How 000shreeharish000/snapaidd works
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: server.py FastAPI API · PoliceDashboard.js Police UI · CitizenDashboard.js Citizen UI · AuthContext.js Auth Context
Components 17
Frontend
React client apps and shared UI
- Citizen UI · Citizen-facing submission and profile flows
frontend/src/pages/CitizenDashboard.js - Police UI · Operator dashboard for triage and case updates
frontend/src/pages/PoliceDashboard.js - Auth Pages · Login, registration, and auth callback flow
frontend/src/pages/LoginPage.js - Submission Flow · SOS, review, and success steps for incident intake
frontend/src/pages/SOSPage.js - Public Info · Emergency numbers and low-friction safety access
frontend/src/pages/EmergencyNumbersPage.js - Auth Context · Session and role state shared across the React app
frontend/src/contexts/AuthContext.js - Language Context · Language selection and localization state
frontend/src/contexts/LanguageContext.js - Route Guard · Protects authenticated and role-restricted routes
frontend/src/components/ProtectedRoute.js - UI System · Shared design-system components used across pages
frontend/src/components/ui/button.jsx
Backend
FastAPI API, realtime updates, and persistence
- FastAPI API · Main server entrypoint for REST and websocket traffic
backend/server.py - Auth Service · JWT login, registration, bcrypt hashing, and role checks
backend/server.py - Incident Intake · Receives citizen reports and structured incident packets
backend/server.py - AI Enrichment · Calls Gemini for classification, severity, confidence, and summary
backend/server.py - Realtime Gateway · Pushes live incident updates to the police dashboard
backend/server.py - Incident Store · SQLAlchemy-backed storage for users, incidents, status, and logs
backend/server.py
External
Third-party and data stores
- Gemini API · Multimodal model used for media understanding and scoring
- PostgreSQL · Primary system of record for app state
Connections 21
- 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