# khanakhun/yakhnama architecture

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

- Interactive diagram: https://gitdiagram.com/khanakhun/yakhnama
- Repository: https://github.com/khanakhun/yakhnama

## Overview

Yakhnama is a modular-monolith system of record for community-observed high-mountain hazards. Its central workflow takes reports through triage and moderation, then creates verified canonical events with sourced impact claims; media and provenance support traceability, while verification preserves moderator decisions. Separate capabilities ingest historical datasets and export/import data through background jobs. The graph follows the README’s documented boundaries and sampled query/pipeline behavior; several runtime connections are based on README architecture rather than inspected router or handler source.

Main entry points: [`src/yakhnama/modules/events/application`](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/events/application) (Canonical events), [`src/yakhnama/platform/db.py`](https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/platform/db.py) (Persistent records), [`src/yakhnama/modules/reports/application`](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/reports/application) (Reports and triage), [`src/yakhnama/modules/verification/application`](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/verification/application) (Verification cases)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Reports and review"]
  node_report_api["Report API"]
  node_reports["Reports and triage"]
  node_media["Media handling"]
  node_media_store["Media object storage<br/>[s3_storage.py]"]
  node_verification["Verification cases"]
end

subgraph group_record["Canonical record"]
  node_events["Canonical events"]
  node_impacts["Impact claims"]
  node_provenance["Sources and citations"]
  node_geography["Geographic references"]
  node_hazards["Hazard references"]
  node_audit["Audit log"]
end

subgraph group_data["Data exchange"]
  node_ingestion["Dataset ingestion<br/>[pipeline.py]"]
  node_ingestion_adapters["Source adapters"]
  node_exchange["Import and export jobs"]
  node_exchange_formats["Format adapters"]
  node_artifact_store["Export artifacts"]
end

subgraph group_runtime["Application platform"]
  node_app["API application<br/>[main.py]"]
  node_identity["Identity and policy<br/>[public.py]"]
  node_tasks["Background task runtime"]
  node_outbox["Outbox relay"]
  node_database[("Persistent records<br/>[db.py]")]
end

node_community(("Community / moderator"))

node_community -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_report_api
node_report_api -->|"dispatches report requests"| node_reports
node_reports -->|"moderates reports"| node_verification
node_reports -->|"handles attachments"| node_media
node_media -->|"stores and retrieves media"| node_media_store
node_verification -->|"verifies into events"| node_events
node_events -->|"anchors impact claims"| node_impacts
node_events -->|"cites sources"| node_provenance
node_events -->|"uses geographic references"| node_geography
node_events -->|"uses hazard references"| node_hazards
node_reports -->|"checks access policies"| node_identity
node_verification -->|"checks moderator access"| node_identity
node_events -->|"checks visibility"| node_identity
node_impacts -->|"checks visibility"| node_identity
node_events -->|"reads transition history"| node_verification
node_events -->|"reads impact timeline"| node_impacts
node_provenance -->|"checks published citations"| node_events
node_community -.->|"requests data intake"| node_ingestion
node_ingestion -->|"fetches source data"| node_ingestion_adapters
node_ingestion -->|"runs pipeline jobs"| node_tasks
node_community -.->|"requests data exchange"| node_exchange
node_exchange -->|"runs import and export jobs"| node_tasks
node_exchange -->|"converts datasets"| node_exchange_formats
node_exchange -->|"stores and presigns exports"| node_artifact_store
node_reports -->|"persists report records"| node_database
node_verification -->|"persists case history"| node_database
node_events -->|"persists event records"| node_database
node_impacts -->|"persists claims"| node_database
node_provenance -->|"persists source records"| node_database
node_audit -->|"reads audit entries"| node_database
node_outbox -->|"dispatches queued work"| node_tasks

click node_app "https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/main.py"
click node_report_api "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/reports/api"
click node_reports "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/reports/application"
click node_media "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/media/application"
click node_media_store "https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/modules/media/infrastructure/adapters/s3_storage.py"
click node_verification "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/verification/application"
click node_events "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/events/application"
click node_impacts "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/impacts/application"
click node_provenance "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/provenance/application"
click node_geography "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/geography"
click node_hazards "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/hazards"
click node_identity "https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/modules/identity/public.py"
click node_audit "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/audit"
click node_ingestion "https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/modules/ingestion/application/pipeline.py"
click node_ingestion_adapters "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/ingestion/infrastructure/adapters"
click node_exchange "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/exchange/application"
click node_exchange_formats "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/exchange/infrastructure/adapters"
click node_tasks "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/platform/tasks"
click node_outbox "https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/platform/outbox"
click node_database "https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/platform/db.py"
click node_artifact_store "https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/modules/exchange/infrastructure/adapters/s3_artifact_store.py"

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_report_api,node_reports,node_media,node_media_store,node_verification toneBlue
class node_events,node_impacts,node_provenance,node_geography,node_hazards,node_audit toneAmber
class node_ingestion,node_ingestion_adapters,node_exchange,node_exchange_formats,node_artifact_store toneMint
class node_app,node_identity,node_tasks,node_outbox,node_database toneRose
class node_community toneIndigo
```

## Components

### Reports and review

- [Report API](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/reports/api): `src/yakhnama/modules/reports/api`
- [Reports and triage](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/reports/application): `src/yakhnama/modules/reports/application`
- [Media handling](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/media/application): `src/yakhnama/modules/media/application`
- [Media object storage](https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/modules/media/infrastructure/adapters/s3_storage.py): `src/yakhnama/modules/media/infrastructure/adapters/s3_storage.py`
- [Verification cases](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/verification/application): `src/yakhnama/modules/verification/application`

### Canonical record

- [Canonical events](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/events/application): `src/yakhnama/modules/events/application`
- [Impact claims](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/impacts/application): `src/yakhnama/modules/impacts/application`
- [Sources and citations](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/provenance/application): `src/yakhnama/modules/provenance/application`
- [Geographic references](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/geography): `src/yakhnama/modules/geography`
- [Hazard references](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/hazards): `src/yakhnama/modules/hazards`
- [Audit log](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/audit): `src/yakhnama/modules/audit`

### Data exchange

- [Dataset ingestion](https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/modules/ingestion/application/pipeline.py): `src/yakhnama/modules/ingestion/application/pipeline.py`
- [Source adapters](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/ingestion/infrastructure/adapters): `src/yakhnama/modules/ingestion/infrastructure/adapters`
- [Import and export jobs](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/exchange/application): `src/yakhnama/modules/exchange/application`
- [Format adapters](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/modules/exchange/infrastructure/adapters): `src/yakhnama/modules/exchange/infrastructure/adapters`
- [Export artifacts](https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/modules/exchange/infrastructure/adapters/s3_artifact_store.py): `src/yakhnama/modules/exchange/infrastructure/adapters/s3_artifact_store.py`

### Application platform

- [API application](https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/main.py): `src/yakhnama/main.py`
- [Identity and policy](https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/modules/identity/public.py): `src/yakhnama/modules/identity/public.py`
- [Background task runtime](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/platform/tasks): `src/yakhnama/platform/tasks`
- [Outbox relay](https://github.com/khanakhun/yakhnama/tree/main/src/yakhnama/platform/outbox): `src/yakhnama/platform/outbox`
- [Persistent records](https://github.com/khanakhun/yakhnama/blob/main/src/yakhnama/platform/db.py): `src/yakhnama/platform/db.py`

### Other components

- **Community / moderator**

## Connections

- Community / moderator → API application: sends requests
- API application → Report API: mounts routes
- Report API → Reports and triage: dispatches report requests
- Reports and triage → Verification cases: moderates reports
- Reports and triage → Media handling: handles attachments
- Media handling → Media object storage: stores and retrieves media
- Verification cases → Canonical events: verifies into events
- Canonical events → Impact claims: anchors impact claims
- Canonical events → Sources and citations: cites sources
- Canonical events → Geographic references: uses geographic references
- Canonical events → Hazard references: uses hazard references
- Reports and triage → Identity and policy: checks access policies
- Verification cases → Identity and policy: checks moderator access
- Canonical events → Identity and policy: checks visibility
- Impact claims → Identity and policy: checks visibility
- Canonical events → Verification cases: reads transition history
- Canonical events → Impact claims: reads impact timeline
- Sources and citations → Canonical events: checks published citations
- Community / moderator → Dataset ingestion: requests data intake
- Dataset ingestion → Source adapters: fetches source data
- Dataset ingestion → Background task runtime: runs pipeline jobs
- Community / moderator → Import and export jobs: requests data exchange
- Import and export jobs → Background task runtime: runs import and export jobs
- Import and export jobs → Format adapters: converts datasets
- Import and export jobs → Export artifacts: stores and presigns exports
- Reports and triage → Persistent records: persists report records
- Verification cases → Persistent records: persists case history
- Canonical events → Persistent records: persists event records
- Impact claims → Persistent records: persists claims
- Sources and citations → Persistent records: persists source records
- Audit log → Persistent records: reads audit entries
- Outbox relay → Background task runtime: dispatches queued work