# lakshya0402/parkpulse-ai architecture

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

- Interactive diagram: https://gitdiagram.com/lakshya0402/parkpulse-ai
- Repository: https://github.com/lakshya0402/parkpulse-ai

## Overview

1. **Overall shape**
   - This is a two-tier system: a **React/Vite frontend** for investigation and planning workflows, and a **FastAPI backend** that owns data ingestion, storage, ML inference, and patrol prioritization.
   - The product goal is operational: turn historical Bengaluru traffic violation records into a map-based enforcement dashboard.

2. **Frontend boundary**
   - The frontend is a single-page app built with **React 18 + Vite + Tailwind**.
   - It is organized by user task into pages: **City Map, Analytics, Hotspot Explorer, Predict, Planner, Coverage, and Offenders**.
   - Shared UI lives in `components/common`, map rendering lives in `components/map`, and API access is centralized in `services/api.js`.

3. **Mapping and geospatial visualization**
   - The frontend uses the **Mappls Web Map SDK** to render the city map, heatmaps, cluster markers, and location popups.
   - This is the main visualization boundary: the backend provides cluster/risk data, while the frontend is responsible for map presentation and user interaction.

4. **Backend API layer**
   - The backend is a **FastAPI** app with route modules grouped by feature: `analytics`, `coverage`, `hotspots`, `offenders`, `planner`, and `predict`.
   - These routes are thin HTTP boundaries that expose precomputed analytics, live model predictions, patrol plans, and lookup data to the UI.

5. **Core data pipeline**
   - `app/core/data_pipeline.py` is the central bootstrap path for turning raw historical records into usable application assets.
   - On first startup, it downloads/processes the dataset, builds the database contents, and prepares model artifacts. The README indicates this is automatic and takes a few minutes on initial run.

6. **Persistence layer**
   - `app/models/db_models.py` defines the SQLAlchemy ORM schema, and `app/core/database.py` manages the DB connection/session.
   - The app supports **SQLite by default** for local use and **PostgreSQL** as an alternative deployment database.
   - This database stores the operational data the API serves: violation records, clusters, analytics aggregates, and related entities.

7. **ML artifacts and inference**
   - The repository includes a persisted **risk model** in `backend/model_cache/` (`risk_model.pkl` plus metadata).
   - The backend uses this cached model for prediction endpoints rather than retraining on each request, which keeps inference fast and isolates training from serving.

8. **Enforcement planner subsystem**
   - `app/services/planner.py` contains the logic for translating hotspot and risk outputs into an enforcement plan.
   - This is the decision-support layer: it takes officer count as input and returns prioritized patrol zones, allocation, and patrol windows.

9. **Analytics and exploration flow**
   - The backend exposes multiple derived views over the same violation dataset: temporal patterns, hotspot clusters, offender history, coverage gaps, and risk predictions.
   - The frontend consumes these outputs to support different workflows: broad situational awareness, hotspot drill-down, repeat-offender review, and tactical planning.

10. **Data and model generation dependencies**
   - The architecture relies on **pandas/numpy/geopandas** for data processing, **scikit-learn DBSCAN** for hotspot clustering, and **XGBoost** for risk prediction.
   - These are not just library details; they define the pipeline boundary between raw records, spatial clusters, and operational risk scores.

11. **Runtime and deployment boundary**
   - Backend runtime is Python 3.10+ with async web/database support via FastAPI and SQLAlchemy async; frontend runtime is Node.js 18+.
   - The only external service that materially affects the UI is **Mappls**, which requires a frontend SDK key and supplies map rendering.

12. **End-to-end flow**
   - Historical BTP violation data enters the backend pipeline, is cleaned and clustered, stored in the database, and summarized into analytics/model artifacts.
   - The frontend then queries the API, overlays the results on a live map, and exposes drill-down and planning pages for police operations.

Main entry points: [`backend/app/api`](https://github.com/lakshya0402/parkpulse-ai/tree/main/backend/app/api) (Route layer), [`backend/app/core/database.py`](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/core/database.py) (Database), [`frontend/src/App.jsx`](https://github.com/lakshya0402/parkpulse-ai/blob/main/frontend/src/App.jsx) (UI app), [`frontend/src/pages`](https://github.com/lakshya0402/parkpulse-ai/tree/main/frontend/src/pages) (Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["UI app<br/>React/Vite SPA<br/>[App.jsx]"]
  node_frontend_pages["Pages<br/>task views"]
  node_frontend_map["Map view<br/>Mappls rendering<br/>[MapContainer.jsx]"]
  node_frontend_common["Shared UI<br/>common components"]
  node_frontend_api["API client<br/>HTTP client<br/>[api.js]"]
  node_frontend_hooks["Hooks"]
end

subgraph group_backend["Backend"]
  node_backend_main["API app<br/>FastAPI entry<br/>[main.py]"]
  node_backend_routes["Route layer<br/>HTTP modules"]
  node_backend_analytics["Analytics<br/>derived views<br/>[analytics.py]"]
  node_backend_hotspots["Hotspots<br/>cluster API<br/>[hotspots.py]"]
  node_backend_offenders["Offenders<br/>history API<br/>[offenders.py]"]
  node_backend_coverage["Coverage<br/>gap API<br/>[coverage.py]"]
  node_backend_predict["Predict<br/>risk API<br/>[predict.py]"]
  node_backend_planner["Planner API<br/>plan API<br/>[planner.py]"]
  node_backend_pipeline["Data pipeline<br/>bootstrap ETL<br/>[data_pipeline.py]"]
  node_backend_db[("Database<br/>SQLAlchemy async<br/>[database.py]")]
  node_backend_models["ORM models<br/>schema layer<br/>[db_models.py]"]
  node_backend_service_planner["Plan engine<br/>decision support<br/>[planner.py]"]
  node_backend_model_cache["Risk model<br/>cached artifacts<br/>[risk_model.pkl]"]
end

node_frontend_app -->|"routes"| node_frontend_pages
node_frontend_app -->|"renders"| node_frontend_map
node_frontend_app -->|"uses"| node_frontend_common
node_frontend_app -->|"fetches"| node_frontend_api
node_frontend_app -->|"loads"| node_frontend_hooks
node_frontend_pages -->|"drives"| node_frontend_map
node_frontend_pages -->|"queries"| node_frontend_api
node_frontend_hooks -->|"initializes"| node_frontend_map
node_frontend_api -->|"calls"| node_backend_main
node_backend_main -->|"mounts"| node_backend_routes
node_backend_routes -->|"exposes"| node_backend_analytics
node_backend_routes -->|"exposes"| node_backend_hotspots
node_backend_routes -->|"exposes"| node_backend_offenders
node_backend_routes -->|"exposes"| node_backend_coverage
node_backend_routes -->|"exposes"| node_backend_predict
node_backend_routes -->|"exposes"| node_backend_planner
node_backend_analytics -->|"reads"| node_backend_db
node_backend_hotspots -->|"reads"| node_backend_db
node_backend_offenders -->|"reads"| node_backend_db
node_backend_coverage -->|"reads"| node_backend_db
node_backend_predict -->|"loads"| node_backend_model_cache
node_backend_predict -->|"reads"| node_backend_db
node_backend_planner -->|"delegates"| node_backend_service_planner
node_backend_service_planner -->|"reads"| node_backend_db
node_backend_pipeline -->|"builds"| node_backend_db
node_backend_pipeline -->|"produces"| node_backend_model_cache
node_backend_models -->|"maps"| node_backend_db
node_backend_main -.->|"bootstraps"| node_backend_pipeline

click node_frontend_app "https://github.com/lakshya0402/parkpulse-ai/blob/main/frontend/src/App.jsx"
click node_frontend_pages "https://github.com/lakshya0402/parkpulse-ai/tree/main/frontend/src/pages"
click node_frontend_map "https://github.com/lakshya0402/parkpulse-ai/blob/main/frontend/src/components/map/MapContainer.jsx"
click node_frontend_common "https://github.com/lakshya0402/parkpulse-ai/tree/main/frontend/src/components/common"
click node_frontend_api "https://github.com/lakshya0402/parkpulse-ai/blob/main/frontend/src/services/api.js"
click node_frontend_hooks "https://github.com/lakshya0402/parkpulse-ai/tree/main/frontend/src/hooks"
click node_backend_main "https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/main.py"
click node_backend_routes "https://github.com/lakshya0402/parkpulse-ai/tree/main/backend/app/api"
click node_backend_analytics "https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/api/analytics.py"
click node_backend_hotspots "https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/api/hotspots.py"
click node_backend_offenders "https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/api/offenders.py"
click node_backend_coverage "https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/api/coverage.py"
click node_backend_predict "https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/api/predict.py"
click node_backend_planner "https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/api/planner.py"
click node_backend_pipeline "https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/core/data_pipeline.py"
click node_backend_db "https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/core/database.py"
click node_backend_models "https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/models/db_models.py"
click node_backend_service_planner "https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/services/planner.py"
click node_backend_model_cache "https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/model_cache/risk_model.pkl"

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_frontend_app,node_frontend_pages,node_frontend_map,node_frontend_common,node_frontend_api,node_frontend_hooks toneBlue
class node_backend_main,node_backend_routes,node_backend_analytics,node_backend_hotspots,node_backend_offenders,node_backend_coverage,node_backend_predict,node_backend_planner,node_backend_pipeline,node_backend_db,node_backend_models,node_backend_service_planner,node_backend_model_cache toneAmber
```

## Components

### Frontend

React/Vite SPA for map-based investigation and planning

- [UI app](https://github.com/lakshya0402/parkpulse-ai/blob/main/frontend/src/App.jsx): React/Vite SPA · Single-page frontend shell and routing entry · `frontend/src/App.jsx`
- [Pages](https://github.com/lakshya0402/parkpulse-ai/tree/main/frontend/src/pages): task views · City map, analytics, hotspots, prediction, planning, coverage, and offenders screens · `frontend/src/pages`
- [Map view](https://github.com/lakshya0402/parkpulse-ai/blob/main/frontend/src/components/map/MapContainer.jsx): Mappls rendering · City map, heatmaps, cluster markers, and popups · `frontend/src/components/map/MapContainer.jsx`
- [Shared UI](https://github.com/lakshya0402/parkpulse-ai/tree/main/frontend/src/components/common): common components · Reusable sidebar and interface elements · `frontend/src/components/common`
- [API client](https://github.com/lakshya0402/parkpulse-ai/blob/main/frontend/src/services/api.js): HTTP client · Centralized backend API access for all pages · `frontend/src/services/api.js`
- [Hooks](https://github.com/lakshya0402/parkpulse-ai/tree/main/frontend/src/hooks): client hooks · Data fetching and Mappls loader integration · `frontend/src/hooks`

### Backend

FastAPI services for ingestion, analytics, inference, and planning

- [API app](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/main.py): FastAPI entry · Backend application bootstrap and route assembly · `backend/app/main.py`
- [Route layer](https://github.com/lakshya0402/parkpulse-ai/tree/main/backend/app/api): HTTP modules · Feature routes for analytics, coverage, hotspots, offenders, planner, and predict · `backend/app/api`
- [Analytics](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/api/analytics.py): derived views · Temporal patterns and aggregate violation analysis · `backend/app/api/analytics.py`
- [Hotspots](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/api/hotspots.py): cluster API · Hotspot and spatial risk lookup endpoints · `backend/app/api/hotspots.py`
- [Offenders](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/api/offenders.py): history API · Repeat-offender and offender detail endpoints · `backend/app/api/offenders.py`
- [Coverage](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/api/coverage.py): gap API · Patrol coverage and enforcement gap endpoints · `backend/app/api/coverage.py`
- [Predict](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/api/predict.py): risk API · Live risk scoring and prediction endpoints · `backend/app/api/predict.py`
- [Planner API](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/api/planner.py): plan API · Patrol planning endpoints that turn risk into allocations · `backend/app/api/planner.py`
- [Data pipeline](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/core/data_pipeline.py): bootstrap ETL · Initial download, cleaning, clustering, and artifact generation · `backend/app/core/data_pipeline.py`
- [Database](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/core/database.py): SQLAlchemy async · Connection and session management for persistent operational data · `backend/app/core/database.py`
- [ORM models](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/models/db_models.py): schema layer · Database schema for violations, clusters, analytics, and related entities · `backend/app/models/db_models.py`
- [Plan engine](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/app/services/planner.py): decision support · Transforms hotspot and risk outputs into patrol zones and windows · `backend/app/services/planner.py`
- [Risk model](https://github.com/lakshya0402/parkpulse-ai/blob/main/backend/model_cache/risk_model.pkl): cached artifacts · Persisted model and metadata used for fast inference · `backend/model_cache/risk_model.pkl`

## Connections

- UI app → Pages: routes · App shell organizes the task pages
- UI app → Map view: renders · Primary city map visualization boundary
- UI app → Shared UI: uses · Shared layout and controls
- UI app → API client: fetches · Central API access for all views
- UI app → Hooks: loads · Client-side data and map loader hooks
- Pages → Map view: drives · Map-centric pages consume map rendering
- Pages → API client: queries · Pages request analytics, hotspots, offenders, coverage, predictions, and plans
- Hooks → Map view: initializes · Loads the Mappls SDK before map rendering
- API client → API app: calls · Frontend talks to the FastAPI backend
- API app → Route layer: mounts · Main app wires feature routes
- Route layer → Analytics: exposes · Analytics endpoints
- Route layer → Hotspots: exposes · Hotspot lookup endpoints
- Route layer → Offenders: exposes · Offender history endpoints
- Route layer → Coverage: exposes · Coverage endpoints
- Route layer → Predict: exposes · Risk prediction endpoints
- Route layer → Planner API: exposes · Patrol planning endpoints
- Analytics → Database: reads · Aggregates stored operational data
- Hotspots → Database: reads · Spatial queries over persisted records and clusters
- Offenders → Database: reads · Retrieves offender and violation history
- Coverage → Database: reads · Coverage calculations from stored data
- Predict → Risk model: loads · Uses cached risk model artifacts
- Predict → Database: reads · Pulls features and context for scoring
- Planner API → Plan engine: delegates · Planner API calls the decision engine
- Plan engine → Database: reads · Uses hotspot and risk data from persistence
- Data pipeline → Database: builds · Initial pipeline populates the database
- Data pipeline → Risk model: produces · Pipeline prepares reusable model artifacts
- ORM models → Database: maps · ORM layer defines persisted entities
- API app → Data pipeline: bootstraps · Initial startup triggers data preparation