# nwf007/statement-delivery-system architecture

> Architecture diagram of the GitHub repository nwf007/statement-delivery-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nwf007/statement-delivery-system
- Repository: https://github.com/nwf007/statement-delivery-system

## Overview

The platform separates burst-oriented statement generation from customer-facing delivery: a run is planned, ledger data becomes a rendered and encrypted statement, and customers later retrieve it through an authenticated API and a single-use download gateway. Retention and erasure form a separate lifecycle, with legal holds and key destruction governing whether encrypted objects can be purged. The graph reflects README capabilities and the supplied source excerpts; some endpoint-to-repository wiring is inferred only where documented behavior supports it, so uncertain links are omitted.

Main entry points: [`src/Services/Delivery.Api/Program.cs`](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Program.cs) (Delivery API), [`src/Services/Generation.Worker/RenderPipeline.cs`](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Generation.Worker/RenderPipeline.cs) (Render pipeline), [`src/Services/Download.Gateway/Downloads/DownloadEndpoints.cs`](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Download.Gateway/Downloads/DownloadEndpoints.cs) (Download endpoints), [`src/BuildingBlocks/ServiceDefaults/Storage/StatementContentStore.cs`](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/ServiceDefaults/Storage/StatementContentStore.cs) (Encrypted content store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Generation"]
  node_generation_worker["Generation worker<br/>[Program.cs]"]
  node_run_orchestrator["Run orchestrator"]
  node_render_worker["Render worker"]
  node_render_pipeline["Render pipeline<br/>[RenderPipeline.cs]"]
end

subgraph group_delivery["Delivery"]
  node_delivery_api["Delivery API<br/>[Program.cs]"]
  node_statement_endpoints["Statement endpoints"]
  node_link_endpoints["Link endpoints"]
  node_gateway["Download gateway<br/>[Program.cs]"]
  node_download_endpoints["Download endpoints"]
end

subgraph group_retention["Retention"]
  node_retention_worker["Retention worker<br/>[Program.cs]"]
  node_retention_sweep["Retention sweep"]
  node_retention_decision["Retention decision"]
  node_retention_api["Retention endpoints"]
  node_hold_api["Legal hold endpoints"]
  node_restore_api["Restore endpoints"]
  node_erasure["Erasure executor<br/>[ErasureExecutor.cs]"]
  node_object_admin["Object administration"]
end

subgraph group_shared["Security and persistence"]
  node_renderer["PDF renderer"]
  node_statement_domain["Statement model<br/>[Statement.cs]"]
  node_content_store["Encrypted content store"]
  node_crypto["Framed encryption"]
  node_key_service["Customer key service"]
  node_key_provider["Key provider<br/>[KeyProvider.cs]"]
  node_object_store[("Object storage<br/>[ObjectStorage.cs]")]
  node_statement_reads["Statement reads"]
  node_statement_writes["Statement writes"]
  node_runs["Run repository"]
  node_tokens["Download tokens"]
end

subgraph group_audit["Audit"]
  node_audit_api["Audit verification API"]
end

node_operator(("Operator"))
node_customer(("Customer"))
node_ledger["Core ledger"]
node_mock_ledger["Mock ledger API<br/>[Program.cs]"]
node_postgres[("PostgreSQL")]

node_customer -->|"calls"| node_delivery_api
node_delivery_api -->|"routes"| node_statement_endpoints
node_delivery_api -->|"routes"| node_link_endpoints
node_delivery_api -->|"routes"| node_retention_api
node_delivery_api -->|"routes"| node_hold_api
node_delivery_api -->|"routes"| node_restore_api
node_delivery_api -->|"routes"| node_audit_api
node_statement_endpoints -->|"reads"| node_statement_reads
node_link_endpoints -->|"reads"| node_statement_reads
node_link_endpoints -->|"creates"| node_tokens
node_customer -->|"redeems link"| node_gateway
node_gateway -->|"routes"| node_download_endpoints
node_download_endpoints -->|"consumes"| node_tokens
node_download_endpoints -->|"loads metadata"| node_statement_reads
node_download_endpoints -->|"streams content"| node_content_store
node_content_store -->|"reads and writes"| node_object_store
node_content_store -->|"encrypts and decrypts"| node_crypto
node_crypto -->|"uses keys"| node_key_service
node_key_service -->|"wraps keys"| node_key_provider
node_generation_worker -->|"hosts"| node_run_orchestrator
node_generation_worker -->|"hosts"| node_render_worker
node_run_orchestrator -->|"plans runs"| node_runs
node_run_orchestrator -->|"acquires lease"| node_postgres
node_render_worker -->|"processes claims"| node_render_pipeline
node_render_pipeline -->|"requests transactions"| node_ledger
node_render_pipeline -->|"renders document"| node_renderer
node_render_pipeline -->|"writes encrypted content"| node_content_store
node_render_pipeline -->|"publishes statement"| node_statement_writes
node_statement_writes -->|"writes"| node_postgres
node_statement_reads -->|"reads"| node_postgres
node_runs -->|"reads and writes"| node_postgres
node_tokens -->|"reads and writes"| node_postgres
node_operator -->|"requests erasure"| node_retention_api
node_operator -->|"manages holds"| node_hold_api
node_operator -->|"requests restore"| node_restore_api
node_retention_api -->|"records request"| node_postgres
node_hold_api -->|"sets object holds"| node_object_admin
node_restore_api -->|"records request"| node_postgres
node_retention_worker -->|"hosts"| node_retention_sweep
node_retention_sweep -->|"decides disposition"| node_retention_decision
node_retention_worker -->|"executes erasure"| node_erasure
node_erasure -->|"destroys customer key"| node_key_service
node_erasure -->|"manages objects"| node_object_admin
node_object_admin -->|"administers locks"| node_object_store
node_retention_sweep -->|"loads candidates"| node_postgres
node_audit_api -->|"verifies chains"| node_postgres
node_mock_ledger -.->|"implements locally"| node_ledger

click node_delivery_api "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Program.cs"
click node_statement_endpoints "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Statements/StatementEndpoints.cs"
click node_link_endpoints "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Downloads/DownloadLinkEndpoints.cs"
click node_gateway "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Download.Gateway/Program.cs"
click node_download_endpoints "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Download.Gateway/Downloads/DownloadEndpoints.cs"
click node_generation_worker "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Generation.Worker/Program.cs"
click node_run_orchestrator "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Generation.Worker/RunOrchestratorService.cs"
click node_render_worker "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Generation.Worker/RenderWorkerService.cs"
click node_render_pipeline "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Generation.Worker/RenderPipeline.cs"
click node_mock_ledger "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/MockLedger.Api/Program.cs"
click node_renderer "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Rendering/QuestPdfStatementRenderer.cs"
click node_statement_domain "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Domain/Statements/Statement.cs"
click node_content_store "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/ServiceDefaults/Storage/StatementContentStore.cs"
click node_crypto "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Crypto/Framing/FramedAeadCipher.cs"
click node_key_service "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Crypto/Keys/CustomerKeyService.cs"
click node_key_provider "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Crypto/Keys/KeyProvider.cs"
click node_object_store "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/ServiceDefaults/Storage/ObjectStorage.cs"
click node_statement_reads "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Persistence/Repositories/StatementReadRepository.cs"
click node_statement_writes "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Persistence/Repositories/StatementWriteRepository.cs"
click node_runs "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Persistence/Runs/StatementRunRepository.cs"
click node_tokens "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Persistence/Tokens/DownloadTokenRepository.cs"
click node_retention_worker "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Retention.Worker/Program.cs"
click node_retention_sweep "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Retention.Worker/RetentionSweepService.cs"
click node_retention_decision "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Domain/Retention/RetentionDecisionEngine.cs"
click node_retention_api "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Retention/ErasureEndpoints.cs"
click node_hold_api "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Retention/LegalHoldEndpoints.cs"
click node_restore_api "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Retention/RestoreEndpoints.cs"
click node_erasure "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Retention.Worker/ErasureExecutor.cs"
click node_object_admin "https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/ServiceDefaults/Storage/ObjectAdminStore.cs"
click node_audit_api "https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Auditing/AuditVerifyEndpoint.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_generation_worker,node_run_orchestrator,node_render_worker,node_render_pipeline toneBlue
class node_delivery_api,node_statement_endpoints,node_link_endpoints,node_gateway,node_download_endpoints,node_postgres toneAmber
class node_retention_worker,node_retention_sweep,node_retention_decision,node_retention_api,node_hold_api,node_restore_api,node_erasure,node_object_admin,node_mock_ledger toneMint
class node_renderer,node_statement_domain,node_content_store,node_crypto,node_key_service,node_key_provider,node_object_store,node_statement_reads,node_statement_writes,node_runs,node_tokens toneRose
class node_audit_api,node_operator,node_customer,node_ledger toneIndigo
```

## Components

### Generation

- [Generation worker](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Generation.Worker/Program.cs): `src/Services/Generation.Worker/Program.cs`
- [Run orchestrator](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Generation.Worker/RunOrchestratorService.cs): `src/Services/Generation.Worker/RunOrchestratorService.cs`
- [Render worker](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Generation.Worker/RenderWorkerService.cs): `src/Services/Generation.Worker/RenderWorkerService.cs`
- [Render pipeline](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Generation.Worker/RenderPipeline.cs): `src/Services/Generation.Worker/RenderPipeline.cs`

### Delivery

- [Delivery API](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Program.cs): `src/Services/Delivery.Api/Program.cs`
- [Statement endpoints](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Statements/StatementEndpoints.cs): `src/Services/Delivery.Api/Statements/StatementEndpoints.cs`
- [Link endpoints](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Downloads/DownloadLinkEndpoints.cs): `src/Services/Delivery.Api/Downloads/DownloadLinkEndpoints.cs`
- [Download gateway](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Download.Gateway/Program.cs): `src/Services/Download.Gateway/Program.cs`
- [Download endpoints](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Download.Gateway/Downloads/DownloadEndpoints.cs): `src/Services/Download.Gateway/Downloads/DownloadEndpoints.cs`

### Retention

- [Retention worker](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Retention.Worker/Program.cs): `src/Services/Retention.Worker/Program.cs`
- [Retention sweep](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Retention.Worker/RetentionSweepService.cs): `src/Services/Retention.Worker/RetentionSweepService.cs`
- [Retention decision](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Domain/Retention/RetentionDecisionEngine.cs): `src/BuildingBlocks/Domain/Retention/RetentionDecisionEngine.cs`
- [Retention endpoints](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Retention/ErasureEndpoints.cs): `src/Services/Delivery.Api/Retention/ErasureEndpoints.cs`
- [Legal hold endpoints](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Retention/LegalHoldEndpoints.cs): `src/Services/Delivery.Api/Retention/LegalHoldEndpoints.cs`
- [Restore endpoints](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Retention/RestoreEndpoints.cs): `src/Services/Delivery.Api/Retention/RestoreEndpoints.cs`
- [Erasure executor](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Retention.Worker/ErasureExecutor.cs): `src/Services/Retention.Worker/ErasureExecutor.cs`
- [Object administration](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/ServiceDefaults/Storage/ObjectAdminStore.cs): `src/BuildingBlocks/ServiceDefaults/Storage/ObjectAdminStore.cs`

### Security and persistence

- [PDF renderer](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Rendering/QuestPdfStatementRenderer.cs): `src/BuildingBlocks/Rendering/QuestPdfStatementRenderer.cs`
- [Statement model](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Domain/Statements/Statement.cs): `src/BuildingBlocks/Domain/Statements/Statement.cs`
- [Encrypted content store](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/ServiceDefaults/Storage/StatementContentStore.cs): `src/BuildingBlocks/ServiceDefaults/Storage/StatementContentStore.cs`
- [Framed encryption](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Crypto/Framing/FramedAeadCipher.cs): `src/BuildingBlocks/Crypto/Framing/FramedAeadCipher.cs`
- [Customer key service](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Crypto/Keys/CustomerKeyService.cs): `src/BuildingBlocks/Crypto/Keys/CustomerKeyService.cs`
- [Key provider](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Crypto/Keys/KeyProvider.cs): `src/BuildingBlocks/Crypto/Keys/KeyProvider.cs`
- [Object storage](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/ServiceDefaults/Storage/ObjectStorage.cs): `src/BuildingBlocks/ServiceDefaults/Storage/ObjectStorage.cs`
- [Statement reads](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Persistence/Repositories/StatementReadRepository.cs): `src/BuildingBlocks/Persistence/Repositories/StatementReadRepository.cs`
- [Statement writes](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Persistence/Repositories/StatementWriteRepository.cs): `src/BuildingBlocks/Persistence/Repositories/StatementWriteRepository.cs`
- [Run repository](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Persistence/Runs/StatementRunRepository.cs): `src/BuildingBlocks/Persistence/Runs/StatementRunRepository.cs`
- [Download tokens](https://github.com/nwf007/statement-delivery-system/blob/main/src/BuildingBlocks/Persistence/Tokens/DownloadTokenRepository.cs): `src/BuildingBlocks/Persistence/Tokens/DownloadTokenRepository.cs`

### Audit

- [Audit verification API](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/Delivery.Api/Auditing/AuditVerifyEndpoint.cs): `src/Services/Delivery.Api/Auditing/AuditVerifyEndpoint.cs`

### Other components

- **Operator**
- **Customer**
- **Core ledger**
- [Mock ledger API](https://github.com/nwf007/statement-delivery-system/blob/main/src/Services/MockLedger.Api/Program.cs): `src/Services/MockLedger.Api/Program.cs`
- **PostgreSQL**

## Connections

- Customer → Delivery API: calls
- Delivery API → Statement endpoints: routes
- Delivery API → Link endpoints: routes
- Delivery API → Retention endpoints: routes
- Delivery API → Legal hold endpoints: routes
- Delivery API → Restore endpoints: routes
- Delivery API → Audit verification API: routes
- Statement endpoints → Statement reads: reads
- Link endpoints → Statement reads: reads
- Link endpoints → Download tokens: creates
- Customer → Download gateway: redeems link
- Download gateway → Download endpoints: routes
- Download endpoints → Download tokens: consumes
- Download endpoints → Statement reads: loads metadata
- Download endpoints → Encrypted content store: streams content
- Encrypted content store → Object storage: reads and writes
- Encrypted content store → Framed encryption: encrypts and decrypts
- Framed encryption → Customer key service: uses keys
- Customer key service → Key provider: wraps keys
- Generation worker → Run orchestrator: hosts
- Generation worker → Render worker: hosts
- Run orchestrator → Run repository: plans runs
- Run orchestrator → PostgreSQL: acquires lease
- Render worker → Render pipeline: processes claims
- Render pipeline → Core ledger: requests transactions
- Render pipeline → PDF renderer: renders document
- Render pipeline → Encrypted content store: writes encrypted content
- Render pipeline → Statement writes: publishes statement
- Statement writes → PostgreSQL: writes
- Statement reads → PostgreSQL: reads
- Run repository → PostgreSQL: reads and writes
- Download tokens → PostgreSQL: reads and writes
- Operator → Retention endpoints: requests erasure
- Operator → Legal hold endpoints: manages holds
- Operator → Restore endpoints: requests restore
- Retention endpoints → PostgreSQL: records request
- Legal hold endpoints → Object administration: sets object holds
- Restore endpoints → PostgreSQL: records request
- Retention worker → Retention sweep: hosts
- Retention sweep → Retention decision: decides disposition
- Retention worker → Erasure executor: executes erasure
- Erasure executor → Customer key service: destroys customer key
- Erasure executor → Object administration: manages objects
- Object administration → Object storage: administers locks
- Retention sweep → PostgreSQL: loads candidates
- Audit verification API → PostgreSQL: verifies chains
- Mock ledger API → Core ledger: implements locally