How arghyacr7/public-grievance-intelligence-platform works
1. Repository shape
This is a two-tier civic-issues system: a Python/FastAPI backend plus a React/Vite frontend. The backend owns authentication, complaint lifecycle, AI inference, persistence, and notifications; the frontend is a citizen/officer portal that consumes the API.
2. Backend entrypoints and runtime
The backend appears to be started from main.py and/or run_server.py, with DB setup/migration handled separately by migrate_db.py. The stack is Python + FastAPI/Uvicorn, with async database access via backend/database.py and SQLite as the primary store.
3. API boundary
HTTP routes are split into backend/routes/auth.py and backend/routes/complaints.py. That boundary is important: auth endpoints handle identity/session flows, while complaints endpoints handle complaint creation, status tracking, review, and AI-enriched metadata.
4. Domain and persistence layer
backend/models.py and backend/schemas.py define the core data model and API contracts. This layer is the shape of the system’s state: users, complaints, and likely complaint attributes such as category, severity, image references, location, and tracking metadata.
5. Authentication subsystem
backend/auth_utils.py implements local auth primitives such as password/JWT handling, while the README indicates Google OAuth support as well. So there are two identity paths feeding the same user/session boundary: local credentials and third-party login.
6. AI inference pipeline
The backend/ai/ package is the intelligence layer. It is split by concern:
- detector.py for image/object detection
- captioning.py for generating textual context from images
- severity.py for complaint prioritization
- duplicate.py for deduplication or similarity checks
- llm.py for generative/LLM-backed enrichment
This suggests the complaint flow is not just CRUD; uploaded evidence is analyzed before or during persistence.
7. Complaint processing flow
The likely backend data path is: user submits complaint + image/location → backend validates/authenticates request → AI modules enrich the complaint with labels/caption/severity/dup-checks → complaint record is stored in SQLite → client later reads tracked status or dashboards. That pipeline is the main architecture diagram axis.
8. Notification side effects
backend/email_utils.py implies outbound email notifications, probably for password reset and/or complaint updates. This is a separate side-effect boundary from the core API and database flow, and likely triggered from auth and complaint events.
9. Frontend structure
The frontend lives under frontend/src and is organized by pages, components, API client, and theme context. Major pages include Home, About, Auth, Dashboard, CitizenPortal, TrackComplaint, ResetPassword, and Contact, showing distinct user journeys for citizens and internal users.
10. Frontend integration points
frontend/src/api/client.js is the API boundary on the client side. UI components such as AnnotatedImage, MapView, and OfficerProfile indicate the frontend renders AI-enriched media, geospatial complaint data, and officer-related views rather than only forms and tables.
11. Geospatial and review UI
MapView.jsx is a meaningful subsystem because the README calls out interactive mapping. Complaints likely carry coordinates, and the map is used to visualize incident distribution and status. AnnotatedImage.jsx suggests the frontend also displays image overlays or detection results coming back from the backend.
12. Model artifacts and training workspace
The grievance_models/, ml_models/, and runs/ directories indicate this repo includes both product code and training/evaluation outputs. There are YOLOv8 segmentation/classification datasets for potholes and garbage, plus notebooks/logs/results from model training. This means AI model development is part of the repository, not an external dependency only.
13. Upload and generated asset boundaries
uploads/ is the runtime storage boundary for user-submitted media. runs/ holds generated training/inference artifacts. In architecture terms, uploaded complaint images flow into the backend/AI layer, while model outputs and training artifacts remain local files rather than being stored exclusively in the database.
14. Operational and deployment concerns
.env.example, vercel.json, and the frontend Vite config indicate separate deployment concerns for backend and frontend. The README also references SQLite, JWT secret configuration, and Google API keys, so external services are limited but materially important: Google AI/OAuth and email delivery, with SQLite as the persistence anchor.
15. Validation and evaluation scripts
test_api.py, test_ai.py, test_blip.py, test_groq.py, and eval_both.py show the project has standalone validation scripts for API and model behavior. That implies a development workflow where AI outputs can be checked independently of the web app, reinforcing the separation between inference logic and user-facing routes.
Main entry points: complaints.py Complaint routes · components UI components · main.jsx Client app · auth.py Auth routes
Components 25
Backend
FastAPI app, domain logic, persistence, auth, notifications, and AI enrichment.
- API app · Primary backend application startup.
main.py - Server runner · Alternative backend start script.
run_server.py - Auth routes · Identity, login, session, and reset endpoints.
backend/routes/auth.py - Complaint routes · Complaint submission, tracking, review, and lifecycle APIs.
backend/routes/complaints.py - Auth logic · Password handling, token logic, and shared auth primitives.
backend/auth_utils.py - Database · Database connection and async access layer.
backend/database.py - Data models · Core persisted entities and relationships.
backend/models.py - API schemas · Request and response shapes for the API boundary.
backend/schemas.py - Detector · Image/object detection for complaint evidence.
backend/ai/detector.py - Captioning · Generates textual context from uploaded images.
backend/ai/captioning.py - Severity · Estimates complaint urgency and priority.
backend/ai/severity.py - Duplicate check · Detects repeated or near-duplicate complaints.
backend/ai/duplicate.py - LLM enrich · Produces higher-level complaint enrichment and summaries.
backend/ai/llm.py - Email service · Sends email notifications for auth and complaint events.
backend/email_utils.py
Frontend
React/Vite citizen and officer portal that consumes the API.
- Client app · Frontend bootstrap and application shell.
frontend/src/main.jsx - API client · Browser-side API integration layer.
frontend/src/api/client.js - Pages · Citizen and officer journeys across the portal.
frontend/src/pages - UI components · Annotated media, maps, and officer profile views.
frontend/src/components - Theme context · Shared presentation context for the frontend.
frontend/src/context/ThemeContext.jsx
ML Assets
Training data, notebooks, and generated model artifacts for grievance AI.
- Model artifacts · Trained model configs, metrics, and experiment outputs.
runs - Training workspace · Datasets, notebooks, and training assets for grievance models.
grievance_models - Train scripts · Scripts that build or fine-tune classification and segmentation models.
ml_models
Ops
Startup, migration, configuration, uploads, and validation scripts.
- Uploads · Stored complaint images and submitted media.
uploads - DB migrate · Database setup and schema migration workflow.
migrate_db.py - Admin seed · Creates or seeds initial administrative data.
seed_admin.py
Connections 30
- Server runner → API app: starts · Launches the backend app process.
- API app → Auth routes: mounts · Exposes authentication endpoints.
- API app → Complaint routes: mounts · Exposes complaint endpoints.
- Auth routes → Auth logic: uses · Delegates auth primitives and token handling.
- Auth routes → Email service: triggers · Sends auth-related notifications.
- Auth routes → API schemas: validates · Uses request and response contracts.
- Complaint routes → Data models: persists · Reads and writes complaint and user state.
- Complaint routes → Database: queries · Uses async database access.
- Complaint routes → Detector: enriches · Runs image detection on uploaded evidence.
- Complaint routes → Captioning: enriches · Generates descriptive context from images.
- Complaint routes → Severity: scores · Assigns priority or severity.
- Complaint routes → Duplicate check: checks · Flags repeated complaints.
- Complaint routes → LLM enrich: summarizes · Adds generative enrichment when needed.
- Complaint routes → Uploads: stores · Accepts and references uploaded media.
- Complaint routes → Email service: notifies · Emits complaint status emails.
- Data models → Database: mapped to · Persists through the database layer.
- API schemas → Data models: mirrors · API contracts reflect the core domain state.
- DB migrate → Database: prepares · Sets up the database before runtime.
- Admin seed → Database: initializes · Creates starter admin data in storage.
- Client app → Pages: renders · Loads application views and routes.
- Client app → API client: calls · Uses the API integration boundary.
- Client app → UI components: composes · Builds screens from shared components.
- Client app → Theme context: provides · Shares theme state across the UI.
- Pages → UI components: uses · Pages depend on shared visual widgets.
- UI components → API client: fetches · Components request backend data through the client.
- UI components → LLM enrich: displays · Shows AI-enriched content returned by the backend.
- UI components → Uploads: shows media · Renders complaint image evidence.
- Train scripts → Training workspace: trains on · Consumes datasets and notebooks.
- Train scripts → Model artifacts: writes · Produces model runs and evaluation outputs.
- Complaint routes → Model artifacts: influenced by · Complaint AI behavior depends on trained artifacts.