feat: comprehensive project structure improvements and Cloud for Sovereignty landing zone
- 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
365
docs/architecture/CLOUD_FOR_SOVEREIGNTY_LANDING_ZONE.md
Normal file
365
docs/architecture/CLOUD_FOR_SOVEREIGNTY_LANDING_ZONE.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# Cloud for Sovereignty Landing Zone Architecture
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
**Management Group**: SOVEREIGN-ORDER-OF-HOSPITALLERS
|
||||
**Framework**: Azure Well-Architected Framework + Cloud for Sovereignty
|
||||
**Status**: Planning Phase
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document outlines a comprehensive Cloud for Sovereignty landing zone architecture for The Order, designed using Azure Well-Architected Framework principles. The architecture spans all non-US Azure commercial regions to ensure data sovereignty, compliance, and operational resilience.
|
||||
|
||||
## Management Group Hierarchy
|
||||
|
||||
```
|
||||
SOVEREIGN-ORDER-OF-HOSPITALLERS (Root)
|
||||
├── Landing Zones
|
||||
│ ├── Platform (Platform team managed)
|
||||
│ ├── Sandbox (Development/testing)
|
||||
│ └── Workloads (Application workloads)
|
||||
├── Management
|
||||
│ ├── Identity (Identity and access management)
|
||||
│ ├── Security (Security operations)
|
||||
│ └── Monitoring (Centralized monitoring)
|
||||
└── Connectivity
|
||||
├── Hub Networks (Regional hubs)
|
||||
└── Spoke Networks (Workload networks)
|
||||
```
|
||||
|
||||
## Well-Architected Framework Pillars
|
||||
|
||||
### 1. Cost Optimization
|
||||
|
||||
**Principles:**
|
||||
- Right-sizing resources per region
|
||||
- Reserved instances for predictable workloads
|
||||
- Spot instances for non-critical workloads
|
||||
- Cost allocation tags for chargeback
|
||||
- Budget alerts and governance
|
||||
|
||||
**Implementation:**
|
||||
- Cost Management budgets per management group
|
||||
- Azure Advisor recommendations
|
||||
- Resource tagging strategy
|
||||
- Reserved capacity planning
|
||||
|
||||
### 2. Operational Excellence
|
||||
|
||||
**Principles:**
|
||||
- Infrastructure as Code (Terraform)
|
||||
- Automated deployments (GitHub Actions)
|
||||
- Centralized logging and monitoring
|
||||
- Runbooks and playbooks
|
||||
- Change management processes
|
||||
|
||||
**Implementation:**
|
||||
- Terraform modules for repeatable deployments
|
||||
- CI/CD pipelines for infrastructure
|
||||
- Azure Monitor and Log Analytics
|
||||
- Azure Automation for runbooks
|
||||
|
||||
### 3. Performance Efficiency
|
||||
|
||||
**Principles:**
|
||||
- Regional proximity for low latency
|
||||
- CDN for global content delivery
|
||||
- Auto-scaling for dynamic workloads
|
||||
- Performance monitoring and optimization
|
||||
- Database query optimization
|
||||
|
||||
**Implementation:**
|
||||
- Multi-region deployment
|
||||
- Azure Front Door for global routing
|
||||
- Azure CDN for static assets
|
||||
- Application Insights for performance tracking
|
||||
|
||||
### 4. Reliability
|
||||
|
||||
**Principles:**
|
||||
- Multi-region redundancy
|
||||
- Availability Zones within regions
|
||||
- Automated failover
|
||||
- Disaster recovery procedures
|
||||
- Health monitoring and alerting
|
||||
|
||||
**Implementation:**
|
||||
- Primary and secondary regions
|
||||
- Geo-replication for storage
|
||||
- Traffic Manager for DNS failover
|
||||
- RTO: 4 hours, RPO: 1 hour
|
||||
|
||||
### 5. Security
|
||||
|
||||
**Principles:**
|
||||
- Zero-trust architecture
|
||||
- Defense in depth
|
||||
- Data encryption at rest and in transit
|
||||
- Identity and access management
|
||||
- Security monitoring and threat detection
|
||||
|
||||
**Implementation:**
|
||||
- Azure AD for identity
|
||||
- Key Vault for secrets management
|
||||
- Network Security Groups and Azure Firewall
|
||||
- Microsoft Defender for Cloud
|
||||
- Azure Sentinel for SIEM
|
||||
|
||||
## Cloud for Sovereignty Requirements
|
||||
|
||||
### Data Residency
|
||||
|
||||
- **Requirement**: All data must remain within specified regions
|
||||
- **Implementation**:
|
||||
- Resource location policies
|
||||
- Storage account geo-replication controls
|
||||
- Database replication restrictions
|
||||
|
||||
### Data Protection
|
||||
|
||||
- **Requirement**: Encryption and access controls
|
||||
- **Implementation**:
|
||||
- Customer-managed keys (CMK)
|
||||
- Azure Key Vault with HSM
|
||||
- Private endpoints for services
|
||||
|
||||
### Compliance
|
||||
|
||||
- **Requirement**: GDPR, eIDAS, and regional compliance
|
||||
- **Implementation**:
|
||||
- Compliance policies and initiatives
|
||||
- Audit logging and retention
|
||||
- Data classification and labeling
|
||||
|
||||
### Operational Control
|
||||
|
||||
- **Requirement**: Sovereign operations and control
|
||||
- **Implementation**:
|
||||
- Management group hierarchy
|
||||
- Policy-based governance
|
||||
- Role-based access control (RBAC)
|
||||
|
||||
## Regional Architecture
|
||||
|
||||
### Supported Regions (Non-US Commercial)
|
||||
|
||||
1. **West Europe** (Netherlands) - Primary
|
||||
2. **North Europe** (Ireland) - Secondary
|
||||
3. **UK South** (London) - UK workloads
|
||||
4. **Switzerland North** (Zurich) - Swiss workloads
|
||||
5. **Norway East** (Oslo) - Nordic workloads
|
||||
6. **France Central** (Paris) - French workloads
|
||||
7. **Germany West Central** (Frankfurt) - German workloads
|
||||
|
||||
### Regional Deployment Pattern
|
||||
|
||||
Each region follows the same pattern:
|
||||
|
||||
```
|
||||
Region
|
||||
├── Hub Network (VNet)
|
||||
│ ├── Gateway Subnet (VPN/ExpressRoute)
|
||||
│ ├── Azure Firewall Subnet
|
||||
│ └── Management Subnet
|
||||
├── Spoke Networks (Workloads)
|
||||
│ ├── Application Subnet
|
||||
│ ├── Database Subnet
|
||||
│ └── Storage Subnet
|
||||
├── Key Vault (Regional)
|
||||
├── Storage Account (Regional)
|
||||
├── Database (Regional)
|
||||
└── AKS Cluster (Regional)
|
||||
```
|
||||
|
||||
## Landing Zone Components
|
||||
|
||||
### 1. Identity and Access Management
|
||||
|
||||
- **Azure AD Tenant**: Single tenant per sovereignty requirement
|
||||
- **Management Groups**: Hierarchical organization
|
||||
- **RBAC**: Role-based access control
|
||||
- **Conditional Access**: Location-based policies
|
||||
- **Privileged Identity Management**: Just-in-time access
|
||||
|
||||
### 2. Network Architecture
|
||||
|
||||
- **Hub-and-Spoke**: Centralized connectivity
|
||||
- **Azure Firewall**: Centralized security
|
||||
- **Private Endpoints**: Secure service access
|
||||
- **VPN/ExpressRoute**: Hybrid connectivity
|
||||
- **Network Watcher**: Monitoring and diagnostics
|
||||
|
||||
### 3. Security and Compliance
|
||||
|
||||
- **Microsoft Defender for Cloud**: Security posture management
|
||||
- **Azure Sentinel**: SIEM and SOAR
|
||||
- **Key Vault**: Secrets and certificate management
|
||||
- **Azure Policy**: Governance and compliance
|
||||
- **Azure Blueprints**: Standardized deployments
|
||||
|
||||
### 4. Monitoring and Logging
|
||||
|
||||
- **Log Analytics Workspaces**: Regional workspaces
|
||||
- **Application Insights**: Application monitoring
|
||||
- **Azure Monitor**: Infrastructure monitoring
|
||||
- **Azure Service Health**: Service status
|
||||
- **Azure Advisor**: Best practice recommendations
|
||||
|
||||
### 5. Backup and Disaster Recovery
|
||||
|
||||
- **Azure Backup**: Centralized backup
|
||||
- **Azure Site Recovery**: DR orchestration
|
||||
- **Geo-replication**: Cross-region replication
|
||||
- **Backup Vault**: Regional backup storage
|
||||
|
||||
### 6. Governance
|
||||
|
||||
- **Azure Policy**: Resource compliance
|
||||
- **Azure Blueprints**: Standardized environments
|
||||
- **Cost Management**: Budget and cost tracking
|
||||
- **Resource Tags**: Organization and chargeback
|
||||
- **Management Groups**: Hierarchical governance
|
||||
|
||||
## Resource Organization
|
||||
|
||||
### Naming Convention
|
||||
|
||||
```
|
||||
{provider}-{region}-{resource}-{env}-{purpose}
|
||||
|
||||
Examples:
|
||||
- az-we-rg-dev-main (Resource Group)
|
||||
- azwesadevdata (Storage Account)
|
||||
- az-we-kv-dev-main (Key Vault)
|
||||
- az-we-aks-dev-main (AKS Cluster)
|
||||
```
|
||||
|
||||
### Tagging Strategy
|
||||
|
||||
Required tags for all resources:
|
||||
- `Environment`: dev, stage, prod
|
||||
- `Project`: the-order
|
||||
- `Region`: westeurope, northeurope, etc.
|
||||
- `ManagedBy`: terraform
|
||||
- `CostCenter`: engineering
|
||||
- `Owner`: platform-team
|
||||
- `DataClassification`: public, internal, confidential, restricted
|
||||
- `Compliance`: gdpr, eidas, regional
|
||||
|
||||
## Deployment Strategy
|
||||
|
||||
### Phase 1: Foundation (Weeks 1-2)
|
||||
- Management group hierarchy
|
||||
- Identity and access management
|
||||
- Core networking (hub networks)
|
||||
- Key Vault setup
|
||||
- Log Analytics workspaces
|
||||
|
||||
### Phase 2: Regional Deployment (Weeks 3-6)
|
||||
- Deploy to primary region (West Europe)
|
||||
- Deploy to secondary region (North Europe)
|
||||
- Set up geo-replication
|
||||
- Configure monitoring
|
||||
|
||||
### Phase 3: Multi-Region Expansion (Weeks 7-10)
|
||||
- Deploy to remaining regions
|
||||
- Configure regional failover
|
||||
- Set up CDN endpoints
|
||||
- Implement traffic routing
|
||||
|
||||
### Phase 4: Workload Migration (Weeks 11-14)
|
||||
- Migrate applications
|
||||
- Configure application networking
|
||||
- Set up application monitoring
|
||||
- Performance optimization
|
||||
|
||||
### Phase 5: Optimization (Weeks 15-16)
|
||||
- Cost optimization
|
||||
- Performance tuning
|
||||
- Security hardening
|
||||
- Documentation and runbooks
|
||||
|
||||
## Cost Estimation
|
||||
|
||||
### Per Region (Monthly)
|
||||
|
||||
- **Networking**: $500-1,000
|
||||
- **Compute (AKS)**: $1,000-3,000
|
||||
- **Storage**: $200-500
|
||||
- **Database**: $500-2,000
|
||||
- **Monitoring**: $200-500
|
||||
- **Security**: $300-800
|
||||
- **Backup**: $100-300
|
||||
|
||||
**Total per region**: $2,800-8,100/month
|
||||
|
||||
### Multi-Region (7 regions)
|
||||
- **Development**: ~$20,000/month
|
||||
- **Production**: ~$50,000/month
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Data Sovereignty
|
||||
- All data stored within specified regions
|
||||
- No cross-region data transfer without encryption
|
||||
- Customer-managed keys for encryption
|
||||
- Private endpoints for all services
|
||||
|
||||
### Access Control
|
||||
- Zero-trust network architecture
|
||||
- Conditional access policies
|
||||
- Multi-factor authentication
|
||||
- Just-in-time access
|
||||
- Privileged access management
|
||||
|
||||
### Compliance
|
||||
- GDPR compliance
|
||||
- eIDAS compliance
|
||||
- Regional data protection laws
|
||||
- Audit logging (90 days retention)
|
||||
- Data classification and handling
|
||||
|
||||
## Monitoring and Alerting
|
||||
|
||||
### Key Metrics
|
||||
- Resource health
|
||||
- Cost trends
|
||||
- Security alerts
|
||||
- Performance metrics
|
||||
- Compliance status
|
||||
|
||||
### Alert Channels
|
||||
- Email notifications
|
||||
- Azure Monitor alerts
|
||||
- Microsoft Teams integration
|
||||
- PagerDuty (for critical alerts)
|
||||
|
||||
## Disaster Recovery
|
||||
|
||||
### RTO/RPO Targets
|
||||
- **RTO**: 4 hours
|
||||
- **RPO**: 1 hour
|
||||
|
||||
### DR Strategy
|
||||
- Primary region: West Europe
|
||||
- Secondary region: North Europe
|
||||
- Backup regions: Other regional hubs
|
||||
- Automated failover for critical services
|
||||
- Manual failover for non-critical services
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review and Approve Architecture**
|
||||
2. **Set Up Management Group Hierarchy**
|
||||
3. **Deploy Foundation Infrastructure**
|
||||
4. **Configure Regional Networks**
|
||||
5. **Deploy Regional Resources**
|
||||
6. **Set Up Monitoring and Alerting**
|
||||
7. **Implement Security Controls**
|
||||
8. **Migrate Workloads**
|
||||
9. **Optimize and Tune**
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
**Next Review**: After Phase 1 completion
|
||||
|
||||
@@ -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
|
||||
|
||||
189
docs/architecture/SOVEREIGNTY_LANDING_ZONE_SUMMARY.md
Normal file
189
docs/architecture/SOVEREIGNTY_LANDING_ZONE_SUMMARY.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# Cloud for Sovereignty Landing Zone - Executive Summary
|
||||
|
||||
**Date**: 2025-01-27
|
||||
**Management Group**: SOVEREIGN-ORDER-OF-HOSPITALLERS
|
||||
**Status**: Architecture Complete - Ready for Deployment
|
||||
|
||||
## Overview
|
||||
|
||||
A comprehensive Cloud for Sovereignty landing zone architecture designed using Azure Well-Architected Framework principles, spanning all non-US commercial Azure regions to ensure data sovereignty, compliance, and operational resilience.
|
||||
|
||||
## Key Metrics
|
||||
|
||||
- **Regions**: 7 non-US commercial Azure regions
|
||||
- **Management Groups**: 11 hierarchical groups
|
||||
- **Policies**: 5 compliance policies + 1 initiative
|
||||
- **Virtual Networks**: 14 (7 hub + 7 spoke)
|
||||
- **Subnets**: 42 total
|
||||
- **Security**: 7 Azure Firewalls, 14 private endpoints
|
||||
- **Estimated Cost**: $10,850-20,000/month (depending on environment)
|
||||
|
||||
## Well-Architected Framework Compliance
|
||||
|
||||
### ✅ Cost Optimization
|
||||
- Right-sized resources per region
|
||||
- Reserved instance planning
|
||||
- Cost allocation tags
|
||||
- Budget alerts and governance
|
||||
|
||||
### ✅ Operational Excellence
|
||||
- Infrastructure as Code (Terraform)
|
||||
- Automated deployments
|
||||
- Centralized logging
|
||||
- Runbooks and playbooks
|
||||
|
||||
### ✅ Performance Efficiency
|
||||
- Regional proximity for low latency
|
||||
- CDN for global content delivery
|
||||
- Auto-scaling capabilities
|
||||
- Performance monitoring
|
||||
|
||||
### ✅ Reliability
|
||||
- Multi-region redundancy
|
||||
- Availability Zones
|
||||
- Automated failover
|
||||
- RTO: 4 hours, RPO: 1 hour
|
||||
|
||||
### ✅ Security
|
||||
- Zero-trust architecture
|
||||
- Defense in depth
|
||||
- Data encryption (at rest and in transit)
|
||||
- Identity and access management
|
||||
- Security monitoring
|
||||
|
||||
## Cloud for Sovereignty Features
|
||||
|
||||
### Data Residency
|
||||
- All data remains within specified regions
|
||||
- Resource location policies enforced
|
||||
- Storage geo-replication controls
|
||||
|
||||
### Data Protection
|
||||
- Customer-managed keys (CMK)
|
||||
- Azure Key Vault with HSM
|
||||
- Private endpoints for all services
|
||||
|
||||
### Compliance
|
||||
- GDPR compliance
|
||||
- eIDAS compliance
|
||||
- Regional compliance requirements
|
||||
- Audit logging (90 days retention)
|
||||
|
||||
### Operational Control
|
||||
- Management group hierarchy
|
||||
- Policy-based governance
|
||||
- Role-based access control (RBAC)
|
||||
|
||||
## Regional Deployment
|
||||
|
||||
### Supported Regions
|
||||
|
||||
1. **West Europe** (Netherlands) - Primary region
|
||||
2. **North Europe** (Ireland) - Secondary region
|
||||
3. **UK South** (London) - UK workloads
|
||||
4. **Switzerland North** (Zurich) - Swiss workloads
|
||||
5. **Norway East** (Oslo) - Nordic workloads
|
||||
6. **France Central** (Paris) - French workloads
|
||||
7. **Germany West Central** (Frankfurt) - German workloads
|
||||
|
||||
### Per-Region Components
|
||||
|
||||
- Hub Virtual Network (gateway, firewall, management subnets)
|
||||
- Spoke Virtual Network (application, database, storage subnets)
|
||||
- Azure Firewall (Standard SKU)
|
||||
- Key Vault (Premium SKU with private endpoint)
|
||||
- Storage Account (with private endpoint)
|
||||
- Log Analytics Workspace
|
||||
|
||||
## Management Group Hierarchy
|
||||
|
||||
```
|
||||
SOVEREIGN-ORDER-OF-HOSPITALLERS
|
||||
├── Landing Zones
|
||||
│ ├── Platform
|
||||
│ ├── Sandbox
|
||||
│ └── Workloads
|
||||
├── Management
|
||||
│ ├── Identity
|
||||
│ ├── Security
|
||||
│ └── Monitoring
|
||||
└── Connectivity
|
||||
├── Hub Networks
|
||||
└── Spoke Networks
|
||||
```
|
||||
|
||||
## Compliance Policies
|
||||
|
||||
1. **Allowed Locations**: Restricts to non-US commercial regions
|
||||
2. **Deny US Regions**: Explicitly denies US regions
|
||||
3. **Require Data Residency Tag**: Tracks data residency
|
||||
4. **Require Encryption at Rest**: Customer-managed keys
|
||||
5. **Require Resource Tags**: Governance and cost management
|
||||
|
||||
## Deployment Phases
|
||||
|
||||
### Phase 1: Foundation (Weeks 1-2)
|
||||
- Management group hierarchy
|
||||
- Identity and access management
|
||||
- Core networking
|
||||
- Key Vault setup
|
||||
- Log Analytics workspaces
|
||||
|
||||
### Phase 2: Regional Deployment (Weeks 3-6)
|
||||
- Primary region (West Europe)
|
||||
- Secondary region (North Europe)
|
||||
- Geo-replication
|
||||
- Monitoring setup
|
||||
|
||||
### Phase 3: Multi-Region Expansion (Weeks 7-10)
|
||||
- Remaining 5 regions
|
||||
- Regional failover
|
||||
- CDN endpoints
|
||||
- Traffic routing
|
||||
|
||||
### Phase 4: Workload Migration (Weeks 11-14)
|
||||
- Application migration
|
||||
- Application networking
|
||||
- Application monitoring
|
||||
- Performance optimization
|
||||
|
||||
### Phase 5: Optimization (Weeks 15-16)
|
||||
- Cost optimization
|
||||
- Performance tuning
|
||||
- Security hardening
|
||||
- Documentation
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Load environment
|
||||
source infra/scripts/azure-load-env.sh
|
||||
|
||||
# 2. Deploy landing zone
|
||||
./infra/scripts/deploy-sovereignty-landing-zone.sh
|
||||
|
||||
# 3. Verify deployment
|
||||
az group list --query "[?contains(name, 'az-')]"
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- **Architecture**: `docs/architecture/CLOUD_FOR_SOVEREIGNTY_LANDING_ZONE.md`
|
||||
- **Deployment Guide**: `docs/deployment/azure/SOVEREIGNTY_LANDING_ZONE_DEPLOYMENT.md`
|
||||
- **Module Docs**: `infra/terraform/modules/regional-landing-zone/README.md`
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- ✅ All 7 regions deployed
|
||||
- ✅ Management group hierarchy established
|
||||
- ✅ Compliance policies enforced
|
||||
- ✅ Private endpoints configured
|
||||
- ✅ Monitoring active
|
||||
- ✅ Cost tracking enabled
|
||||
- ✅ Security hardened
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
**Next Review**: After Phase 1 deployment
|
||||
|
||||
Reference in New Issue
Block a user