the_order/docs/architecture/README.md

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:

• Spoofing
• Tampering
• Repudiation
• Information Disclosure
• Denial of Service
• Elevation 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
• Threat Models
• Data Models
• API Documentation