# zish19/jan-setu architecture

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

- Interactive diagram: https://gitdiagram.com/zish19/jan-setu
- Repository: https://github.com/zish19/jan-setu

## Overview

1. **Repository shape**
   - The repo is split into two deployable applications: a **FastAPI backend** in `backend/` and a **Next.js frontend** in `frontend/`.
   - The backend owns all AI/data processing, persistence, and optimization logic; the frontend is a presentation and interaction layer that calls backend APIs.

2. **Primary product flow**
   - The system centers on a civic-intelligence pipeline: **citizen submissions → AI enrichment → issue clustering → budget optimization → explanation/trust views**.
   - This flow is explicitly reflected in backend services and in the frontend routes for citizen intake, MP dashboard, audit, and public trust.

3. **Backend API boundary**
   - `backend/app/api/v1/` is organized by domain: `assistant`, `dashboard`, `optimize`, `signals`, `clusters`, `audit`, and `trust`.
   - Each router exposes a slice of the platform rather than a generic CRUD API, which suggests the backend is the authoritative orchestration layer for AI analysis, reporting, and recommendations.

4. **AI processing pipeline**
   - The core backend service layer is split into specialized steps: `translation`, `vision`, `categorization`, `priority`, `geo_verification`, `embedding`, and `clustering`.
   - These services transform raw multilingual, multimodal complaints into normalized, structured issue records and grouped “verified issues” suitable for decision-making.

5. **Model and prompt boundary**
   - `backend/app/core/gemini.py` is the Google Gemini integration point, while `backend/app/prompts/` contains task-specific prompt templates for categorization, translation, vision, and explanation.
   - This makes the AI behavior configurable and separates prompt design from business logic.

6. **Optimization subsystem**
   - `backend/app/services/optimizer.py` is the budget-allocation engine, and `backend/app/services/orchestrator.py` likely coordinates the full sequence from issue discovery to solver input.
   - The README indicates the optimization model uses **OR-Tools CP-SAT** to allocate a fixed MPLADS-style budget under category constraints; architecturally, this is the decision-making boundary between “data understanding” and “policy-constrained funding.”

7. **Persistence and domain storage**
   - `backend/app/repositories/` and `backend/app/schemas/firestore.py` indicate a repository abstraction over **Firestore**-backed documents.
   - The architecture likely stores processed complaints, clustered issues, solver outputs, audit artifacts, and trust metrics there, with repositories insulating services from direct datastore details.

8. **Trust, audit, and explainability**
   - The `assistant`, `audit`, and `trust` APIs support explainability and public accountability rather than core intake.
   - `backend/app/services/explanation.py` and the `priority_explanation` prompt suggest the system generates human-readable rationales for why a project was prioritized or deprioritized, with `audit` and `trust` serving oversight and public-facing verification use cases.

9. **Backend platform concerns**
   - `backend/app/core/` holds cross-cutting infrastructure: auth, Firebase integration, logging, exceptions, and settings.
   - This indicates a layered backend where configuration, auth, and external service setup are centralized and reused across all routers and services.

10. **Frontend application structure**
   - The frontend uses the **Next.js App Router** with routes for `/dashboard`, `/audit`, `/trust`, and a landing page.
   - Feature code is split into reusable UI and domain-specific components: `CitizenFlow`, `AskJanSetuPanel`, `BudgetOptimizerPanel`, and `ConstituencyMap`.

11. **Frontend data access and state**
   - `frontend/src/services/` wraps backend API calls per domain, while `frontend/src/hooks/useSignals.ts` and `frontend/src/store/` manage reactive state.
   - This shows a clean separation: UI components do not talk to the backend directly; they consume domain services and state stores, which is important for diagramming the frontend’s internal boundaries.

12. **Dashboard and interaction model**
   - The dashboard is designed as a synchronized operational surface: map, signals, budget optimizer, and assistant feedback are coordinated in one view.
   - The presence of `pipeline.store.ts` and dashboard feature components suggests live state propagation from backend-derived data into multiple coordinated UI panels.

13. **Presenter/demo subsystem**
   - `frontend/src/store/demo.machine.ts`, `demo.store.ts`, and `config/demo-script.json` implement an automated demo flow.
   - This is a separate UX orchestration layer that drives the app through a scripted sequence for presentations, distinct from the normal user workflow.

14. **Infrastructure and deployment**
   - Both frontend and backend have Dockerfiles, and the root `docker-compose.yml` supports local multi-service startup.
   - `backend/scripts/seed_demo.py` suggests the backend can preload sample data for demonstrations, which is useful when diagramming development/test environments versus production data flow.

15. **What to show in an architecture diagram**
   - The most important boundaries are: **frontend UI → domain API services → AI enrichment/optimization services → Firestore persistence**.
   - A second boundary is **explainability and trust**: the assistant, audit, and public trust surfaces all read from the same normalized/clustered data and solver outputs, but present them differently for MPs, auditors, and citizens.

Main entry points: [`frontend/src/services`](https://github.com/zish19/jan-setu/tree/main/frontend/src/services) (API Services), [`frontend/src/app`](https://github.com/zish19/jan-setu/tree/main/frontend/src/app) (Next.js App), [`backend/app/services/orchestrator.py`](https://github.com/zish19/jan-setu/blob/main/backend/app/services/orchestrator.py) (Orchestrator), [`backend/app/services`](https://github.com/zish19/jan-setu/tree/main/backend/app/services) (AI Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_app["FastAPI App<br/>entrypoint<br/>[main.py]"]
  node_backend_api["Domain APIs<br/>routers"]
  node_backend_orchestrator["Orchestrator<br/>workflow<br/>[orchestrator.py]"]
  node_backend_ai_pipeline["AI Pipeline<br/>service bundle"]
  node_backend_optimizer{{"Budget Solver<br/>optimization<br/>[optimizer.py]"}}
  node_backend_explanation["Explainability<br/>[explanation.py]"]
  node_backend_prompts["Prompt Library<br/>prompts"]
  node_backend_gemini(("Gemini<br/>llm integration<br/>[gemini.py]"))
  node_backend_platform["Core Platform<br/>infrastructure"]
  node_backend_repos["Repositories<br/>data access"]
  node_backend_firestore[("Firestore Schemas<br/>storage model<br/>[firestore.py]")]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["Next.js App<br/>entrypoint"]
  node_frontend_citizen["Citizen Flow<br/>ui flow<br/>[CitizenFlow.tsx]"]
  node_frontend_dashboard["Dashboard<br/>page<br/>[page.tsx]"]
  node_frontend_trust["Trust View<br/>page<br/>[page.tsx]"]
  node_frontend_audit["Audit View<br/>page<br/>[page.tsx]"]
  node_frontend_panels["Dashboard Panels<br/>ui components"]
  node_frontend_api["API Services<br/>client services"]
  node_frontend_state["State Layer<br/>stores and hooks"]
  node_frontend_demo(("Demo Orchestrator<br/>ux automation<br/>[demo.machine.ts]"))
end

node_backend_app -->|"mounts"| node_backend_api
node_backend_api -->|"coordinates"| node_backend_orchestrator
node_backend_orchestrator -->|"enriches"| node_backend_ai_pipeline
node_backend_ai_pipeline -->|"calls"| node_backend_gemini
node_backend_ai_pipeline -->|"templates"| node_backend_prompts
node_backend_ai_pipeline -->|"stores"| node_backend_repos
node_backend_repos -->|"maps"| node_backend_firestore
node_backend_orchestrator -->|"solves"| node_backend_optimizer
node_backend_optimizer -->|"persists"| node_backend_repos
node_backend_orchestrator -->|"explains"| node_backend_explanation
node_backend_explanation -->|"uses"| node_backend_prompts
node_backend_api -->|"relies on"| node_backend_platform
node_frontend_app -->|"renders"| node_frontend_citizen
node_frontend_app -->|"renders"| node_frontend_dashboard
node_frontend_app -->|"renders"| node_frontend_trust
node_frontend_app -->|"renders"| node_frontend_audit
node_frontend_dashboard -->|"composes"| node_frontend_panels
node_frontend_panels -->|"fetches"| node_frontend_api
node_frontend_citizen -->|"submits"| node_frontend_api
node_frontend_trust -->|"reads"| node_frontend_api
node_frontend_audit -->|"reads"| node_frontend_api
node_frontend_api -->|"requests"| node_backend_api
node_frontend_api -->|"updates"| node_frontend_state
node_frontend_state -->|"drives"| node_frontend_demo

click node_backend_app "https://github.com/zish19/jan-setu/blob/main/backend/app/main.py"
click node_backend_api "https://github.com/zish19/jan-setu/tree/main/backend/app/api/v1"
click node_backend_orchestrator "https://github.com/zish19/jan-setu/blob/main/backend/app/services/orchestrator.py"
click node_backend_ai_pipeline "https://github.com/zish19/jan-setu/tree/main/backend/app/services"
click node_backend_optimizer "https://github.com/zish19/jan-setu/blob/main/backend/app/services/optimizer.py"
click node_backend_explanation "https://github.com/zish19/jan-setu/blob/main/backend/app/services/explanation.py"
click node_backend_prompts "https://github.com/zish19/jan-setu/tree/main/backend/app/prompts"
click node_backend_gemini "https://github.com/zish19/jan-setu/blob/main/backend/app/core/gemini.py"
click node_backend_platform "https://github.com/zish19/jan-setu/tree/main/backend/app/core"
click node_backend_repos "https://github.com/zish19/jan-setu/tree/main/backend/app/repositories"
click node_backend_firestore "https://github.com/zish19/jan-setu/blob/main/backend/app/schemas/firestore.py"
click node_frontend_app "https://github.com/zish19/jan-setu/tree/main/frontend/src/app"
click node_frontend_citizen "https://github.com/zish19/jan-setu/blob/main/frontend/src/features/citizen/CitizenFlow.tsx"
click node_frontend_dashboard "https://github.com/zish19/jan-setu/blob/main/frontend/src/app/dashboard/page.tsx"
click node_frontend_trust "https://github.com/zish19/jan-setu/blob/main/frontend/src/app/trust/page.tsx"
click node_frontend_audit "https://github.com/zish19/jan-setu/blob/main/frontend/src/app/audit/page.tsx"
click node_frontend_panels "https://github.com/zish19/jan-setu/tree/main/frontend/src/features/dashboard"
click node_frontend_api "https://github.com/zish19/jan-setu/tree/main/frontend/src/services"
click node_frontend_state "https://github.com/zish19/jan-setu/tree/main/frontend/src/store"
click node_frontend_demo "https://github.com/zish19/jan-setu/blob/main/frontend/src/store/demo.machine.ts"

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_backend_app,node_backend_api,node_backend_orchestrator,node_backend_ai_pipeline,node_backend_optimizer,node_backend_explanation,node_backend_prompts,node_backend_gemini,node_backend_platform,node_backend_repos,node_backend_firestore toneBlue
class node_frontend_app,node_frontend_citizen,node_frontend_dashboard,node_frontend_trust,node_frontend_audit,node_frontend_panels,node_frontend_api,node_frontend_state,node_frontend_demo toneAmber
```

## Components

### Backend

FastAPI application for AI processing, persistence, and optimization

- [FastAPI App](https://github.com/zish19/jan-setu/blob/main/backend/app/main.py): entrypoint · API server and application bootstrap · `backend/app/main.py`
- [Domain APIs](https://github.com/zish19/jan-setu/tree/main/backend/app/api/v1): routers · Versioned HTTP boundary for assistant, dashboard, optimize, signals, clusters, audit, and trust · `backend/app/api/v1`
- [Orchestrator](https://github.com/zish19/jan-setu/blob/main/backend/app/services/orchestrator.py): workflow · Coordinates intake, enrichment, clustering, and solver preparation · `backend/app/services/orchestrator.py`
- [AI Pipeline](https://github.com/zish19/jan-setu/tree/main/backend/app/services): service bundle · Translation, vision, categorization, priority, geo verification, embedding, and clustering · `backend/app/services`
- [Budget Solver](https://github.com/zish19/jan-setu/blob/main/backend/app/services/optimizer.py): optimization · CP-SAT allocation engine for constrained budget decisions · `backend/app/services/optimizer.py`
- [Explainability](https://github.com/zish19/jan-setu/blob/main/backend/app/services/explanation.py): service · Generates human-readable rationales for prioritization and outcomes · `backend/app/services/explanation.py`
- [Prompt Library](https://github.com/zish19/jan-setu/tree/main/backend/app/prompts): prompts · Task templates for translation, vision, categorization, and explanations · `backend/app/prompts`
- [Gemini](https://github.com/zish19/jan-setu/blob/main/backend/app/core/gemini.py): llm integration · Google Gemini client used by AI services · `backend/app/core/gemini.py`
- [Core Platform](https://github.com/zish19/jan-setu/tree/main/backend/app/core): infrastructure · Auth, Firebase, logging, settings, and shared exceptions · `backend/app/core`
- [Repositories](https://github.com/zish19/jan-setu/tree/main/backend/app/repositories): data access · Repository abstraction over persisted domain documents · `backend/app/repositories`
- [Firestore Schemas](https://github.com/zish19/jan-setu/blob/main/backend/app/schemas/firestore.py): storage model · Document shapes for stored complaints, clusters, solver outputs, and trust artifacts · `backend/app/schemas/firestore.py`

### Frontend

Next.js application for citizen, dashboard, audit, and trust experiences

- [Next.js App](https://github.com/zish19/jan-setu/tree/main/frontend/src/app): entrypoint · App Router shell for the web client · `frontend/src/app`
- [Citizen Flow](https://github.com/zish19/jan-setu/blob/main/frontend/src/features/citizen/CitizenFlow.tsx): ui flow · Intake experience for citizen submissions · `frontend/src/features/citizen/CitizenFlow.tsx`
- [Dashboard](https://github.com/zish19/jan-setu/blob/main/frontend/src/app/dashboard/page.tsx): page · Operational workspace for MPs and staff · `frontend/src/app/dashboard/page.tsx`
- [Trust View](https://github.com/zish19/jan-setu/blob/main/frontend/src/app/trust/page.tsx): page · Public-facing accountability and verification surface · `frontend/src/app/trust/page.tsx`
- [Audit View](https://github.com/zish19/jan-setu/blob/main/frontend/src/app/audit/page.tsx): page · Oversight and review surface for decisions and evidence · `frontend/src/app/audit/page.tsx`
- [Dashboard Panels](https://github.com/zish19/jan-setu/tree/main/frontend/src/features/dashboard): ui components · Map, assistant, and optimizer panels composed into the dashboard · `frontend/src/features/dashboard`
- [API Services](https://github.com/zish19/jan-setu/tree/main/frontend/src/services): client services · Typed backend API wrappers for assistant, dashboard, optimization, signals, and trust · `frontend/src/services`
- [State Layer](https://github.com/zish19/jan-setu/tree/main/frontend/src/store): stores and hooks · Reactive signal, pipeline, and demo state coordination · `frontend/src/store`
- [Demo Orchestrator](https://github.com/zish19/jan-setu/blob/main/frontend/src/store/demo.machine.ts): ux automation · Scripted presentation flow for walkthroughs and demos · `frontend/src/store/demo.machine.ts`

## Connections

- FastAPI App → Domain APIs: mounts · Application exposes versioned domain routers
- Domain APIs → Orchestrator: coordinates · API endpoints trigger the main workflow
- Orchestrator → AI Pipeline: enriches · Raw submissions are transformed into normalized issue records
- AI Pipeline → Gemini: calls · LLM-backed steps use Gemini for generation and analysis
- AI Pipeline → Prompt Library: templates · Task-specific prompt text guides each AI step
- AI Pipeline → Repositories: stores · Processed and clustered results are persisted through repositories
- Repositories → Firestore Schemas: maps · Repositories persist domain documents using Firestore schemas
- Orchestrator → Budget Solver: solves · Verified issues feed constrained budget allocation
- Budget Solver → Repositories: persists · Solver outputs are stored for downstream views
- Orchestrator → Explainability: explains · Prioritization and allocation outcomes are turned into human-readable rationale
- Explainability → Prompt Library: uses · Explanations are shaped by prompt templates
- Domain APIs → Core Platform: relies on · Routers share auth, Firebase, logging, settings, and error handling
- Next.js App → Citizen Flow: renders · Landing and intake experience
- Next.js App → Dashboard: renders · Operational dashboard route
- Next.js App → Trust View: renders · Public trust route
- Next.js App → Audit View: renders · Audit route
- Dashboard → Dashboard Panels: composes · Dashboard combines map, assistant, and optimizer panels
- Dashboard Panels → API Services: fetches · Panels call backend domain APIs through service wrappers
- Citizen Flow → API Services: submits · Citizen intake sends data through typed clients
- Trust View → API Services: reads · Trust page consumes backend verification and summary data
- Audit View → API Services: reads · Audit page consumes evidence and decision records
- API Services → Domain APIs: requests · Frontend services invoke backend HTTP endpoints
- API Services → State Layer: updates · Fetched data flows into signal and pipeline state
- State Layer → Demo Orchestrator: drives · Demo machine orchestrates scripted UI progression
