# lowellowuor/amr_nexus- architecture

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

- Interactive diagram: https://gitdiagram.com/lowellowuor/amr_nexus-
- Repository: https://github.com/lowellowuor/amr_nexus-

## Overview

AMR Nexus is Kenya’s antimicrobial-resistance surveillance and clinical decision-support platform. A clinician or analyst uses the authenticated frontend to submit isolate data or explore surveillance results; prediction requests pass through the backend to prediction and storage services, while analytics support maps, comparisons, and reports. Separate workflows handle alerts, notifications, administration, audit, and data-subject rights. The README documents these capabilities; sampled source supports the frontend routing, authenticated API client, backend entry point, isolate search, offline drafts, and LLM integrations, but does not expose every router-to-service call.

Main entry points: [`Backend/amr_nexus_ml/src/main.py`](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/main.py) (ASGI application), [`Backend/amr_nexus_ml/src/db/models.py`](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/db/models.py) (Application database), [`frontend/src/App.jsx`](https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/App.jsx) (Authenticated app routes), [`Backend/amr_nexus_ml/src/api/routers/predictions.py`](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/predictions.py) (Prediction endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User application"]
  node_app["Authenticated app routes<br/>[App.jsx]"]
  node_predict["Isolate prediction<br/>[Predict.jsx]"]
  node_dashboards["Dashboards and exploration"]
  node_reports["Reports and comparisons<br/>[Reports.jsx]"]
  node_api["Authenticated API client<br/>[client.js]"]
  node_drafts[("Offline drafts<br/>[offlineStorage.js]")]
end

subgraph group_prediction["Clinical prediction"]
  node_prediction_router["Prediction endpoints<br/>[predictions.py]"]
  node_prediction_service["Prediction service"]
  node_ml["Model and fallback<br/>[ml.py]"]
  node_explain["SHAP explanations<br/>[shap_service.py]"]
end

subgraph group_surveillance["Surveillance analytics"]
  node_analytics_router["Analytics endpoints<br/>[analytics.py]"]
  node_pathogen_router["Pathogen exploration<br/>[analyst.py]"]
  node_search_router["Historical isolate search<br/>[search_router.py]"]
  node_forecast["Time-series forecasts"]
end

subgraph group_operations["Alerts and governance"]
  node_alerts_router["Alert lifecycle<br/>[alerts.py]"]
  node_notifications["Notification dispatch"]
  node_audit["Audit trail"]
  node_users["Identity and user rights<br/>[user_router.py]"]
  node_llm["Clinical narrative insights<br/>[llm_service.py]"]
end

subgraph group_runtime["Backend runtime"]
  node_backend["ASGI application<br/>[main.py]"]
  node_db[("Application database<br/>[models.py]")]
end

node_user(("Clinician or analyst"))
node_gemini(("Google Gemini"))
node_email_sms(("Email and SMS providers"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_predict
node_app -->|"routes to"| node_dashboards
node_app -->|"routes to"| node_reports
node_predict -->|"requests API"| node_api
node_dashboards -->|"requests API"| node_api
node_reports -->|"requests API"| node_api
node_predict -->|"saves drafts"| node_drafts
node_api -->|"sends requests"| node_backend
node_backend -->|"dispatches"| node_prediction_router
node_backend -->|"dispatches"| node_analytics_router
node_backend -->|"dispatches"| node_pathogen_router
node_backend -->|"dispatches"| node_search_router
node_backend -->|"dispatches"| node_alerts_router
node_backend -->|"dispatches"| node_users
node_prediction_router -->|"requests prediction"| node_prediction_service
node_prediction_service -->|"runs inference"| node_ml
node_prediction_service -->|"requests explanation"| node_explain
node_prediction_router -->|"records outcomes"| node_db
node_analytics_router -->|"queries surveillance data"| node_db
node_search_router -->|"queries isolates"| node_db
node_backend -->|"requests forecast"| node_forecast
node_forecast -->|"reads surveillance data"| node_db
node_alerts_router -->|"dispatches notifications"| node_notifications
node_notifications -.->|"sends email or SMS"| node_email_sms
node_backend -->|"records privileged actions"| node_audit
node_users -->|"manages user data"| node_db
node_prediction_router -->|"requests insight"| node_llm
node_llm -.->|"generates narrative"| node_gemini

click node_app "https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/App.jsx"
click node_predict "https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/pages/Predict.jsx"
click node_dashboards "https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/pages/NationalDashboard.jsx"
click node_reports "https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/pages/Reports.jsx"
click node_api "https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/api/client.js"
click node_drafts "https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/utils/offlineStorage.js"
click node_backend "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/main.py"
click node_prediction_router "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/predictions.py"
click node_prediction_service "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/services/prediction_service.py"
click node_ml "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/core/ml.py"
click node_explain "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/services/shap_service.py"
click node_analytics_router "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/analytics.py"
click node_pathogen_router "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/analyst.py"
click node_search_router "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/search_router.py"
click node_forecast "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/services/forecast_service.py"
click node_alerts_router "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/alerts.py"
click node_notifications "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/services/notification_service.py"
click node_audit "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/core/audit_middleware.py"
click node_users "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/user_router.py"
click node_llm "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/services/llm_service.py"
click node_db "https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/db/models.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_app,node_predict,node_dashboards,node_reports,node_api,node_drafts toneBlue
class node_prediction_router,node_prediction_service,node_ml,node_explain toneAmber
class node_analytics_router,node_pathogen_router,node_search_router,node_forecast toneMint
class node_alerts_router,node_notifications,node_audit,node_users,node_llm toneRose
class node_backend,node_db,node_user,node_gemini,node_email_sms toneIndigo
```

## Components

### User application

- [Authenticated app routes](https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Isolate prediction](https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/pages/Predict.jsx): `frontend/src/pages/Predict.jsx`
- [Dashboards and exploration](https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/pages/NationalDashboard.jsx): `frontend/src/pages/NationalDashboard.jsx`
- [Reports and comparisons](https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/pages/Reports.jsx): `frontend/src/pages/Reports.jsx`
- [Authenticated API client](https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Offline drafts](https://github.com/lowellowuor/amr_nexus-/blob/main/frontend/src/utils/offlineStorage.js): `frontend/src/utils/offlineStorage.js`

### Clinical prediction

- [Prediction endpoints](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/predictions.py): `Backend/amr_nexus_ml/src/api/routers/predictions.py`
- [Prediction service](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/services/prediction_service.py): `Backend/amr_nexus_ml/src/services/prediction_service.py`
- [Model and fallback](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/core/ml.py): `Backend/amr_nexus_ml/src/core/ml.py`
- [SHAP explanations](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/services/shap_service.py): `Backend/amr_nexus_ml/src/services/shap_service.py`

### Surveillance analytics

- [Analytics endpoints](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/analytics.py): `Backend/amr_nexus_ml/src/api/routers/analytics.py`
- [Pathogen exploration](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/analyst.py): `Backend/amr_nexus_ml/src/api/routers/analyst.py`
- [Historical isolate search](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/search_router.py): `Backend/amr_nexus_ml/src/api/routers/search_router.py`
- [Time-series forecasts](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/services/forecast_service.py): `Backend/amr_nexus_ml/src/services/forecast_service.py`

### Alerts and governance

- [Alert lifecycle](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/alerts.py): `Backend/amr_nexus_ml/src/api/routers/alerts.py`
- [Notification dispatch](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/services/notification_service.py): `Backend/amr_nexus_ml/src/services/notification_service.py`
- [Audit trail](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/core/audit_middleware.py): `Backend/amr_nexus_ml/src/core/audit_middleware.py`
- [Identity and user rights](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/api/routers/user_router.py): `Backend/amr_nexus_ml/src/api/routers/user_router.py`
- [Clinical narrative insights](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/services/llm_service.py): `Backend/amr_nexus_ml/src/services/llm_service.py`

### Backend runtime

- [ASGI application](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/main.py): `Backend/amr_nexus_ml/src/main.py`
- [Application database](https://github.com/lowellowuor/amr_nexus-/blob/main/Backend/amr_nexus_ml/src/db/models.py): `Backend/amr_nexus_ml/src/db/models.py`

### Other components

- **Clinician or analyst**
- **Google Gemini**
- **Email and SMS providers**

## Connections

- Clinician or analyst → Authenticated app routes: uses
- Authenticated app routes → Isolate prediction: routes to
- Authenticated app routes → Dashboards and exploration: routes to
- Authenticated app routes → Reports and comparisons: routes to
- Isolate prediction → Authenticated API client: requests API
- Dashboards and exploration → Authenticated API client: requests API
- Reports and comparisons → Authenticated API client: requests API
- Isolate prediction → Offline drafts: saves drafts
- Authenticated API client → ASGI application: sends requests
- ASGI application → Prediction endpoints: dispatches
- ASGI application → Analytics endpoints: dispatches
- ASGI application → Pathogen exploration: dispatches
- ASGI application → Historical isolate search: dispatches
- ASGI application → Alert lifecycle: dispatches
- ASGI application → Identity and user rights: dispatches
- Prediction endpoints → Prediction service: requests prediction
- Prediction service → Model and fallback: runs inference
- Prediction service → SHAP explanations: requests explanation
- Prediction endpoints → Application database: records outcomes
- Analytics endpoints → Application database: queries surveillance data
- Historical isolate search → Application database: queries isolates
- ASGI application → Time-series forecasts: requests forecast
- Time-series forecasts → Application database: reads surveillance data
- Alert lifecycle → Notification dispatch: dispatches notifications
- Notification dispatch → Email and SMS providers: sends email or SMS
- ASGI application → Audit trail: records privileged actions
- Identity and user rights → Application database: manages user data
- Prediction endpoints → Clinical narrative insights: requests insight
- Clinical narrative insights → Google Gemini: generates narrative