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 - Complete multi-region architecture
• Sovereignty Landing Zone Summary - 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
• Deployment Guides
• Service Documentation
• Infrastructure Documentation

---

Last Updated: 2025-01-27