d-bis/the_order
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: comprehensive project structure improvements and Cloud for Sovereignty landing zone

Browse Source 
- Add Cloud for Sovereignty landing zone architecture and deployment
- Implement complete legal document management system
- Reorganize documentation with improved navigation
- Add infrastructure improvements (Dockerfiles, K8s, monitoring)
- Add operational improvements (graceful shutdown, rate limiting, caching)
- Create comprehensive project structure documentation
- Add Azure deployment automation scripts
- Improve repository navigation and organization
This commit is contained in:
defiQUG
2025-11-13 09:32:55 -08:00
parent 92cc41d26d
commit 6a8582e54d
202 changed files with 22699 additions and 981 deletions
Download Patch File Download Diff File Expand all files Collapse all files

387
docs/architecture/README.md
View File

@@ -1,236 +1,283 @@
# Architecture Documentation
This directory contains architecture documentation for The Order, including Architecture Decision Records (ADRs), data flow diagrams, and threat models.
**Last Updated**: 2025-01-27
**Status**: Comprehensive Architecture Guide
## Architecture Decision Records (ADRs)
## Overview
Architecture Decision Records document important architectural decisions made in the project. They capture the context, decision, and consequences of key choices.
This directory contains comprehensive architecture documentation for The Order platform, including system design, data models, deployment architecture, and architectural decision records (ADRs).
### ADR Template
## Documentation Index
When creating a new ADR, use the template in `adrs/README.md`.
### Core Architecture
- [Cloud for Sovereignty Landing Zone](CLOUD_FOR_SOVEREIGNTY_LANDING_ZONE.md) - Complete multi-region architecture
- [Sovereignty Landing Zone Summary](SOVEREIGNTY_LANDING_ZONE_SUMMARY.md) - Executive summary
### Current ADRs
### System Design
- **Microservices Architecture**: See service documentation in `services/*/README.md`
- **Data Models**: Entity relationships and database schema
- **API Design**: RESTful APIs with OpenAPI/Swagger documentation
- **Security Architecture**: Zero-trust, defense in depth
- See `adrs/` directory for all ADRs
- ADRs are numbered sequentially: `adr-001-*.md`, `adr-002-*.md`, etc.
## Architecture Principles
### ADR Process
### Well-Architected Framework
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
The Order follows Azure Well-Architected Framework principles:
1. **Cost Optimization**
- Right-sized resources
- Reserved instances
- Cost allocation tags
- Budget alerts
2. **Operational Excellence**
- Infrastructure as Code
- Automated deployments
- Centralized logging
- Runbooks and playbooks
3. **Performance Efficiency**
- Regional proximity
- CDN for global delivery
- Auto-scaling
- Performance monitoring
4. **Reliability**
- Multi-region redundancy
- Availability Zones
- Automated failover
- RTO: 4 hours, RPO: 1 hour
5. **Security**
- Zero-trust architecture
- Defense in depth
- Data encryption
- Identity and access management
### Cloud for Sovereignty
- **Data Residency**: All data within specified regions
- **Data Protection**: Customer-managed keys, private endpoints
- **Compliance**: GDPR, eIDAS, regional requirements
- **Operational Control**: Management groups, policy governance
## System Architecture
### High-Level Overview
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Portal │────▶│ Services │────▶│ Databases │
│ Apps │ │ (APIs) │ │ & Storage │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└───────────────────┴────────────────────┘
│
┌──────┴──────┐
│ Identity │
│ & Auth │
└─────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Frontend Applications │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MCP Legal │ │ Portal Public│ │Portal Internal│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ API Gateway / Load Balancer │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Identity │ │ Intake │ │ Finance │
│ Service │ │ Service │ │ Service │
└──────────────┘ └──────────────┘ └──────────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Dataroom │ │Legal Docs │ │ e-Residency │
│ Service │ │ Service │ │ Service │
└──────────────┘ └──────────────┘ └──────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Shared Infrastructure │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │PostgreSQL│ │ Redis │ │OpenSearch│ │ Azure │ │
│ │ │ │ │ │ │ │ Storage │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Core Services
### Service Architecture
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
Each service follows a consistent architecture:
```
Document Upload → Intake Service → OCR → Classification →
Storage (WORM) → Indexing → Workflow Trigger
Service
├── API Layer (Fastify)
│ ├── Routes
│ ├── Middleware
│ └── Validation
├── Service Layer
│ ├── Business Logic
│ ├── External Integrations
│ └── Error Handling
├── Data Layer
│ ├── Database Queries
│ ├── Caching
│ └── Storage
└── Infrastructure
├── Health Checks
├── Metrics
└── Logging
```
#### 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
- **Document**: Legal document
- **Matter**: Legal matter
- **Deal**: Business transaction
- **Payment**: Financial transaction
### 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
See entity relationship diagrams in service-specific documentation.
## Deployment Architecture
### Environments
### Regional Deployment
- **Development**: Local development
- **Staging**: Pre-production testing
- **Production**: Live environment
The Order is deployed across 7 non-US commercial Azure regions:
### Deployment Strategy
1. **West Europe** (Netherlands) - Primary
2. **North Europe** (Ireland) - Secondary
3. **UK South** (London)
4. **Switzerland North** (Zurich)
5. **Norway East** (Oslo)
6. **France Central** (Paris)
7. **Germany West Central** (Frankfurt)
- **Blue-Green Deployment**: For zero-downtime updates
- **Canary Releases**: For gradual rollouts
- **Feature Flags**: For controlled feature releases
### Per-Region Architecture
### Infrastructure Regions
Each region includes:
- Hub Virtual Network (gateway, firewall, management)
- Spoke Virtual Network (application, database, storage)
- Azure Firewall
- Key Vault (with private endpoint)
- Storage Account (with private endpoint)
- Log Analytics Workspace
- AKS Cluster (optional)
- Primary region: EU (for eIDAS compliance)
- Secondary region: Backup/DR
- CDN: Global distribution for static assets
### Network Architecture
- **Hub-and-Spoke**: Centralized connectivity
- **Private Endpoints**: Secure service access
- **Azure Firewall**: Centralized security
- **VNet Peering**: Hub-to-spoke connectivity
## Security Architecture
### Zero-Trust Principles
- **Identity Verification**: Always verify identity
- **Least Privilege**: Minimum required access
- **Network Segmentation**: Isolated networks
- **Encryption**: At rest and in transit
- **Monitoring**: Continuous security monitoring
### Defense in Depth
1. **Perimeter**: Azure Firewall, WAF
2. **Network**: NSGs, Private Endpoints
3. **Application**: Authentication, Authorization
4. **Data**: Encryption, Access Controls
5. **Identity**: MFA, RBAC, PIM
## Monitoring & Observability
### Metrics
- Application metrics (Prometheus)
- Infrastructure metrics (cloud provider)
- Business metrics (custom dashboards)
- Infrastructure metrics (Azure Monitor)
- Business metrics (Custom dashboards)
### Logging
- Structured logging (JSON)
- Centralized log aggregation
- Log retention policies
- Centralized log aggregation (Log Analytics)
- Log retention (90 days production)
### Tracing
- Distributed tracing (OpenTelemetry)
- Request flow visualization
- Performance analysis
## Disaster Recovery
### Backup Strategy
### Strategy
- **RTO**: 4 hours
- **RPO**: 1 hour
- **Primary Region**: West Europe
- **Secondary Region**: North Europe
- **Backup Regions**: Other 5 regions
- Database backups: Daily full, hourly incremental
- Object storage: Cross-region replication
### Backup Strategy
- Database: Daily full, hourly incremental
- Storage: Cross-region replication
- Configuration: Version controlled
### Recovery Procedures
## Technology Stack
- RTO (Recovery Time Objective): 4 hours
- RPO (Recovery Point Objective): 1 hour
- Runbooks in `docs/governance/runbooks/`
### Frontend
- React 18+
- Next.js 14+
- TypeScript
- Tailwind CSS
- Material-UI
## Future Considerations
### Backend
- Node.js 18+
- TypeScript
- Fastify
- PostgreSQL
- Redis
- Multi-cloud deployment
- Edge computing for low latency
- Machine learning for document classification
- Blockchain integration for notarization
### Infrastructure
- Azure (non-US commercial)
- Kubernetes
- Terraform
- Docker
## References
### Monitoring
- Prometheus
- Grafana
- OpenTelemetry
- Log Analytics
- [ADR Template](adrs/README.md)
- [Threat Models](threat-models/)
- [Data Models](data-models/)
- [API Documentation](../api/)
## Design Decisions
### Why Microservices?
- Independent scaling
- Technology diversity
- Team autonomy
- Fault isolation
### Why Azure (Non-US)?
- Data sovereignty requirements
- GDPR compliance
- Regional data residency
- Cloud for Sovereignty
### Why Kubernetes?
- Container orchestration
- Auto-scaling
- Rolling updates
- Service discovery
## Related Documentation
- [Cloud for Sovereignty Landing Zone](CLOUD_FOR_SOVEREIGNTY_LANDING_ZONE.md)
- [Deployment Guides](../deployment/README.md)
- [Service Documentation](../../services/*/README.md)
- [Infrastructure Documentation](../../infra/README.md)
---
**Last Updated**: 2025-01-27