Update README.md to provide a comprehensive overview of The Order monorepo, including repository structure, quickstart guide, development workflow, and contribution guidelines.
This commit is contained in:
defiQUG
236
docs/architecture/README.md
Normal file
236
docs/architecture/README.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# Architecture Documentation
|
||||
|
||||
This directory contains architecture documentation for The Order, including Architecture Decision Records (ADRs), data flow diagrams, and threat models.
|
||||
|
||||
## Architecture Decision Records (ADRs)
|
||||
|
||||
Architecture Decision Records document important architectural decisions made in the project. They capture the context, decision, and consequences of key choices.
|
||||
|
||||
### ADR Template
|
||||
|
||||
When creating a new ADR, use the template in `adrs/README.md`.
|
||||
|
||||
### Current ADRs
|
||||
|
||||
- See `adrs/` directory for all ADRs
|
||||
- ADRs are numbered sequentially: `adr-001-*.md`, `adr-002-*.md`, etc.
|
||||
|
||||
### ADR Process
|
||||
|
||||
1. Propose an architectural decision
|
||||
2. Create ADR using template
|
||||
3. Discuss with team
|
||||
4. Record decision in ADR
|
||||
5. Update as needed if decision changes
|
||||
|
||||
## System Architecture
|
||||
|
||||
### High-Level Overview
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ Portal │────▶│ Services │────▶│ Databases │
|
||||
│ Apps │ │ (APIs) │ │ & Storage │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
│ │ │
|
||||
└───────────────────┴────────────────────┘
|
||||
│
|
||||
┌──────┴──────┐
|
||||
│ Identity │
|
||||
│ & Auth │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
### Core Services
|
||||
|
||||
1. **Intake Service**: Document ingestion, OCR, classification
|
||||
2. **Identity Service**: eIDAS/DID, verifiable credentials
|
||||
3. **Finance Service**: Payments, ledgers, rate management
|
||||
4. **Dataroom Service**: Secure VDR, deal rooms
|
||||
5. **MCP Services**: Member and legal management portals
|
||||
|
||||
### Data Flow
|
||||
|
||||
#### Content Intake Flow
|
||||
|
||||
```
|
||||
Document Upload → Intake Service → OCR → Classification →
|
||||
Storage (WORM) → Indexing → Workflow Trigger
|
||||
```
|
||||
|
||||
#### Identity Flow
|
||||
|
||||
```
|
||||
User Request → Identity Service → eIDAS/DID Verification →
|
||||
VC Issuance → Wallet Storage → Access Grant
|
||||
```
|
||||
|
||||
#### Dataroom Flow
|
||||
|
||||
```
|
||||
Deal Creation → Dataroom Service → Document Upload →
|
||||
Access Control (OPA) → Watermarking → Presigned URLs
|
||||
```
|
||||
|
||||
## Technology Stack
|
||||
|
||||
### Frontend
|
||||
|
||||
- **Framework**: Next.js 14+
|
||||
- **UI Library**: React 18+
|
||||
- **Styling**: Tailwind CSS
|
||||
- **Components**: shadcn/ui
|
||||
- **State Management**: Zustand / React Query
|
||||
|
||||
### Backend
|
||||
|
||||
- **Runtime**: Node.js 18+ (TypeScript)
|
||||
- **API Framework**: NestJS / Fastify
|
||||
- **Workflow Engine**: Temporal / AWS Step Functions
|
||||
- **Message Queue**: Redis / Kafka
|
||||
|
||||
### Infrastructure
|
||||
|
||||
- **Container Orchestration**: Kubernetes
|
||||
- **Infrastructure as Code**: Terraform
|
||||
- **CI/CD**: GitHub Actions
|
||||
- **Monitoring**: OpenTelemetry + Grafana
|
||||
- **Logging**: Structured logging (JSON)
|
||||
|
||||
### Data Stores
|
||||
|
||||
- **Primary Database**: PostgreSQL
|
||||
- **Cache**: Redis
|
||||
- **Search**: OpenSearch
|
||||
- **Object Storage**: S3 / GCS (WORM mode)
|
||||
- **Key Management**: KMS / HSM
|
||||
|
||||
### Security
|
||||
|
||||
- **Secrets Management**: SOPS + age / External Secrets
|
||||
- **Identity**: OIDC + DID (did:key, did:web)
|
||||
- **Signing**: eIDAS qualified signatures
|
||||
- **Policy Engine**: OPA (Open Policy Agent)
|
||||
- **SBOM**: Syft
|
||||
- **Vulnerability Scanning**: Grype
|
||||
- **Image Signing**: Cosign
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Security First**: All systems designed with security in mind
|
||||
2. **Immutable Infrastructure**: Infrastructure as code, version controlled
|
||||
3. **Observability**: Comprehensive logging, metrics, and tracing
|
||||
4. **Scalability**: Horizontal scaling, stateless services
|
||||
5. **Resilience**: Graceful degradation, circuit breakers
|
||||
6. **Compliance**: eIDAS, data retention, audit trails
|
||||
|
||||
## Threat Models
|
||||
|
||||
Threat models for each service are located in `threat-models/`. They use STRIDE methodology:
|
||||
|
||||
- **S**poofing
|
||||
- **T**ampering
|
||||
- **R**epudiation
|
||||
- **I**nformation Disclosure
|
||||
- **D**enial of Service
|
||||
- **E**levation of Privilege
|
||||
|
||||
## Data Models
|
||||
|
||||
### Core Entities
|
||||
|
||||
- **User**: Member of The Order
|
||||
- **Document**: Legal document, treaty, etc.
|
||||
- **Deal**: Business transaction with dataroom
|
||||
- **Matter**: Legal matter with associated documents
|
||||
- **Identity**: Digital identity (eIDAS/DID)
|
||||
- **Credential**: Verifiable credential
|
||||
|
||||
### Relationships
|
||||
|
||||
See entity relationship diagrams in `data-models/`.
|
||||
|
||||
## API Design
|
||||
|
||||
### REST APIs
|
||||
|
||||
- Follow RESTful principles
|
||||
- Use OpenAPI/Swagger for documentation
|
||||
- Version APIs: `/v1/`, `/v2/`, etc.
|
||||
- Use proper HTTP status codes
|
||||
- Include request/response examples
|
||||
|
||||
### GraphQL (if applicable)
|
||||
|
||||
- Use GraphQL for complex queries
|
||||
- Implement proper authorization
|
||||
- Use DataLoader for N+1 queries
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
### Environments
|
||||
|
||||
- **Development**: Local development
|
||||
- **Staging**: Pre-production testing
|
||||
- **Production**: Live environment
|
||||
|
||||
### Deployment Strategy
|
||||
|
||||
- **Blue-Green Deployment**: For zero-downtime updates
|
||||
- **Canary Releases**: For gradual rollouts
|
||||
- **Feature Flags**: For controlled feature releases
|
||||
|
||||
### Infrastructure Regions
|
||||
|
||||
- Primary region: EU (for eIDAS compliance)
|
||||
- Secondary region: Backup/DR
|
||||
- CDN: Global distribution for static assets
|
||||
|
||||
## Monitoring & Observability
|
||||
|
||||
### Metrics
|
||||
|
||||
- Application metrics (Prometheus)
|
||||
- Infrastructure metrics (cloud provider)
|
||||
- Business metrics (custom dashboards)
|
||||
|
||||
### Logging
|
||||
|
||||
- Structured logging (JSON)
|
||||
- Centralized log aggregation
|
||||
- Log retention policies
|
||||
|
||||
### Tracing
|
||||
|
||||
- Distributed tracing (OpenTelemetry)
|
||||
- Request flow visualization
|
||||
- Performance analysis
|
||||
|
||||
## Disaster Recovery
|
||||
|
||||
### Backup Strategy
|
||||
|
||||
- Database backups: Daily full, hourly incremental
|
||||
- Object storage: Cross-region replication
|
||||
- Configuration: Version controlled
|
||||
|
||||
### Recovery Procedures
|
||||
|
||||
- RTO (Recovery Time Objective): 4 hours
|
||||
- RPO (Recovery Point Objective): 1 hour
|
||||
- Runbooks in `docs/governance/runbooks/`
|
||||
|
||||
## Future Considerations
|
||||
|
||||
- Multi-cloud deployment
|
||||
- Edge computing for low latency
|
||||
- Machine learning for document classification
|
||||
- Blockchain integration for notarization
|
||||
|
||||
## References
|
||||
|
||||
- [ADR Template](adrs/README.md)
|
||||
- [Threat Models](threat-models/)
|
||||
- [Data Models](data-models/)
|
||||
- [API Documentation](../api/)
|
||||
|
||||
65
docs/architecture/adrs/README.md
Normal file
65
docs/architecture/adrs/README.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# Architecture Decision Records
|
||||
|
||||
This directory contains Architecture Decision Records (ADRs) for The Order project.
|
||||
|
||||
## What is an ADR?
|
||||
|
||||
An Architecture Decision Record is a document that captures an important architectural decision made along with its context and consequences.
|
||||
|
||||
## ADR Format
|
||||
|
||||
Each ADR should follow this structure:
|
||||
|
||||
```markdown
|
||||
# ADR-XXX: [Title]
|
||||
|
||||
## Status
|
||||
[Proposed | Accepted | Deprecated | Superseded]
|
||||
|
||||
## Context
|
||||
Describe the issue that is motivating this decision or change.
|
||||
|
||||
## Decision
|
||||
State the architectural decision that is being made.
|
||||
|
||||
## Consequences
|
||||
Describe the consequences, both positive and negative, of this decision.
|
||||
|
||||
## Alternatives Considered
|
||||
List alternatives that were considered and why they were rejected.
|
||||
|
||||
## References
|
||||
Links to related ADRs, issues, or documentation.
|
||||
```
|
||||
|
||||
## ADR Numbering
|
||||
|
||||
ADRs are numbered sequentially:
|
||||
- `adr-001-*.md`
|
||||
- `adr-002-*.md`
|
||||
- etc.
|
||||
|
||||
## Creating a New ADR
|
||||
|
||||
1. Create a new file: `adr-XXX-short-title.md`
|
||||
2. Use the template above
|
||||
3. Set status to "Proposed"
|
||||
4. Create a PR for discussion
|
||||
5. Update status to "Accepted" after approval
|
||||
|
||||
## ADR Lifecycle
|
||||
|
||||
1. **Proposed**: Initial proposal, under discussion
|
||||
2. **Accepted**: Decision has been made and approved
|
||||
3. **Deprecated**: Decision is no longer followed
|
||||
4. **Superseded**: Replaced by a newer ADR
|
||||
|
||||
## Current ADRs
|
||||
|
||||
*No ADRs yet. Create the first one using the template above.*
|
||||
|
||||
## References
|
||||
|
||||
- [ADR Template](https://github.com/joelparkerhenderson/architecture-decision-record)
|
||||
- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
|
||||
|
||||
Reference in New Issue
Block a user