How zish19/jan-setu works
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: src/services API Services · app Next.js App · orchestrator.py Orchestrator · app/services AI Pipeline
Components 20
Backend
FastAPI application for AI processing, persistence, and optimization
- FastAPI App · API server and application bootstrap
backend/app/main.py - Domain APIs · Versioned HTTP boundary for assistant, dashboard, optimize, signals, clusters, audit, and trust
backend/app/api/v1 - Orchestrator · Coordinates intake, enrichment, clustering, and solver preparation
backend/app/services/orchestrator.py - AI Pipeline · Translation, vision, categorization, priority, geo verification, embedding, and clustering
backend/app/services - Budget Solver · CP-SAT allocation engine for constrained budget decisions
backend/app/services/optimizer.py - Explainability · Generates human-readable rationales for prioritization and outcomes
backend/app/services/explanation.py - Prompt Library · Task templates for translation, vision, categorization, and explanations
backend/app/prompts - Gemini · Google Gemini client used by AI services
backend/app/core/gemini.py - Core Platform · Auth, Firebase, logging, settings, and shared exceptions
backend/app/core - Repositories · Repository abstraction over persisted domain documents
backend/app/repositories - Firestore Schemas · 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 · App Router shell for the web client
frontend/src/app - Citizen Flow · Intake experience for citizen submissions
frontend/src/features/citizen/CitizenFlow.tsx - Dashboard · Operational workspace for MPs and staff
frontend/src/app/dashboard/page.tsx - Trust View · Public-facing accountability and verification surface
frontend/src/app/trust/page.tsx - Audit View · Oversight and review surface for decisions and evidence
frontend/src/app/audit/page.tsx - Dashboard Panels · Map, assistant, and optimizer panels composed into the dashboard
frontend/src/features/dashboard - API Services · Typed backend API wrappers for assistant, dashboard, optimization, signals, and trust
frontend/src/services - State Layer · Reactive signal, pipeline, and demo state coordination
frontend/src/store - Demo Orchestrator · Scripted presentation flow for walkthroughs and demos
frontend/src/store/demo.machine.ts
Connections 24
- 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