# arghyacr7/public-grievance-intelligence-platform architecture

> Architecture diagram of the GitHub repository arghyacr7/public-grievance-intelligence-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arghyacr7/public-grievance-intelligence-platform
- Repository: https://github.com/arghyacr7/public-grievance-intelligence-platform

## Overview

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: [`backend/routes/complaints.py`](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/routes/complaints.py) (Complaint routes), [`frontend/src/components`](https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/frontend/src/components) (UI components), [`frontend/src/main.jsx`](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/frontend/src/main.jsx) (Client app), [`backend/routes/auth.py`](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/routes/auth.py) (Auth routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_backend["Backend"]
  node_n_main["API app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_n_server["Server runner<br/>Uvicorn launcher<br/>[run_server.py]"]
  node_n_routes_auth["Auth routes<br/>HTTP routes<br/>[auth.py]"]
  node_n_routes_complaints["Complaint routes<br/>HTTP routes<br/>[complaints.py]"]
  node_n_auth_utils["Auth logic<br/>JWT/OAuth helpers<br/>[auth_utils.py]"]
  node_n_db[("Database<br/>Async persistence<br/>[database.py]")]
  node_n_models["Data models<br/>ORM models<br/>[models.py]"]
  node_n_schemas["API schemas<br/>Contracts<br/>[schemas.py]"]
  node_n_ai_detector["Detector<br/>Vision inference<br/>[detector.py]"]
  node_n_ai_caption["Captioning<br/>Vision-to-text<br/>[captioning.py]"]
  node_n_ai_severity["Severity<br/>Prioritization<br/>[severity.py]"]
  node_n_ai_duplicate["Duplicate check<br/>Similarity<br/>[duplicate.py]"]
  node_n_ai_llm["LLM enrich<br/>Generative AI<br/>[llm.py]"]
  node_n_email["Email service<br/>Outbound notifications<br/>[email_utils.py]"]
end

subgraph group_grp_frontend["Frontend"]
  node_n_front_main["Client app<br/>React entrypoint<br/>[main.jsx]"]
  node_n_front_api["API client<br/>Client boundary<br/>[client.js]"]
  node_n_pages["Pages<br/>Portal views"]
  node_n_components["UI components<br/>Shared widgets"]
  node_n_theme(("Theme context<br/>UI state<br/>[ThemeContext.jsx]"))
end

subgraph group_grp_ml["ML Assets"]
  node_n_models_dir[("Model artifacts<br/>ML outputs")]
  node_n_grievance_models[("Training workspace<br/>ML data")]
  node_n_ml_train["Train scripts<br/>ML training"]
end

subgraph group_grp_ops["Ops"]
  node_n_uploads[("Uploads<br/>Runtime storage")]
  node_n_migrate["DB migrate<br/>Migration script<br/>[migrate_db.py]"]
  node_n_seed["Admin seed<br/>Bootstrap script<br/>[seed_admin.py]"]
end

node_n_server -->|"starts"| node_n_main
node_n_main -->|"mounts"| node_n_routes_auth
node_n_main -->|"mounts"| node_n_routes_complaints
node_n_routes_auth -->|"uses"| node_n_auth_utils
node_n_routes_auth -->|"triggers"| node_n_email
node_n_routes_auth -->|"validates"| node_n_schemas
node_n_routes_complaints -->|"persists"| node_n_models
node_n_routes_complaints -->|"queries"| node_n_db
node_n_routes_complaints -->|"enriches"| node_n_ai_detector
node_n_routes_complaints -->|"enriches"| node_n_ai_caption
node_n_routes_complaints -->|"scores"| node_n_ai_severity
node_n_routes_complaints -->|"checks"| node_n_ai_duplicate
node_n_routes_complaints -->|"summarizes"| node_n_ai_llm
node_n_routes_complaints -->|"stores"| node_n_uploads
node_n_routes_complaints -->|"notifies"| node_n_email
node_n_models -->|"mapped to"| node_n_db
node_n_schemas -->|"mirrors"| node_n_models
node_n_migrate -->|"prepares"| node_n_db
node_n_seed -->|"initializes"| node_n_db
node_n_front_main -->|"renders"| node_n_pages
node_n_front_main -->|"calls"| node_n_front_api
node_n_front_main -->|"composes"| node_n_components
node_n_front_main -->|"provides"| node_n_theme
node_n_pages -->|"uses"| node_n_components
node_n_components -->|"fetches"| node_n_front_api
node_n_components -->|"displays"| node_n_ai_llm
node_n_components -->|"shows media"| node_n_uploads
node_n_ml_train -->|"trains on"| node_n_grievance_models
node_n_ml_train -->|"writes"| node_n_models_dir
node_n_routes_complaints -.->|"influenced by"| node_n_models_dir

click node_n_main "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/main.py"
click node_n_server "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/run_server.py"
click node_n_routes_auth "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/routes/auth.py"
click node_n_routes_complaints "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/routes/complaints.py"
click node_n_auth_utils "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/auth_utils.py"
click node_n_db "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/database.py"
click node_n_models "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/models.py"
click node_n_schemas "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/schemas.py"
click node_n_ai_detector "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/ai/detector.py"
click node_n_ai_caption "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/ai/captioning.py"
click node_n_ai_severity "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/ai/severity.py"
click node_n_ai_duplicate "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/ai/duplicate.py"
click node_n_ai_llm "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/ai/llm.py"
click node_n_email "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/email_utils.py"
click node_n_front_main "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/frontend/src/main.jsx"
click node_n_front_api "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/frontend/src/api/client.js"
click node_n_pages "https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/frontend/src/pages"
click node_n_components "https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/frontend/src/components"
click node_n_theme "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/frontend/src/context/ThemeContext.jsx"
click node_n_models_dir "https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/runs"
click node_n_grievance_models "https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/grievance_models"
click node_n_ml_train "https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/ml_models"
click node_n_uploads "https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/uploads"
click node_n_migrate "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/migrate_db.py"
click node_n_seed "https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/seed_admin.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_n_main,node_n_server,node_n_routes_auth,node_n_routes_complaints,node_n_auth_utils,node_n_db,node_n_models,node_n_schemas,node_n_ai_detector,node_n_ai_caption,node_n_ai_severity,node_n_ai_duplicate,node_n_ai_llm,node_n_email toneBlue
class node_n_front_main,node_n_front_api,node_n_pages,node_n_components,node_n_theme toneAmber
class node_n_models_dir,node_n_grievance_models,node_n_ml_train toneMint
class node_n_uploads,node_n_migrate,node_n_seed toneRose
```

## Components

### Backend

FastAPI app, domain logic, persistence, auth, notifications, and AI enrichment.

- [API app](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/main.py): FastAPI entrypoint · Primary backend application startup. · `main.py`
- [Server runner](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/run_server.py): Uvicorn launcher · Alternative backend start script. · `run_server.py`
- [Auth routes](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/routes/auth.py): HTTP routes · Identity, login, session, and reset endpoints. · `backend/routes/auth.py`
- [Complaint routes](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/routes/complaints.py): HTTP routes · Complaint submission, tracking, review, and lifecycle APIs. · `backend/routes/complaints.py`
- [Auth logic](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/auth_utils.py): JWT/OAuth helpers · Password handling, token logic, and shared auth primitives. · `backend/auth_utils.py`
- [Database](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/database.py): Async persistence · Database connection and async access layer. · `backend/database.py`
- [Data models](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/models.py): ORM models · Core persisted entities and relationships. · `backend/models.py`
- [API schemas](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/schemas.py): Contracts · Request and response shapes for the API boundary. · `backend/schemas.py`
- [Detector](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/ai/detector.py): Vision inference · Image/object detection for complaint evidence. · `backend/ai/detector.py`
- [Captioning](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/ai/captioning.py): Vision-to-text · Generates textual context from uploaded images. · `backend/ai/captioning.py`
- [Severity](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/ai/severity.py): Prioritization · Estimates complaint urgency and priority. · `backend/ai/severity.py`
- [Duplicate check](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/ai/duplicate.py): Similarity · Detects repeated or near-duplicate complaints. · `backend/ai/duplicate.py`
- [LLM enrich](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/ai/llm.py): Generative AI · Produces higher-level complaint enrichment and summaries. · `backend/ai/llm.py`
- [Email service](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/backend/email_utils.py): Outbound notifications · 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](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/frontend/src/main.jsx): React entrypoint · Frontend bootstrap and application shell. · `frontend/src/main.jsx`
- [API client](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/frontend/src/api/client.js): Client boundary · Browser-side API integration layer. · `frontend/src/api/client.js`
- [Pages](https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/frontend/src/pages): Portal views · Citizen and officer journeys across the portal. · `frontend/src/pages`
- [UI components](https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/frontend/src/components): Shared widgets · Annotated media, maps, and officer profile views. · `frontend/src/components`
- [Theme context](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/frontend/src/context/ThemeContext.jsx): UI state · 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](https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/runs): ML outputs · Trained model configs, metrics, and experiment outputs. · `runs`
- [Training workspace](https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/grievance_models): ML data · Datasets, notebooks, and training assets for grievance models. · `grievance_models`
- [Train scripts](https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/ml_models): ML training · Scripts that build or fine-tune classification and segmentation models. · `ml_models`

### Ops

Startup, migration, configuration, uploads, and validation scripts.

- [Uploads](https://github.com/arghyacr7/public-grievance-intelligence-platform/tree/main/uploads): Runtime storage · Stored complaint images and submitted media. · `uploads`
- [DB migrate](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/migrate_db.py): Migration script · Database setup and schema migration workflow. · `migrate_db.py`
- [Admin seed](https://github.com/arghyacr7/public-grievance-intelligence-platform/blob/main/seed_admin.py): Bootstrap script · Creates or seeds initial administrative data. · `seed_admin.py`

## Connections

- 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.