# 000shreeharish000/snapaidd architecture

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

- Interactive diagram: https://gitdiagram.com/000shreeharish000/snapaidd
- Repository: https://github.com/000shreeharish000/snapaidd

## Overview

1. **Repository shape**
   - This is a two-tier prototype: a **FastAPI backend** in `backend/` and a **React frontend** in `frontend/`.
   - The repo also contains product/design artifacts (`memory/PRD.md`, `design_guidelines.json`) and test outputs (`test_reports/`), which suggests this is a working prototype rather than a fully packaged production service.

2. **Core product boundary**
   - SnapAid is organized around two user roles:
     - **Citizens** who submit emergency media and details.
     - **Police operators** who review, triage, and update incidents.
   - That role split is central to the architecture and is enforced by authentication and route protection on both client and server.

3. **Backend as the system of record**
   - The backend is the central integration point for all sensitive operations: authentication, incident submission, AI enrichment, and dashboard data access.
   - `backend/server.py` is likely the main API entrypoint; the readme indicates it exposes REST endpoints plus **WebSockets** for live incident updates.
   - `backend_test.py` and the generated `test_reports/` indicate backend behavior is validated independently of the UI.

4. **Data model and persistence**
   - The backend is expected to persist users, incidents, statuses, and likely action logs in **PostgreSQL** via **SQLAlchemy ORM**.
   - The repo does not show migrations or a separate service layer, so the persistence boundary appears to be embedded in the backend application itself.
   - The system stores structured incident packets rather than raw media-only records, which is a key architectural distinction.

5. **AI and verification pipeline**
   - A major backend responsibility is calling the **Gemini Multimodal API** for media understanding.
   - The AI layer produces the incident’s **classification**, **severity score**, **confidence score**, and a contextual summary, and may also contribute to authenticity / synthetic-media detection.
   - In architecture terms, this is an external intelligence service behind the backend, not directly accessed by the frontend.

6. **Authentication and authorization**
   - The app uses **JWT-based auth** with **bcrypt password hashing** and role-based access control.
   - This creates a clear security boundary:
     - public access for login/register and emergency numbers,
     - authenticated citizen flows,
     - restricted police dashboard flows.
   - The frontend’s `ProtectedRoute` and `AuthContext` mirror the backend’s token/role enforcement.

7. **Real-time incident operations**
   - The police dashboard is not just a static page; it is fed by **live incident updates** over WebSockets.
   - This implies a push path from backend to dashboard for new incidents or status changes, alongside normal pull-based REST endpoints for initial loading and detail views.
   - The operational loop is: citizen submission → backend processing → live dashboard update → police status change → backend persistence.

8. **Frontend composition**
   - The frontend is a React app organized by concerns:
     - `pages/` for user flows such as login, register, citizen dashboard, police dashboard, SOS, review, success, profile, and emergency numbers.
     - `contexts/` for auth and language state.
     - `components/` for reusable UI and route protection.
   - `frontend/src/components/ui/` contains a large design-system style component set, indicating a component-driven UI built on a shared library rather than page-specific widgets.

9. **User-flow surfaces**
   - The frontend clearly separates the citizen journey from the police journey:
     - Citizen flow: capture/upload media, review AI output, submit incident, see success/rewards.
     - Police flow: authenticate, review incidents, filter by severity/status, inspect details, update case state.
   - `SOSPage`, `ReviewPage`, and `SuccessPage` suggest a guided submission pipeline rather than a single monolithic form.

10. **Localization and public info**
   - `LanguageContext` and `LanguageSelector` show **multi-language support** is a first-class frontend concern, covering English, Tamil, and Hindi.
   - `EmergencyNumbersPage` is a public, low-friction access surface that likely does not require authentication and serves as a safety utility separate from incident submission.

11. **Map and geospatial behavior**
   - The readme mentions an interactive geospatial dashboard, and the frontend references **Leaflet** in the tech stack.
   - That means incident records likely carry latitude/longitude, and the police dashboard visualizes incident locations to support dispatch prioritization.

12. **Frontend build/runtime tooling**
   - The frontend uses a modern React toolchain with **CRACO**, **Tailwind CSS**, and custom build plugins under `frontend/plugins/`.
   - The `health-check` and `visual-edits` plugins suggest nonstandard dev-server behavior, likely for internal tooling, live diagnostics, or UI-editing support during development.

13. **Boundary between public and operational trust**
   - The architecture is intentionally built to transform untrusted citizen media into trusted operational data before it reaches police operators.
   - That trust boundary is the main architectural theme: validation, classification, and scoring happen server-side before a record becomes actionable in the dashboard.

14. **What to draw in an architecture diagram**
   - Show three external actors/systems around the backend:
     - **Citizen client / React UI**
     - **Police dashboard / React UI**
     - **Gemini multimodal API**
   - Put **FastAPI** in the center, connected to **PostgreSQL** for persistence and **WebSockets** for real-time dashboard delivery.
   - Add auth as a horizontal concern across the app, with JWT/bcrypt and RBAC guarding the police side and protected citizen actions.

Main entry points: [`backend/server.py`](https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.py) (FastAPI API), [`frontend/src/pages/PoliceDashboard.js`](https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/pages/PoliceDashboard.js) (Police UI), [`frontend/src/pages/CitizenDashboard.js`](https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/pages/CitizenDashboard.js) (Citizen UI), [`frontend/src/contexts/AuthContext.js`](https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/contexts/AuthContext.js) (Auth Context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_citizen_ui["Citizen UI<br/>react app"]
  node_police_ui["Police UI<br/>react app<br/>[PoliceDashboard.js]"]
  node_auth_pages["Auth Pages<br/>route screens<br/>[LoginPage.js]"]
  node_submission_flow["Submission Flow<br/>guided flow<br/>[SOSPage.js]"]
  node_public_info["Public Info<br/>public page"]
  node_auth_context["Auth Context<br/>client state<br/>[AuthContext.js]"]
  node_language_context["Language Context<br/>client state<br/>[LanguageContext.js]"]
  node_route_guard["Route Guard<br/>access control<br/>[ProtectedRoute.js]"]
  node_ui_system["UI System<br/>component library<br/>[button.jsx]"]
end

subgraph group_backend["Backend"]
  node_backend_api["FastAPI API<br/>api entrypoint<br/>[server.py]"]
  node_api_auth["Auth Service<br/>security<br/>[server.py]"]
  node_incident_intake["Incident Intake<br/>workflow<br/>[server.py]"]
  node_ai_enrichment["AI Enrichment<br/>multimodal pipeline<br/>[server.py]"]
  node_realtime_gateway["Realtime Gateway<br/>websocket hub<br/>[server.py]"]
  node_persistence[("Incident Store<br/>orm persistence<br/>[server.py]")]
end

subgraph group_external["External"]
  node_gemini_api(("Gemini API<br/>external ai service"))
  node_postgresql[("PostgreSQL<br/>database")]
end

node_citizen_ui -->|"session state"| node_auth_context
node_police_ui -->|"session state"| node_auth_context
node_auth_pages -->|"sign in"| node_auth_context
node_route_guard -->|"protect routes"| node_auth_context
node_language_context -->|"localize"| node_citizen_ui
node_language_context -->|"localize"| node_police_ui
node_citizen_ui -->|"start report"| node_submission_flow
node_submission_flow -->|"submit incident"| node_backend_api
node_public_info -.->|"public access"| node_backend_api
node_backend_api -->|"authenticate"| node_api_auth
node_backend_api -->|"create case"| node_incident_intake
node_incident_intake -->|"analyze media"| node_ai_enrichment
node_ai_enrichment -->|"multimodal call"| node_gemini_api
node_incident_intake -->|"store record"| node_persistence
node_api_auth -->|"user data"| node_persistence
node_persistence -->|"read/write"| node_postgresql
node_realtime_gateway -->|"push updates"| node_police_ui
node_backend_api -->|"publish events"| node_realtime_gateway
node_police_ui -->|"load cases"| node_backend_api
node_police_ui -->|"restrict access"| node_route_guard
node_citizen_ui -->|"restrict access"| node_route_guard

click node_citizen_ui "https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/pages/CitizenDashboard.js"
click node_police_ui "https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/pages/PoliceDashboard.js"
click node_auth_pages "https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/pages/LoginPage.js"
click node_submission_flow "https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/pages/SOSPage.js"
click node_public_info "https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/pages/EmergencyNumbersPage.js"
click node_auth_context "https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/contexts/AuthContext.js"
click node_language_context "https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/contexts/LanguageContext.js"
click node_route_guard "https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/components/ProtectedRoute.js"
click node_ui_system "https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/components/ui/button.jsx"
click node_backend_api "https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.py"
click node_api_auth "https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.py"
click node_incident_intake "https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.py"
click node_ai_enrichment "https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.py"
click node_realtime_gateway "https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.py"
click node_persistence "https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.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_citizen_ui,node_police_ui,node_auth_pages,node_submission_flow,node_public_info,node_auth_context,node_language_context,node_route_guard,node_ui_system toneBlue
class node_backend_api,node_api_auth,node_incident_intake,node_ai_enrichment,node_realtime_gateway,node_persistence toneAmber
class node_gemini_api,node_postgresql toneMint
```

## Components

### Frontend

React client apps and shared UI

- [Citizen UI](https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/pages/CitizenDashboard.js): react app · Citizen-facing submission and profile flows · `frontend/src/pages/CitizenDashboard.js`
- [Police UI](https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/pages/PoliceDashboard.js): react app · Operator dashboard for triage and case updates · `frontend/src/pages/PoliceDashboard.js`
- [Auth Pages](https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/pages/LoginPage.js): route screens · Login, registration, and auth callback flow · `frontend/src/pages/LoginPage.js`
- [Submission Flow](https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/pages/SOSPage.js): guided flow · SOS, review, and success steps for incident intake · `frontend/src/pages/SOSPage.js`
- [Public Info](https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/pages/EmergencyNumbersPage.js): public page · Emergency numbers and low-friction safety access · `frontend/src/pages/EmergencyNumbersPage.js`
- [Auth Context](https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/contexts/AuthContext.js): client state · Session and role state shared across the React app · `frontend/src/contexts/AuthContext.js`
- [Language Context](https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/contexts/LanguageContext.js): client state · Language selection and localization state · `frontend/src/contexts/LanguageContext.js`
- [Route Guard](https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/components/ProtectedRoute.js): access control · Protects authenticated and role-restricted routes · `frontend/src/components/ProtectedRoute.js`
- [UI System](https://github.com/000shreeharish000/snapaidd/blob/main/frontend/src/components/ui/button.jsx): component library · Shared design-system components used across pages · `frontend/src/components/ui/button.jsx`

### Backend

FastAPI API, realtime updates, and persistence

- [FastAPI API](https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.py): api entrypoint · Main server entrypoint for REST and websocket traffic · `backend/server.py`
- [Auth Service](https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.py): security · JWT login, registration, bcrypt hashing, and role checks · `backend/server.py`
- [Incident Intake](https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.py): workflow · Receives citizen reports and structured incident packets · `backend/server.py`
- [AI Enrichment](https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.py): multimodal pipeline · Calls Gemini for classification, severity, confidence, and summary · `backend/server.py`
- [Realtime Gateway](https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.py): websocket hub · Pushes live incident updates to the police dashboard · `backend/server.py`
- [Incident Store](https://github.com/000shreeharish000/snapaidd/blob/main/backend/server.py): orm persistence · SQLAlchemy-backed storage for users, incidents, status, and logs · `backend/server.py`

### External

Third-party and data stores

- **Gemini API**: external ai service · Multimodal model used for media understanding and scoring
- **PostgreSQL**: database · Primary system of record for app state

## Connections

- Citizen UI → Auth Context: session state · Citizen screens read authentication and role state
- Police UI → Auth Context: session state · Dashboard gates and user state come from shared auth context
- Auth Pages → Auth Context: sign in · Login and registration populate client session state
- Route Guard → Auth Context: protect routes · Protected routes use auth and role information
- Language Context → Citizen UI: localize · Shared language selection affects citizen-facing screens
- Language Context → Police UI: localize · Shared language selection affects operator-facing screens
- Citizen UI → Submission Flow: start report · Citizen dashboard leads into the SOS and review flow
- Submission Flow → FastAPI API: submit incident · Completed reports are sent to the backend for processing
- Public Info → FastAPI API: public access · Low-friction pages still share the backend application boundary
- FastAPI API → Auth Service: authenticate · Server verifies credentials and role claims
- FastAPI API → Incident Intake: create case · Server transforms untrusted citizen input into structured incidents
- Incident Intake → AI Enrichment: analyze media · Media and details are enriched before becoming actionable
- AI Enrichment → Gemini API: multimodal call · Backend delegates media understanding to Gemini
- Incident Intake → Incident Store: store record · Validated incidents and metadata are written to storage
- Auth Service → Incident Store: user data · Users and roles are persisted through the ORM layer
- Incident Store → PostgreSQL: read/write · Application state is stored in PostgreSQL
- Realtime Gateway → Police UI: push updates · Live incident changes stream to the operator dashboard
- FastAPI API → Realtime Gateway: publish events · Backend emits incident lifecycle changes to the websocket layer
- Police UI → FastAPI API: load cases · Dashboard uses REST for initial lists and details
- Police UI → Route Guard: restrict access · Police routes are protected from unauthenticated access
- Citizen UI → Route Guard: restrict access · Citizen account and submission flows are protected where needed
