# ductura/server architecture

> Architecture diagram of the GitHub repository ductura/server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ductura/server
- Repository: https://github.com/ductura/server

## Overview

Ductura is a shared API server for AAI@EduHr sign-in, authorization, database-backed work, and background jobs. Its principal request path starts at the server entry point, passes through HTTP protections and contract-based routing, and reaches domain handlers; the documented functional check is opening a user’s own document while rejecting access to another’s. Evidence handling and its storage/signing options are major product capabilities, alongside sessions, administration, metrics, and downloads. Some area wiring is unsampled, so only documented or excerpt-supported relationships are drawn; dashed edges mark documented but unverified flow.

Main entry points: [`server/http`](https://github.com/ductura/server/tree/main/server/http) (HTTP area handlers), [`server/server.ts`](https://github.com/ductura/server/blob/main/server/server.ts) (Server entry), [`server/evidence/service.ts`](https://github.com/ductura/server/blob/main/server/evidence/service.ts) (Evidence service), [`server/http/router.ts`](https://github.com/ductura/server/blob/main/server/http/router.ts) (API router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_server["Server entry<br/>[server.ts]"]
  node_config["Runtime config<br/>[environment.ts]"]
  node_settings["Runtime settings<br/>[service.ts]"]
end

subgraph group_http["HTTP and API"]
  node_pipeline["Request pipeline<br/>[pipeline.ts]"]
  node_router["API router<br/>[router.ts]"]
  node_contracts["API contracts<br/>[index.ts]"]
  node_httpareas["HTTP area handlers"]
  node_problem["Problem responses<br/>[problem.ts]"]
end

subgraph group_identity["Identity and access"]
  node_sessions["Sessions and WebAuthn"]
  node_roles["Roles and permissions<br/>[service.ts]"]
end

subgraph group_work["Work and evidence"]
  node_database[("Database access<br/>[index.ts]")]
  node_domain["Domain rules<br/>[index.ts]"]
  node_evidence["Evidence service<br/>[service.ts]"]
  node_storage["Evidence storage<br/>[port.ts]"]
  node_signing["Evidence signing"]
end

subgraph group_operations["Platform services"]
  node_downloads["Release downloads<br/>[service.ts]"]
  node_metrics["Metrics<br/>[service.ts]"]
  node_support["Support reports<br/>[service.ts]"]
  node_backup["Backup<br/>[service.ts]"]
  node_deletion["Account deletion<br/>[service.ts]"]
  node_email["Email integration<br/>[service.ts]"]
end

node_caller(("API client"))

node_caller -.->|"sends request"| node_server
node_server -->|"validates environment"| node_config
node_server -->|"reads settings"| node_settings
node_server -->|"creates layers"| node_pipeline
node_server -->|"mounts handlers"| node_httpareas
node_pipeline -->|"gates requests"| node_httpareas
node_router -->|"matches contracts"| node_contracts
node_router -->|"sends errors"| node_problem
node_sessions -->|"uses actor access"| node_database
node_httpareas -.->|"authenticates requests"| node_sessions
node_httpareas -.->|"checks permissions"| node_roles
node_evidence -->|"uses persistence"| node_database
node_evidence -->|"uses domain rules"| node_domain
node_evidence -->|"uses payload storage"| node_storage
node_storage -->|"configures S3 credentials"| node_signing
node_httpareas -.->|"serves evidence requests"| node_evidence
node_httpareas -.->|"serves release requests"| node_downloads
node_httpareas -.->|"serves metrics requests"| node_metrics
node_httpareas -.->|"serves support requests"| node_support
node_httpareas -.->|"serves backup requests"| node_backup
node_httpareas -.->|"serves deletion requests"| node_deletion
node_httpareas -.->|"serves email requests"| node_email

click node_server "https://github.com/ductura/server/blob/main/server/server.ts"
click node_config "https://github.com/ductura/server/blob/main/server/config/environment.ts"
click node_settings "https://github.com/ductura/server/blob/main/server/settings/service.ts"
click node_pipeline "https://github.com/ductura/server/blob/main/server/http/pipeline.ts"
click node_router "https://github.com/ductura/server/blob/main/server/http/router.ts"
click node_contracts "https://github.com/ductura/server/blob/main/server/contracts/routes/index.ts"
click node_httpareas "https://github.com/ductura/server/tree/main/server/http"
click node_problem "https://github.com/ductura/server/blob/main/server/http/problem.ts"
click node_sessions "https://github.com/ductura/server/tree/main/server/session"
click node_roles "https://github.com/ductura/server/blob/main/server/roles/service.ts"
click node_database "https://github.com/ductura/server/blob/main/server/database/index.ts"
click node_domain "https://github.com/ductura/server/blob/main/server/domain/index.ts"
click node_evidence "https://github.com/ductura/server/blob/main/server/evidence/service.ts"
click node_storage "https://github.com/ductura/server/blob/main/server/external/storage/port.ts"
click node_signing "https://github.com/ductura/server/blob/main/server/external/keys/signing-key-provider.ts"
click node_downloads "https://github.com/ductura/server/blob/main/server/downloads/service.ts"
click node_metrics "https://github.com/ductura/server/blob/main/server/metrics/service.ts"
click node_support "https://github.com/ductura/server/blob/main/server/support/service.ts"
click node_backup "https://github.com/ductura/server/blob/main/server/backup/service.ts"
click node_deletion "https://github.com/ductura/server/blob/main/server/deletion/service.ts"
click node_email "https://github.com/ductura/server/blob/main/server/external/email/service.ts"

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_server,node_config,node_settings,node_caller toneBlue
class node_pipeline,node_router,node_contracts,node_httpareas,node_problem toneAmber
class node_sessions,node_roles toneMint
class node_database,node_domain,node_evidence,node_storage,node_signing toneRose
class node_downloads,node_metrics,node_support,node_backup,node_deletion,node_email toneIndigo
```

## Components

### Server runtime

- [Server entry](https://github.com/ductura/server/blob/main/server/server.ts): `server/server.ts`
- [Runtime config](https://github.com/ductura/server/blob/main/server/config/environment.ts): `server/config/environment.ts`
- [Runtime settings](https://github.com/ductura/server/blob/main/server/settings/service.ts): `server/settings/service.ts`

### HTTP and API

- [Request pipeline](https://github.com/ductura/server/blob/main/server/http/pipeline.ts): `server/http/pipeline.ts`
- [API router](https://github.com/ductura/server/blob/main/server/http/router.ts): `server/http/router.ts`
- [API contracts](https://github.com/ductura/server/blob/main/server/contracts/routes/index.ts): `server/contracts/routes/index.ts`
- [HTTP area handlers](https://github.com/ductura/server/tree/main/server/http): `server/http`
- [Problem responses](https://github.com/ductura/server/blob/main/server/http/problem.ts): `server/http/problem.ts`

### Identity and access

- [Sessions and WebAuthn](https://github.com/ductura/server/tree/main/server/session): `server/session`
- [Roles and permissions](https://github.com/ductura/server/blob/main/server/roles/service.ts): `server/roles/service.ts`

### Work and evidence

- [Database access](https://github.com/ductura/server/blob/main/server/database/index.ts): `server/database/index.ts`
- [Domain rules](https://github.com/ductura/server/blob/main/server/domain/index.ts): `server/domain/index.ts`
- [Evidence service](https://github.com/ductura/server/blob/main/server/evidence/service.ts): `server/evidence/service.ts`
- [Evidence storage](https://github.com/ductura/server/blob/main/server/external/storage/port.ts): `server/external/storage/port.ts`
- [Evidence signing](https://github.com/ductura/server/blob/main/server/external/keys/signing-key-provider.ts): `server/external/keys/signing-key-provider.ts`

### Platform services

- [Release downloads](https://github.com/ductura/server/blob/main/server/downloads/service.ts): `server/downloads/service.ts`
- [Metrics](https://github.com/ductura/server/blob/main/server/metrics/service.ts): `server/metrics/service.ts`
- [Support reports](https://github.com/ductura/server/blob/main/server/support/service.ts): `server/support/service.ts`
- [Backup](https://github.com/ductura/server/blob/main/server/backup/service.ts): `server/backup/service.ts`
- [Account deletion](https://github.com/ductura/server/blob/main/server/deletion/service.ts): `server/deletion/service.ts`
- [Email integration](https://github.com/ductura/server/blob/main/server/external/email/service.ts): `server/external/email/service.ts`

### Other components

- **API client**

## Connections

- API client → Server entry: sends request
- Server entry → Runtime config: validates environment (evidence: `server/server.ts`)
- Server entry → Runtime settings: reads settings (evidence: `server/server.ts`)
- Server entry → Request pipeline: creates layers (evidence: `server/server.ts`)
- Server entry → HTTP area handlers: mounts handlers (evidence: `server/server.ts`)
- Request pipeline → HTTP area handlers: gates requests (evidence: `server/http/pipeline.ts`)
- API router → API contracts: matches contracts (evidence: `server/http/router.ts`)
- API router → Problem responses: sends errors (evidence: `server/http/router.ts`)
- Sessions and WebAuthn → Database access: uses actor access (evidence: `server/session/index.ts`)
- HTTP area handlers → Sessions and WebAuthn: authenticates requests
- HTTP area handlers → Roles and permissions: checks permissions
- Evidence service → Database access: uses persistence (evidence: `server/evidence/service.ts`)
- Evidence service → Domain rules: uses domain rules (evidence: `server/evidence/service.ts`)
- Evidence service → Evidence storage: uses payload storage (evidence: `server/evidence/service.ts`)
- Evidence storage → Evidence signing: configures S3 credentials
- HTTP area handlers → Evidence service: serves evidence requests
- HTTP area handlers → Release downloads: serves release requests
- HTTP area handlers → Metrics: serves metrics requests
- HTTP area handlers → Support reports: serves support requests
- HTTP area handlers → Backup: serves backup requests
- HTTP area handlers → Account deletion: serves deletion requests
- HTTP area handlers → Email integration: serves email requests
