the_order/docs/architecture/README.md

# Architecture Documentation

**Last Updated**: 2025-01-27  
**Status**: Comprehensive Architecture Guide

## Overview

This directory contains comprehensive architecture documentation for The Order platform, including system design, data models, deployment architecture, and architectural decision records (ADRs).

## Documentation Index

### 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

### 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

## Architecture Principles

### Well-Architected Framework

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

```
┌─────────────────────────────────────────────────────────────┐
│                    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  │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
```

### Service Architecture

Each service follows a consistent architecture:

```
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
```

## Data Models

### Core Entities

- **User**: Member of The Order
- **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 service-specific documentation.

## Deployment Architecture

### Regional Deployment

The Order is deployed across 7 non-US commercial Azure regions:

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)

### Per-Region Architecture

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)

### 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 (Azure Monitor)
- Business metrics (Custom dashboards)

### Logging
- Structured logging (JSON)
- Centralized log aggregation (Log Analytics)
- Log retention (90 days production)

### Tracing
- Distributed tracing (OpenTelemetry)
- Request flow visualization
- Performance analysis

## Disaster Recovery

### Strategy
- **RTO**: 4 hours
- **RPO**: 1 hour
- **Primary Region**: West Europe
- **Secondary Region**: North Europe
- **Backup Regions**: Other 5 regions

### Backup Strategy
- Database: Daily full, hourly incremental
- Storage: Cross-region replication
- Configuration: Version controlled

## Technology Stack

### Frontend
- React 18+
- Next.js 14+
- TypeScript
- Tailwind CSS
- Material-UI

### Backend
- Node.js 18+
- TypeScript
- Fastify
- PostgreSQL
- Redis

### Infrastructure
- Azure (non-US commercial)
- Kubernetes
- Terraform
- Docker

### Monitoring
- Prometheus
- Grafana
- OpenTelemetry
- Log Analytics

## 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