# aamna-khan-git/amr-sentinel architecture

> Architecture diagram of the GitHub repository aamna-khan-git/amr-sentinel, 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/aamna-khan-git/amr-sentinel
- Repository: https://github.com/aamna-khan-git/amr-sentinel

## Overview

AMR Sentinel answers natural-language One Health surveillance questions: its dashboard or REST endpoint sends a question through intent parsing, structured-data and literature retrieval, and grounded narrative generation with severity labels. Separate ingestion paths populate the surveillance database and literature index. The README documents dashboard charts and recommendation capabilities; sampled excerpts do not establish every UI or subsystem connection, so uncertain wiring is omitted.

Main entry points: [`orchestrator.py`](https://github.com/aamna-khan-git/amr-sentinel/blob/main/orchestrator.py) (Query orchestrator), [`api_server.py`](https://github.com/aamna-khan-git/amr-sentinel/blob/main/api_server.py) (Dashboard and API), [`pdf_ingest.py`](https://github.com/aamna-khan-git/amr-sentinel/blob/main/pdf_ingest.py) (PDF ingestion), [`literature_store.py`](https://github.com/aamna-khan-git/amr-sentinel/blob/main/literature_store.py) (Index and search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["Query and answers"]
  node_orchestrator["Query orchestrator<br/>[orchestrator.py]"]
  node_data_agent["Surveillance queries<br/>[data_agent.py]"]
  node_literature_agent["Literature search"]
  node_narrative["Narrative and severity<br/>[narrative_agent.py]"]
  node_db_setup["Database queries<br/>[db_setup.py]"]
  node_lit_store["Index and search"]
end

subgraph group_ingest["Data ingestion"]
  node_pdf_ingest["PDF ingestion<br/>[pdf_ingest.py]"]
  node_efsa_ingest["EFSA ingestion<br/>[fetch_efsa.py]"]
  node_abstract_fetch["Abstract retrieval"]
end

subgraph group_stores["Evidence stores"]
  node_sqlite[("Surveillance database<br/>[amr_sentinel.db]")]
  node_chroma[("Literature index")]
  node_abstracts["Abstract records<br/>[abstracts.jsonl]"]
end

subgraph group_interfaces["User interfaces"]
  node_api["Dashboard and API<br/>[api_server.py]"]
  node_dashboard["Charts and metrics<br/>[api_server.py]"]
end

node_user(("User"))
node_llm{{"LLM provider"}}
node_ecdc{{"ECDC reports"}}
node_efsa{{"EFSA data"}}
node_ncbi{{"NCBI PubMed"}}

node_user -->|"asks"| node_api
node_api -->|"forwards question"| node_orchestrator
node_orchestrator -->|"parses intent"| node_llm
node_orchestrator -->|"queries data"| node_data_agent
node_orchestrator -->|"searches literature"| node_literature_agent
node_orchestrator -->|"generates answer"| node_narrative
node_narrative -->|"generates narrative"| node_llm
node_data_agent -->|"dispatches query"| node_db_setup
node_db_setup -->|"reads"| node_sqlite
node_literature_agent -->|"searches"| node_lit_store
node_lit_store -->|"searches index"| node_chroma
node_ecdc -->|"provides reports"| node_pdf_ingest
node_pdf_ingest -->|"writes surveillance data"| node_sqlite
node_pdf_ingest -->|"writes text chunks"| node_chroma
node_efsa -->|"provides data"| node_efsa_ingest
node_efsa_ingest -->|"writes surveillance data"| node_sqlite
node_ncbi -->|"provides abstracts"| node_abstract_fetch
node_abstract_fetch -->|"writes records"| node_abstracts
node_abstracts -->|"supplies documents"| node_lit_store
node_orchestrator -->|"returns answer"| node_api
node_api -->|"renders results"| node_dashboard

click node_api "https://github.com/aamna-khan-git/amr-sentinel/blob/main/api_server.py"
click node_orchestrator "https://github.com/aamna-khan-git/amr-sentinel/blob/main/orchestrator.py"
click node_data_agent "https://github.com/aamna-khan-git/amr-sentinel/blob/main/agents/data_agent.py"
click node_literature_agent "https://github.com/aamna-khan-git/amr-sentinel/blob/main/agents/literature_agent.py"
click node_narrative "https://github.com/aamna-khan-git/amr-sentinel/blob/main/agents/narrative_agent.py"
click node_sqlite "https://github.com/aamna-khan-git/amr-sentinel/blob/main/amr_sentinel.db"
click node_chroma "https://github.com/aamna-khan-git/amr-sentinel/tree/main/chroma_store"
click node_db_setup "https://github.com/aamna-khan-git/amr-sentinel/blob/main/db_setup.py"
click node_lit_store "https://github.com/aamna-khan-git/amr-sentinel/blob/main/literature_store.py"
click node_pdf_ingest "https://github.com/aamna-khan-git/amr-sentinel/blob/main/pdf_ingest.py"
click node_efsa_ingest "https://github.com/aamna-khan-git/amr-sentinel/blob/main/fetch_efsa.py"
click node_abstract_fetch "https://github.com/aamna-khan-git/amr-sentinel/blob/main/fetch_abstracts_ncbi.py"
click node_abstracts "https://github.com/aamna-khan-git/amr-sentinel/blob/main/data/abstracts.jsonl"
click node_dashboard "https://github.com/aamna-khan-git/amr-sentinel/blob/main/api_server.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_orchestrator,node_data_agent,node_literature_agent,node_narrative,node_db_setup,node_lit_store,node_user toneBlue
class node_pdf_ingest,node_efsa_ingest,node_abstract_fetch toneAmber
class node_sqlite,node_chroma,node_abstracts toneMint
class node_api,node_dashboard toneRose
class node_llm,node_ecdc,node_efsa,node_ncbi toneIndigo
```

## Components

### Query and answers

- [Query orchestrator](https://github.com/aamna-khan-git/amr-sentinel/blob/main/orchestrator.py): `orchestrator.py`
- [Surveillance queries](https://github.com/aamna-khan-git/amr-sentinel/blob/main/agents/data_agent.py): `agents/data_agent.py`
- [Literature search](https://github.com/aamna-khan-git/amr-sentinel/blob/main/agents/literature_agent.py): `agents/literature_agent.py`
- [Narrative and severity](https://github.com/aamna-khan-git/amr-sentinel/blob/main/agents/narrative_agent.py): `agents/narrative_agent.py`
- [Database queries](https://github.com/aamna-khan-git/amr-sentinel/blob/main/db_setup.py): `db_setup.py`
- [Index and search](https://github.com/aamna-khan-git/amr-sentinel/blob/main/literature_store.py): `literature_store.py`

### Data ingestion

- [PDF ingestion](https://github.com/aamna-khan-git/amr-sentinel/blob/main/pdf_ingest.py): `pdf_ingest.py`
- [EFSA ingestion](https://github.com/aamna-khan-git/amr-sentinel/blob/main/fetch_efsa.py): `fetch_efsa.py`
- [Abstract retrieval](https://github.com/aamna-khan-git/amr-sentinel/blob/main/fetch_abstracts_ncbi.py): `fetch_abstracts_ncbi.py`

### Evidence stores

- [Surveillance database](https://github.com/aamna-khan-git/amr-sentinel/blob/main/amr_sentinel.db): `amr_sentinel.db`
- [Literature index](https://github.com/aamna-khan-git/amr-sentinel/tree/main/chroma_store): `chroma_store`
- [Abstract records](https://github.com/aamna-khan-git/amr-sentinel/blob/main/data/abstracts.jsonl): `data/abstracts.jsonl`

### User interfaces

- [Dashboard and API](https://github.com/aamna-khan-git/amr-sentinel/blob/main/api_server.py): `api_server.py`
- [Charts and metrics](https://github.com/aamna-khan-git/amr-sentinel/blob/main/api_server.py): `api_server.py`

### Other components

- **User**
- **LLM provider**
- **ECDC reports**
- **EFSA data**
- **NCBI PubMed**

## Connections

- User → Dashboard and API: asks
- Dashboard and API → Query orchestrator: forwards question
- Query orchestrator → LLM provider: parses intent
- Query orchestrator → Surveillance queries: queries data
- Query orchestrator → Literature search: searches literature
- Query orchestrator → Narrative and severity: generates answer
- Narrative and severity → LLM provider: generates narrative
- Surveillance queries → Database queries: dispatches query
- Database queries → Surveillance database: reads
- Literature search → Index and search: searches
- Index and search → Literature index: searches index
- ECDC reports → PDF ingestion: provides reports
- PDF ingestion → Surveillance database: writes surveillance data
- PDF ingestion → Literature index: writes text chunks
- EFSA data → EFSA ingestion: provides data
- EFSA ingestion → Surveillance database: writes surveillance data
- NCBI PubMed → Abstract retrieval: provides abstracts
- Abstract retrieval → Abstract records: writes records
- Abstract records → Index and search: supplies documents
- Query orchestrator → Dashboard and API: returns answer
- Dashboard and API → Charts and metrics: renders results