lakshya0402/parkpulse-ai

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.