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:

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

### 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](adrs/README.md)
- [Threat Models](threat-models/)
- [Data Models](data-models/)
- [API Documentation](../api/)