# siddharth-g06/idai architecture

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

- Interactive diagram: https://gitdiagram.com/siddharth-g06/idai
- Repository: https://github.com/siddharth-g06/idai

## Overview

IDAI is a civic accountability dashboard: manifesto promises are extracted and categorized, compared with news evidence, verified, and scored; voters then explore results by party, year, and category in a bilingual web app. The documented pipeline and sampled frontend show the main workflow. Backend API internals and several UI areas were not excerpted, so those connections rely on README statements or are omitted where evidence is insufficient.

Main entry points: [`frontend/src/App.jsx`](https://github.com/siddharth-g06/idai/blob/main/frontend/src/App.jsx) (Route Application), [`frontend/src/pages/Home.jsx`](https://github.com/siddharth-g06/idai/blob/main/frontend/src/pages/Home.jsx) (Summary Dashboard), [`frontend/src/pages/PartyPage.jsx`](https://github.com/siddharth-g06/idai/blob/main/frontend/src/pages/PartyPage.jsx) (Party Promise View), [`backend/data`](https://github.com/siddharth-g06/idai/tree/main/backend/data) (Computed JSON Data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Evidence Pipeline"]
  node_parser["Promise Extraction"]
  node_news["News Ingestion<br/>[news_fetcher.py]"]
  node_matcher["Semantic Matching<br/>[matcher.py]"]
  node_verifier["Match Verification<br/>[llm_verifier.py]"]
  node_scorer["Date-Aware Scoring<br/>[scorer.py]"]
  node_orchestrator["Pipeline Runner<br/>[run_pipeline.py]"]
end

subgraph group_backend["Data Service"]
  node_jsondata[("Computed JSON Data")]
  node_api["FastAPI Service<br/>[main.py]"]
  node_keepalive["Health Keepalive<br/>[keepalive.py]"]
end

subgraph group_frontend["Dashboard"]
  node_app["Route Application<br/>[App.jsx]"]
  node_home["Summary Dashboard<br/>[Home.jsx]"]
  node_party["Party Promise View<br/>[PartyPage.jsx]"]
  node_compare["Party Comparison<br/>[Compare.jsx]"]
  node_about["About Page<br/>[About.jsx]"]
  node_api_client["API Client<br/>[client.js]"]
  node_hooks["Data Hooks"]
end

subgraph group_ui["Interface Components"]
  node_promise_card["Promise Card<br/>[PromiseCard.jsx]"]
  node_score_ring["Score Ring<br/>[ScoreRing.jsx]"]
  node_navigation["Navigation<br/>[BottomNav.jsx]"]
  node_empty_state["Empty State<br/>[EmptyState.jsx]"]
  node_error_state["Error State<br/>[ErrorState.jsx]"]
  node_language["Language Context"]
  node_design["Design System<br/>[design-system.js]"]
end

node_voters(("Voters"))
node_manifestos["Manifesto PDFs"]
node_hosting["News Sources"]

node_manifestos -->|"provides PDFs"| node_parser
node_orchestrator -->|"runs parsing"| node_parser
node_orchestrator -->|"runs fetching"| node_news
node_orchestrator -->|"runs matching"| node_matcher
node_orchestrator -->|"runs scoring"| node_scorer
node_parser -->|"writes promises"| node_jsondata
node_hosting -->|"supplies articles"| node_news
node_news -->|"stores articles"| node_jsondata
node_jsondata -->|"provides inputs"| node_matcher
node_matcher -->|"verifies matches"| node_verifier
node_matcher -->|"provides matches"| node_scorer
node_scorer -->|"writes scores"| node_jsondata
node_jsondata -->|"serves JSON"| node_api
node_keepalive -->|"pings health"| node_api
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_party
node_app -->|"routes to"| node_compare
node_app -->|"routes to"| node_about
node_home -->|"loads summaries"| node_hooks
node_party -->|"loads promises"| node_hooks
node_hooks -->|"calls endpoints"| node_api_client
node_api_client -->|"requests data"| node_api
node_party -->|"renders promises"| node_promise_card
node_home -->|"renders scores"| node_score_ring
node_compare -->|"loads comparison"| node_api_client
node_home -->|"renders navigation"| node_navigation
node_party -->|"renders navigation"| node_navigation
node_home -->|"shows empty state"| node_empty_state
node_party -->|"shows errors"| node_error_state
node_app -->|"provides language"| node_language
node_language -->|"enables bilingual UI"| node_voters
node_promise_card -->|"uses styles"| node_design

click node_parser "https://github.com/siddharth-g06/idai/blob/main/backend/manifesto_parser.py"
click node_news "https://github.com/siddharth-g06/idai/blob/main/backend/news_fetcher.py"
click node_matcher "https://github.com/siddharth-g06/idai/blob/main/backend/matcher.py"
click node_verifier "https://github.com/siddharth-g06/idai/blob/main/backend/llm_verifier.py"
click node_scorer "https://github.com/siddharth-g06/idai/blob/main/backend/scorer.py"
click node_orchestrator "https://github.com/siddharth-g06/idai/blob/main/backend/run_pipeline.py"
click node_jsondata "https://github.com/siddharth-g06/idai/tree/main/backend/data"
click node_api "https://github.com/siddharth-g06/idai/blob/main/backend/main.py"
click node_keepalive "https://github.com/siddharth-g06/idai/blob/main/backend/keepalive.py"
click node_app "https://github.com/siddharth-g06/idai/blob/main/frontend/src/App.jsx"
click node_home "https://github.com/siddharth-g06/idai/blob/main/frontend/src/pages/Home.jsx"
click node_party "https://github.com/siddharth-g06/idai/blob/main/frontend/src/pages/PartyPage.jsx"
click node_compare "https://github.com/siddharth-g06/idai/blob/main/frontend/src/pages/Compare.jsx"
click node_about "https://github.com/siddharth-g06/idai/blob/main/frontend/src/pages/About.jsx"
click node_api_client "https://github.com/siddharth-g06/idai/blob/main/frontend/src/api/client.js"
click node_hooks "https://github.com/siddharth-g06/idai/tree/main/frontend/src/hooks"
click node_promise_card "https://github.com/siddharth-g06/idai/blob/main/frontend/src/components/PromiseCard.jsx"
click node_score_ring "https://github.com/siddharth-g06/idai/blob/main/frontend/src/components/ScoreRing.jsx"
click node_navigation "https://github.com/siddharth-g06/idai/blob/main/frontend/src/components/BottomNav.jsx"
click node_empty_state "https://github.com/siddharth-g06/idai/blob/main/frontend/src/components/EmptyState.jsx"
click node_error_state "https://github.com/siddharth-g06/idai/blob/main/frontend/src/components/ErrorState.jsx"
click node_language "https://github.com/siddharth-g06/idai/blob/main/frontend/src/i18n/LanguageContext.jsx"
click node_design "https://github.com/siddharth-g06/idai/blob/main/frontend/src/styles/design-system.js"

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_parser,node_news,node_matcher,node_verifier,node_scorer,node_orchestrator toneBlue
class node_jsondata,node_api,node_keepalive toneAmber
class node_app,node_home,node_party,node_compare,node_about,node_api_client,node_hooks toneMint
class node_promise_card,node_score_ring,node_navigation,node_empty_state,node_error_state,node_language,node_design toneRose
class node_voters,node_manifestos,node_hosting toneIndigo
```

## Components

### Evidence Pipeline

- [Promise Extraction](https://github.com/siddharth-g06/idai/blob/main/backend/manifesto_parser.py): `backend/manifesto_parser.py`
- [News Ingestion](https://github.com/siddharth-g06/idai/blob/main/backend/news_fetcher.py): `backend/news_fetcher.py`
- [Semantic Matching](https://github.com/siddharth-g06/idai/blob/main/backend/matcher.py): `backend/matcher.py`
- [Match Verification](https://github.com/siddharth-g06/idai/blob/main/backend/llm_verifier.py): `backend/llm_verifier.py`
- [Date-Aware Scoring](https://github.com/siddharth-g06/idai/blob/main/backend/scorer.py): `backend/scorer.py`
- [Pipeline Runner](https://github.com/siddharth-g06/idai/blob/main/backend/run_pipeline.py): `backend/run_pipeline.py`

### Data Service

- [Computed JSON Data](https://github.com/siddharth-g06/idai/tree/main/backend/data): `backend/data`
- [FastAPI Service](https://github.com/siddharth-g06/idai/blob/main/backend/main.py): `backend/main.py`
- [Health Keepalive](https://github.com/siddharth-g06/idai/blob/main/backend/keepalive.py): `backend/keepalive.py`

### Dashboard

- [Route Application](https://github.com/siddharth-g06/idai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Summary Dashboard](https://github.com/siddharth-g06/idai/blob/main/frontend/src/pages/Home.jsx): `frontend/src/pages/Home.jsx`
- [Party Promise View](https://github.com/siddharth-g06/idai/blob/main/frontend/src/pages/PartyPage.jsx): `frontend/src/pages/PartyPage.jsx`
- [Party Comparison](https://github.com/siddharth-g06/idai/blob/main/frontend/src/pages/Compare.jsx): `frontend/src/pages/Compare.jsx`
- [About Page](https://github.com/siddharth-g06/idai/blob/main/frontend/src/pages/About.jsx): `frontend/src/pages/About.jsx`
- [API Client](https://github.com/siddharth-g06/idai/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Data Hooks](https://github.com/siddharth-g06/idai/tree/main/frontend/src/hooks): `frontend/src/hooks`

### Interface Components

- [Promise Card](https://github.com/siddharth-g06/idai/blob/main/frontend/src/components/PromiseCard.jsx): `frontend/src/components/PromiseCard.jsx`
- [Score Ring](https://github.com/siddharth-g06/idai/blob/main/frontend/src/components/ScoreRing.jsx): `frontend/src/components/ScoreRing.jsx`
- [Navigation](https://github.com/siddharth-g06/idai/blob/main/frontend/src/components/BottomNav.jsx): `frontend/src/components/BottomNav.jsx`
- [Empty State](https://github.com/siddharth-g06/idai/blob/main/frontend/src/components/EmptyState.jsx): `frontend/src/components/EmptyState.jsx`
- [Error State](https://github.com/siddharth-g06/idai/blob/main/frontend/src/components/ErrorState.jsx): `frontend/src/components/ErrorState.jsx`
- [Language Context](https://github.com/siddharth-g06/idai/blob/main/frontend/src/i18n/LanguageContext.jsx): `frontend/src/i18n/LanguageContext.jsx`
- [Design System](https://github.com/siddharth-g06/idai/blob/main/frontend/src/styles/design-system.js): `frontend/src/styles/design-system.js`

### Other components

- **Voters**
- **Manifesto PDFs**
- **News Sources**

## Connections

- Manifesto PDFs → Promise Extraction: provides PDFs (evidence: `README.md`)
- Pipeline Runner → Promise Extraction: runs parsing (evidence: `backend/run_pipeline.py`)
- Pipeline Runner → News Ingestion: runs fetching (evidence: `backend/run_pipeline.py`)
- Pipeline Runner → Semantic Matching: runs matching (evidence: `backend/run_pipeline.py`)
- Pipeline Runner → Date-Aware Scoring: runs scoring (evidence: `backend/run_pipeline.py`)
- Promise Extraction → Computed JSON Data: writes promises (evidence: `README.md`)
- News Sources → News Ingestion: supplies articles (evidence: `README.md`)
- News Ingestion → Computed JSON Data: stores articles (evidence: `README.md`)
- Computed JSON Data → Semantic Matching: provides inputs (evidence: `README.md`)
- Semantic Matching → Match Verification: verifies matches (evidence: `README.md`)
- Semantic Matching → Date-Aware Scoring: provides matches (evidence: `README.md`)
- Date-Aware Scoring → Computed JSON Data: writes scores (evidence: `README.md`)
- Computed JSON Data → FastAPI Service: serves JSON (evidence: `README.md`)
- Health Keepalive → FastAPI Service: pings health (evidence: `README.md`)
- Route Application → Summary Dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Route Application → Party Promise View: routes to (evidence: `frontend/src/App.jsx`)
- Route Application → Party Comparison: routes to (evidence: `frontend/src/App.jsx`)
- Route Application → About Page: routes to (evidence: `frontend/src/App.jsx`)
- Summary Dashboard → Data Hooks: loads summaries (evidence: `frontend/src/pages/Home.jsx`)
- Party Promise View → Data Hooks: loads promises (evidence: `frontend/src/pages/PartyPage.jsx`)
- Data Hooks → API Client: calls endpoints (evidence: `frontend/src/hooks/usePromises.js`)
- API Client → FastAPI Service: requests data (evidence: `README.md`)
- Party Promise View → Promise Card: renders promises (evidence: `frontend/src/pages/PartyPage.jsx`)
- Summary Dashboard → Score Ring: renders scores (evidence: `frontend/src/pages/Home.jsx`)
- Party Comparison → API Client: loads comparison (evidence: `frontend/src/pages/Compare.jsx`)
- Summary Dashboard → Navigation: renders navigation (evidence: `frontend/src/pages/Home.jsx`)
- Party Promise View → Navigation: renders navigation (evidence: `frontend/src/pages/PartyPage.jsx`)
- Summary Dashboard → Empty State: shows empty state (evidence: `frontend/src/pages/Home.jsx`)
- Party Promise View → Error State: shows errors (evidence: `frontend/src/pages/PartyPage.jsx`)
- Route Application → Language Context: provides language (evidence: `frontend/src/main.jsx`)
- Language Context → Voters: enables bilingual UI (evidence: `README.md`)
- Promise Card → Design System: uses styles (evidence: `frontend/src/components/PromiseCard.jsx`)
