# arsahadu/district_intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/arsahadu/district_intelligence
- Repository: https://github.com/arsahadu/district_intelligence

## Overview

This repository is a District Intelligence Platform foundation. The documented user workflow is a dashboard checking backend health and displaying stored records; the README explicitly says database and intelligence features are out of scope for the current vertical slice. The tree also contains record/source APIs and an ingestion package with domain connectors, normalization, and raw storage. Those ingestion modules are represented, but their runtime orchestration is unclear from the available excerpts, so unsupported connections are omitted.

Main entry points: [`backend/app/api/records.py`](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/api/records.py) (Records API), [`frontend/src/pages/Dashboard.jsx`](https://github.com/arsahadu/district_intelligence/blob/main/frontend/src/pages/Dashboard.jsx) (Dashboard), [`backend/app/api/sources.py`](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/api/sources.py) (Sources API), [`backend/app/main.py`](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/main.py) (API application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Collector dashboard"]
  node_app["App entry<br/>[App.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_header["Header<br/>[Header.jsx]"]
  node_status_card["Status card<br/>[StatusCard.jsx]"]
end

subgraph group_backend["FastAPI backend"]
  node_api_app["API application<br/>[main.py]"]
  node_health_api["Health endpoint<br/>[health.py]"]
  node_records_api["Records API<br/>[records.py]"]
  node_sources_api["Sources API<br/>[sources.py]"]
  node_record_schema["Record schema<br/>[common_record.py]"]
  node_source_schema["Source schema<br/>[source.py]"]
  node_record_model["Record model<br/>[common_record.py]"]
  node_source_model["Source model<br/>[source.py]"]
  node_record_service["Record service<br/>[record_service.py]"]
  node_database[("Database session<br/>[database.py]")]
end

subgraph group_ingestion["Data ingestion"]
  node_news_connector["Dinamalar connector<br/>[dinamalar.py]"]
  node_article_model["Source article<br/>[source_article.py]"]
  node_news_normalizer["News normalizer<br/>[news.py]"]
  node_common_record["Ingestion record<br/>[common_record.py]"]
  node_raw_storage[("Raw JSON storage<br/>[raw_storage.py]")]
  node_agmarknet["Agmarknet connector<br/>[agmarknet.py]"]
  node_flood_connector["Flood connector<br/>[flood.py]"]
  node_weather_connector["Open-Meteo connector<br/>[open_meteo.py]"]
  node_location_normalizer["Location normalizer<br/>[location.py]"]
end

node_user(("Dashboard user"))

node_user -->|"opens dashboard"| node_app
node_app -->|"renders"| node_dashboard
node_dashboard -->|"requests health and records"| node_api_client
node_dashboard -->|"renders"| node_header
node_dashboard -->|"renders"| node_status_card
node_api_app -->|"registers route"| node_health_api
node_api_app -->|"registers route"| node_records_api
node_api_app -->|"registers route"| node_sources_api
node_records_api -->|"gets session"| node_database
node_records_api -->|"queries and writes"| node_record_model
node_records_api -->|"queries and writes"| node_source_model
node_records_api -->|"validates and serializes"| node_record_schema
node_sources_api -->|"uses session"| node_database
node_sources_api -->|"uses schema"| node_source_schema
node_sources_api -->|"uses service"| node_record_service
node_record_service -->|"creates and queries"| node_record_model
node_record_service -->|"creates and queries"| node_source_model
node_news_connector -->|"produces articles"| node_article_model
node_news_connector -->|"uses normalizer"| node_news_normalizer
node_news_connector -->|"stores raw data"| node_raw_storage
node_news_normalizer -->|"converts article"| node_article_model
node_news_normalizer -->|"creates record"| node_common_record

click node_app "https://github.com/arsahadu/district_intelligence/blob/main/frontend/src/App.jsx"
click node_dashboard "https://github.com/arsahadu/district_intelligence/blob/main/frontend/src/pages/Dashboard.jsx"
click node_api_client "https://github.com/arsahadu/district_intelligence/blob/main/frontend/src/services/api.js"
click node_header "https://github.com/arsahadu/district_intelligence/blob/main/frontend/src/components/Header.jsx"
click node_status_card "https://github.com/arsahadu/district_intelligence/blob/main/frontend/src/components/StatusCard.jsx"
click node_api_app "https://github.com/arsahadu/district_intelligence/blob/main/backend/app/main.py"
click node_health_api "https://github.com/arsahadu/district_intelligence/blob/main/backend/app/api/health.py"
click node_records_api "https://github.com/arsahadu/district_intelligence/blob/main/backend/app/api/records.py"
click node_sources_api "https://github.com/arsahadu/district_intelligence/blob/main/backend/app/api/sources.py"
click node_record_schema "https://github.com/arsahadu/district_intelligence/blob/main/backend/app/schemas/common_record.py"
click node_source_schema "https://github.com/arsahadu/district_intelligence/blob/main/backend/app/schemas/source.py"
click node_record_model "https://github.com/arsahadu/district_intelligence/blob/main/backend/app/models/common_record.py"
click node_source_model "https://github.com/arsahadu/district_intelligence/blob/main/backend/app/models/source.py"
click node_record_service "https://github.com/arsahadu/district_intelligence/blob/main/backend/app/services/record_service.py"
click node_database "https://github.com/arsahadu/district_intelligence/blob/main/backend/app/db/database.py"
click node_news_connector "https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/connectors/news/dinamalar.py"
click node_article_model "https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/models/source_article.py"
click node_news_normalizer "https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/normalizers/news.py"
click node_common_record "https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/models/common_record.py"
click node_raw_storage "https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/storage/raw_storage.py"
click node_agmarknet "https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/connectors/agriculture/agmarknet.py"
click node_flood_connector "https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/connectors/disaster/flood.py"
click node_weather_connector "https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/connectors/weather/open_meteo.py"
click node_location_normalizer "https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/normalizers/location.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_dashboard,node_api_client,node_header,node_status_card,node_user toneBlue
class node_api_app,node_health_api,node_records_api,node_sources_api,node_record_schema,node_source_schema,node_record_model,node_source_model,node_record_service,node_database toneAmber
class node_news_connector,node_article_model,node_news_normalizer,node_common_record,node_raw_storage,node_agmarknet,node_flood_connector,node_weather_connector,node_location_normalizer toneMint
```

## Components

### Collector dashboard

- [App entry](https://github.com/arsahadu/district_intelligence/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Dashboard](https://github.com/arsahadu/district_intelligence/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [API client](https://github.com/arsahadu/district_intelligence/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Header](https://github.com/arsahadu/district_intelligence/blob/main/frontend/src/components/Header.jsx): `frontend/src/components/Header.jsx`
- [Status card](https://github.com/arsahadu/district_intelligence/blob/main/frontend/src/components/StatusCard.jsx): `frontend/src/components/StatusCard.jsx`

### FastAPI backend

- [API application](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/main.py): `backend/app/main.py`
- [Health endpoint](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/api/health.py): `backend/app/api/health.py`
- [Records API](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/api/records.py): `backend/app/api/records.py`
- [Sources API](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/api/sources.py): `backend/app/api/sources.py`
- [Record schema](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/schemas/common_record.py): `backend/app/schemas/common_record.py`
- [Source schema](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/schemas/source.py): `backend/app/schemas/source.py`
- [Record model](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/models/common_record.py): `backend/app/models/common_record.py`
- [Source model](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/models/source.py): `backend/app/models/source.py`
- [Record service](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/services/record_service.py): `backend/app/services/record_service.py`
- [Database session](https://github.com/arsahadu/district_intelligence/blob/main/backend/app/db/database.py): `backend/app/db/database.py`

### Data ingestion

- [Dinamalar connector](https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/connectors/news/dinamalar.py): `ingestion/app/connectors/news/dinamalar.py`
- [Source article](https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/models/source_article.py): `ingestion/app/models/source_article.py`
- [News normalizer](https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/normalizers/news.py): `ingestion/app/normalizers/news.py`
- [Ingestion record](https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/models/common_record.py): `ingestion/app/models/common_record.py`
- [Raw JSON storage](https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/storage/raw_storage.py): `ingestion/app/storage/raw_storage.py`
- [Agmarknet connector](https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/connectors/agriculture/agmarknet.py): `ingestion/app/connectors/agriculture/agmarknet.py`
- [Flood connector](https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/connectors/disaster/flood.py): `ingestion/app/connectors/disaster/flood.py`
- [Open-Meteo connector](https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/connectors/weather/open_meteo.py): `ingestion/app/connectors/weather/open_meteo.py`
- [Location normalizer](https://github.com/arsahadu/district_intelligence/blob/main/ingestion/app/normalizers/location.py): `ingestion/app/normalizers/location.py`

### Other components

- **Dashboard user**

## Connections

- Dashboard user → App entry: opens dashboard (evidence: `README.md`)
- App entry → Dashboard: renders (evidence: `frontend/src/App.jsx`)
- Dashboard → API client: requests health and records (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Header: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Status card: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- API application → Health endpoint: registers route (evidence: `backend/app/main.py`)
- API application → Records API: registers route (evidence: `backend/app/main.py`)
- API application → Sources API: registers route (evidence: `backend/app/main.py`)
- Records API → Database session: gets session (evidence: `backend/app/api/records.py`)
- Records API → Record model: queries and writes (evidence: `backend/app/api/records.py`)
- Records API → Source model: queries and writes (evidence: `backend/app/api/records.py`)
- Records API → Record schema: validates and serializes (evidence: `backend/app/api/records.py`)
- Sources API → Database session: uses session (evidence: `backend/app/api/sources.py`)
- Sources API → Source schema: uses schema (evidence: `backend/app/api/sources.py`)
- Sources API → Record service: uses service (evidence: `backend/app/api/sources.py`)
- Record service → Record model: creates and queries (evidence: `backend/app/services/record_service.py`)
- Record service → Source model: creates and queries (evidence: `backend/app/services/record_service.py`)
- Dinamalar connector → Source article: produces articles (evidence: `ingestion/app/connectors/news/dinamalar.py`)
- Dinamalar connector → News normalizer: uses normalizer (evidence: `ingestion/app/connectors/news/dinamalar.py`)
- Dinamalar connector → Raw JSON storage: stores raw data (evidence: `ingestion/app/connectors/news/dinamalar.py`)
- News normalizer → Source article: converts article (evidence: `ingestion/app/normalizers/news.py`)
- News normalizer → Ingestion record: creates record (evidence: `ingestion/app/normalizers/news.py`)
