# somali-ai-pirates/aden architecture

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

- Interactive diagram: https://gitdiagram.com/somali-ai-pirates/aden
- Repository: https://github.com/somali-ai-pirates/aden

## Overview

ADEN is a maritime-document question-answering service: a question enters through the HTTP API, is retrieved against indexed PDFs, then answered with document/page citations or an abstention. The repository also contains offline document curation and indexing, plus evaluation and security-scoring capabilities. The sampled query and retrieval modules show the main runtime orchestration; several ingestion, API setup, and evaluation links are documented or indexed but their implementation details were not sampled, so uncertain connections are omitted or marked dashed.

Main entry points: [`app/service/query.py`](https://github.com/somali-ai-pirates/aden/blob/main/app/service/query.py) (Query orchestration), [`app/service/resources.py`](https://github.com/somali-ai-pirates/aden/blob/main/app/service/resources.py) (Runtime resources), [`app/retrieval/service.py`](https://github.com/somali-ai-pirates/aden/blob/main/app/retrieval/service.py) (Retrieval modes), [`app/ingestion/curation.py`](https://github.com/somali-ai-pirates/aden/blob/main/app/ingestion/curation.py) (PDF curation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and service"]
  node_api_routes["HTTP routes<br/>[routes.py]"]
  node_query["Query orchestration<br/>[query.py]"]
  node_resources["Runtime resources<br/>[resources.py]"]
  node_contracts["Query contracts<br/>[contracts.py]"]
end

subgraph group_search["Retrieval and generation"]
  node_retrieval["Retrieval modes<br/>[service.py]"]
  node_embeddings["Text embeddings<br/>[embeddings.py]"]
  node_dense["Dense search<br/>[dense.py]"]
  node_hybrid["Hybrid search<br/>[hybrid.py]"]
  node_reranker["Candidate reranking<br/>[reranker.py]"]
  node_context["Context assembly<br/>[context.py]"]
  node_answer["Answer generation<br/>[chain.py]"]
  node_citations["Citation resolution<br/>[citations.py]"]
end

subgraph group_docs["Document preparation"]
  node_curation["PDF curation<br/>[curation.py]"]
  node_layout["PDF layout parsing<br/>[layout.py]"]
  node_rules["Shared text rules<br/>[common_rules.py]"]
  node_chunker["Chunking<br/>[chunker.py]"]
  node_vector_store["Vector indexing<br/>[vector_store.py]"]
  node_index_build["Index build tool<br/>[build_index.py]"]
end

subgraph group_eval["Evaluation"]
  node_eval_data["Evaluation datasets<br/>[dataset.py]"]
  node_graders["Answer graders<br/>[graders.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
  node_eval_report["Evaluation reports<br/>[report.py]"]
  node_security_eval["Security evaluation<br/>[security.py]"]
end

subgraph group_ops["Observability"]
  node_tracing["Request tracing<br/>[tracing.py]"]
  node_records["Run records<br/>[records.py]"]
end

node_user(("Questioner"))
node_model{{"Language model"}}
node_qdrant[("Qdrant index")]

node_user -->|"submits question"| node_api_routes
node_api_routes -->|"dispatches query"| node_query
node_api_routes -->|"validates payload"| node_contracts
node_query -->|"retrieves candidates"| node_retrieval
node_query -->|"prepares evidence"| node_context
node_query -->|"generates answer"| node_answer
node_query -->|"resolves sources"| node_citations
node_query -->|"uses resources"| node_resources
node_query -->|"records trace"| node_tracing
node_retrieval -->|"runs dense mode"| node_dense
node_retrieval -->|"runs hybrid mode"| node_hybrid
node_retrieval -->|"reranks candidates"| node_reranker
node_resources -->|"loads embedder"| node_embeddings
node_resources -->|"loads tracer"| node_tracing
node_resources -.->|"connects index"| node_qdrant
node_dense -.->|"embeds query"| node_embeddings
node_dense -.->|"searches vectors"| node_qdrant
node_hybrid -.->|"uses indexed data"| node_qdrant
node_answer -->|"requests completion"| node_model
node_curation -->|"parses pages"| node_layout
node_curation -->|"applies rules"| node_rules
node_vector_store -->|"chunks documents"| node_chunker
node_index_build -.->|"builds index"| node_vector_store
node_curation -.->|"feeds curated data"| node_index_build
node_eval_report -->|"uses graders"| node_graders
node_eval_report -->|"computes metrics"| node_metrics
node_graders -->|"uses measures"| node_metrics
node_metrics -->|"scores dataset"| node_eval_data
node_security_eval -->|"reads run records"| node_records
node_eval_report -->|"reads run records"| node_records

click node_api_routes "https://github.com/somali-ai-pirates/aden/blob/main/app/api/routes.py"
click node_query "https://github.com/somali-ai-pirates/aden/blob/main/app/service/query.py"
click node_resources "https://github.com/somali-ai-pirates/aden/blob/main/app/service/resources.py"
click node_contracts "https://github.com/somali-ai-pirates/aden/blob/main/shared/contracts.py"
click node_retrieval "https://github.com/somali-ai-pirates/aden/blob/main/app/retrieval/service.py"
click node_embeddings "https://github.com/somali-ai-pirates/aden/blob/main/app/indexing/embeddings.py"
click node_dense "https://github.com/somali-ai-pirates/aden/blob/main/app/retrieval/dense.py"
click node_hybrid "https://github.com/somali-ai-pirates/aden/blob/main/app/retrieval/hybrid.py"
click node_reranker "https://github.com/somali-ai-pirates/aden/blob/main/app/retrieval/reranker.py"
click node_context "https://github.com/somali-ai-pirates/aden/blob/main/app/generation/context.py"
click node_answer "https://github.com/somali-ai-pirates/aden/blob/main/app/generation/chain.py"
click node_citations "https://github.com/somali-ai-pirates/aden/blob/main/app/generation/citations.py"
click node_curation "https://github.com/somali-ai-pirates/aden/blob/main/app/ingestion/curation.py"
click node_layout "https://github.com/somali-ai-pirates/aden/blob/main/app/ingestion/layout.py"
click node_rules "https://github.com/somali-ai-pirates/aden/blob/main/app/ingestion/common_rules.py"
click node_chunker "https://github.com/somali-ai-pirates/aden/blob/main/app/ingestion/chunker.py"
click node_vector_store "https://github.com/somali-ai-pirates/aden/blob/main/app/indexing/vector_store.py"
click node_index_build "https://github.com/somali-ai-pirates/aden/blob/main/app/indexing/scripts/build_index.py"
click node_eval_data "https://github.com/somali-ai-pirates/aden/blob/main/app/evaluation/dataset.py"
click node_graders "https://github.com/somali-ai-pirates/aden/blob/main/app/evaluation/graders.py"
click node_metrics "https://github.com/somali-ai-pirates/aden/blob/main/app/evaluation/metrics.py"
click node_eval_report "https://github.com/somali-ai-pirates/aden/blob/main/app/evaluation/report.py"
click node_security_eval "https://github.com/somali-ai-pirates/aden/blob/main/app/evaluation/security.py"
click node_tracing "https://github.com/somali-ai-pirates/aden/blob/main/app/observability/tracing.py"
click node_records "https://github.com/somali-ai-pirates/aden/blob/main/app/observability/records.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_api_routes,node_query,node_resources,node_contracts toneBlue
class node_retrieval,node_embeddings,node_dense,node_hybrid,node_reranker,node_context,node_answer,node_citations,node_qdrant toneAmber
class node_curation,node_layout,node_rules,node_chunker,node_vector_store,node_index_build toneMint
class node_eval_data,node_graders,node_metrics,node_eval_report,node_security_eval toneRose
class node_tracing,node_records,node_user,node_model toneIndigo
```

## Components

### API and service

- [HTTP routes](https://github.com/somali-ai-pirates/aden/blob/main/app/api/routes.py): `app/api/routes.py`
- [Query orchestration](https://github.com/somali-ai-pirates/aden/blob/main/app/service/query.py): `app/service/query.py`
- [Runtime resources](https://github.com/somali-ai-pirates/aden/blob/main/app/service/resources.py): `app/service/resources.py`
- [Query contracts](https://github.com/somali-ai-pirates/aden/blob/main/shared/contracts.py): `shared/contracts.py`

### Retrieval and generation

- [Retrieval modes](https://github.com/somali-ai-pirates/aden/blob/main/app/retrieval/service.py): `app/retrieval/service.py`
- [Text embeddings](https://github.com/somali-ai-pirates/aden/blob/main/app/indexing/embeddings.py): `app/indexing/embeddings.py`
- [Dense search](https://github.com/somali-ai-pirates/aden/blob/main/app/retrieval/dense.py): `app/retrieval/dense.py`
- [Hybrid search](https://github.com/somali-ai-pirates/aden/blob/main/app/retrieval/hybrid.py): `app/retrieval/hybrid.py`
- [Candidate reranking](https://github.com/somali-ai-pirates/aden/blob/main/app/retrieval/reranker.py): `app/retrieval/reranker.py`
- [Context assembly](https://github.com/somali-ai-pirates/aden/blob/main/app/generation/context.py): `app/generation/context.py`
- [Answer generation](https://github.com/somali-ai-pirates/aden/blob/main/app/generation/chain.py): `app/generation/chain.py`
- [Citation resolution](https://github.com/somali-ai-pirates/aden/blob/main/app/generation/citations.py): `app/generation/citations.py`

### Document preparation

- [PDF curation](https://github.com/somali-ai-pirates/aden/blob/main/app/ingestion/curation.py): `app/ingestion/curation.py`
- [PDF layout parsing](https://github.com/somali-ai-pirates/aden/blob/main/app/ingestion/layout.py): `app/ingestion/layout.py`
- [Shared text rules](https://github.com/somali-ai-pirates/aden/blob/main/app/ingestion/common_rules.py): `app/ingestion/common_rules.py`
- [Chunking](https://github.com/somali-ai-pirates/aden/blob/main/app/ingestion/chunker.py): `app/ingestion/chunker.py`
- [Vector indexing](https://github.com/somali-ai-pirates/aden/blob/main/app/indexing/vector_store.py): `app/indexing/vector_store.py`
- [Index build tool](https://github.com/somali-ai-pirates/aden/blob/main/app/indexing/scripts/build_index.py): `app/indexing/scripts/build_index.py`

### Evaluation

- [Evaluation datasets](https://github.com/somali-ai-pirates/aden/blob/main/app/evaluation/dataset.py): `app/evaluation/dataset.py`
- [Answer graders](https://github.com/somali-ai-pirates/aden/blob/main/app/evaluation/graders.py): `app/evaluation/graders.py`
- [Evaluation metrics](https://github.com/somali-ai-pirates/aden/blob/main/app/evaluation/metrics.py): `app/evaluation/metrics.py`
- [Evaluation reports](https://github.com/somali-ai-pirates/aden/blob/main/app/evaluation/report.py): `app/evaluation/report.py`
- [Security evaluation](https://github.com/somali-ai-pirates/aden/blob/main/app/evaluation/security.py): `app/evaluation/security.py`

### Observability

- [Request tracing](https://github.com/somali-ai-pirates/aden/blob/main/app/observability/tracing.py): `app/observability/tracing.py`
- [Run records](https://github.com/somali-ai-pirates/aden/blob/main/app/observability/records.py): `app/observability/records.py`

### Other components

- **Questioner**
- **Language model**
- **Qdrant index**

## Connections

- Questioner → HTTP routes: submits question (evidence: `app/api/routes.py`)
- HTTP routes → Query orchestration: dispatches query (evidence: `app/api/routes.py`)
- HTTP routes → Query contracts: validates payload (evidence: `app/api/routes.py`)
- Query orchestration → Retrieval modes: retrieves candidates (evidence: `app/service/query.py`)
- Query orchestration → Context assembly: prepares evidence (evidence: `app/service/query.py`)
- Query orchestration → Answer generation: generates answer (evidence: `app/service/query.py`)
- Query orchestration → Citation resolution: resolves sources (evidence: `app/service/query.py`)
- Query orchestration → Runtime resources: uses resources (evidence: `app/service/query.py`)
- Query orchestration → Request tracing: records trace (evidence: `app/service/query.py`)
- Retrieval modes → Dense search: runs dense mode (evidence: `app/retrieval/service.py`)
- Retrieval modes → Hybrid search: runs hybrid mode (evidence: `app/retrieval/service.py`)
- Retrieval modes → Candidate reranking: reranks candidates (evidence: `app/retrieval/service.py`)
- Runtime resources → Text embeddings: loads embedder (evidence: `app/service/resources.py`)
- Runtime resources → Request tracing: loads tracer (evidence: `app/service/resources.py`)
- Runtime resources → Qdrant index: connects index (evidence: `app/service/resources.py`)
- Dense search → Text embeddings: embeds query
- Dense search → Qdrant index: searches vectors
- Hybrid search → Qdrant index: uses indexed data
- Answer generation → Language model: requests completion
- PDF curation → PDF layout parsing: parses pages (evidence: `app/ingestion/curation.py`)
- PDF curation → Shared text rules: applies rules (evidence: `app/ingestion/curation.py`)
- Vector indexing → Chunking: chunks documents (evidence: `app/indexing/vector_store.py`)
- Index build tool → Vector indexing: builds index
- PDF curation → Index build tool: feeds curated data
- Evaluation reports → Answer graders: uses graders (evidence: `app/evaluation/report.py`)
- Evaluation reports → Evaluation metrics: computes metrics (evidence: `app/evaluation/report.py`)
- Answer graders → Evaluation metrics: uses measures (evidence: `app/evaluation/graders.py`)
- Evaluation metrics → Evaluation datasets: scores dataset (evidence: `app/evaluation/metrics.py`)
- Security evaluation → Run records: reads run records (evidence: `app/evaluation/security.py`)
- Evaluation reports → Run records: reads run records (evidence: `app/evaluation/report.py`)