CrimeMap

Geospatial Crime Intelligence, Analytics & Decision Support — a cloud-deployed, locally runnable prototype for Puducherry Police Hackathon 2026 (Problem Statement 02).

Synthetic demonstration data only. All incident locations, zone labels, patrol/CCTV overlays and reports are fictional. CrimeMap is not a real police platform, validated crime forecast or operational decision-making tool.

Quick start

Requires Python 3.11+ and a recent Node.js LTS with npm. The one-command launcher now supports Windows, Linux and macOS.

Linux/macOS (first install only)

cd backend
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m app.bootstrap_admin
cd ../frontend
npm install
cd ..
python3 start.py

The administrator bootstrap prompts for your own username/password. Skip it if you already have an account. On subsequent runs, from the repository root:

python3 start.py

• Application: http://127.0.0.1:5173
• API and interactive docs: http://127.0.0.1:8000/docs
• Health check: http://127.0.0.1:8000/health
• Stop: Ctrl+C (stops backend and frontend together)

After updates that change dependencies, run cd backend && .venv/bin/python -m pip install -r requirements.txt in the existing virtual environment. Don't delete your SQLite database or rebootstrap accounts when updating.

Windows (PowerShell, first install only)

Clone your own copy, then run these commands in PowerShell from the repository root:

git clone --branch dev/shwetha https://github.com/aeroslayys/CrimeMap.git
cd CrimeMap
cd backend
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m app.bootstrap_admin
.\.venv\Scripts\python.exe -m scripts.seed_demo
cd ..\frontend
npm install
cd ..
.\start_windows.bat

The first administrator and 100 synthetic seed records are created only on a brand-new teammate database; skip bootstrap/seed on existing local installations. Each clone has its own independent SQLite database, not your private imported records or accounts.

After first-time setup, double-click start_windows.bat in File Explorer, or run .\start_windows.bat in PowerShell. It starts both backend and frontend in one terminal, with shared logs, and Ctrl+C stops them. You can also run py -3 start.py. No PowerShell execution-policy changes, Docker, or PostgreSQL are needed.

If updating on Windows, pull the new code, then install updated dependencies inside the existing venv with cd backend; .\.venv\Scripts\python.exe -m pip install -r requirements.txt; return to the root and launch again. Do not delete backend\crimemap.db or rebootstrap accounts.

For optional PostgreSQL, security configuration, detailed role permissions, backups and test commands, see Developer setup.

Public landing page and proposed complaint tracking

The deployed app opens to a public, informational landing page describing what CrimeMap is, how it helps reviewers explore fictional incident patterns, its differentiators, and why decisions still require human review. Select Sign in for the role-protected workspaces. After login, choose About CrimeMap in the navigation to return to the introduction.

The landing page includes a proposed future idea, not an implemented feature: privacy-protected citizen complaint progress with verified case references, identity checks, authorized updates and simple status milestones. There is no real complaint intake, public case lookup, verified citizen identity system, or live police integration in this hackathon demo. Never submit real personal/case data.

Distributed fictional incidents and visible demonstration zones

The 100 canonical synthetic incidents in data/synthetic_incidents.csv and the downloadable sample now cover widely separated Puducherry reference neighborhoods. The Zones mode in Geospatial Intelligence shows four clickable colored polygons with descriptions of where each zone begins and ends. Their boundaries are illustrative, not official police jurisdictions or authoritative water/land outlines.

Existing databases are unchanged on code deployment. Seeding only inserts missing records. Use cd backend && python -m scripts.reposition_demo to preview relocating untouched original/small-block canonical DEMO pins; --apply is required for any database updates. Never reset a database or rerun a cloud initializer to relocate sample locations. Read the detailed zone map and migration guide.

What it does

CrimeMap has four workspaces, not a separate screen for every visualization:

Workspace	Capabilities
Incidents	Search, filter, paginate, create and update synthetic records. Place/drag a map marker to choose coordinates and suggest the containing fictional Demo Zone A–D. Map on a record locates and highlights it on the existing map. CSV/JSON import previews validation problems, possible duplicates and warnings before confirmation.
Geospatial Intelligence	One Leaflet/OpenStreetMap map with Markers, Zones, Heatmap, Grid Analysis and Operations modes. Fixed-grid count comparisons use equal-length, nonoverlapping periods; Operations overlays are fictional, not live GPS/CCTV feeds.
Analytics	Counts by category, status, IST date/hour and demonstration zone. Shared filters cover all matching records, not just the visible registry page. Build presentation PDF exports selectable analytics, geographic findings and saved prevention-plan summaries.
Prevention Planner	General safeguarding suggestions from descriptive fictional counts; human-reviewed action plans with status, owner and due date. Completed plans offer a before/later count review, not a causal effectiveness claim.

Administrator → User management includes account permissions and an application-level change history of selected successful incident and prevention-plan actions. It is not a tamper-proof audit system.

Access levels

Viewer: records and basic map. Analyst: analytics, spatial comparisons, prevention review and PDF. Officer: creates/imports incidents and manages prevention plans. Administrator: also deletes incidents and manages accounts/audit history. Permissions are enforced by FastAPI, not merely by hiding UI elements.

Data, imports and persistence

• Default database: backend/crimemap.db (SQLite). Successfully imported records, accounts and saved plans persist across browser refreshes, sign-outs and server restarts. Optional PostgreSQL uses a different database; switching does not transfer SQLite records.
• Bundled demo data: data/synthetic_incidents.csv contains 100 canonical fictional records with stable DEMO- IDs. To add only missing seed IDs to the current database, run cd backend && .venv/bin/python -m scripts.seed_demo. This is optional, idempotent and never runs automatically. Your total can be greater than 100 if you've imported more incidents.
• Manual import: Inside Incidents → Import incident data, choose a CSV/JSON file (up to 2 MB / 1,000 rows), inspect the read-only preview and confirm. Invalid rows block the batch; possible duplicates are skipped by default and existing records are not overwritten. Duplicate matching is a heuristic: category, UTC occurrence second and coordinates rounded to six decimal places.
• Sample CSV: Download it from the import panel, or use frontend/public/sample-data/synthetic_incidents.csv. The import also accepts an optional id column as ignored metadata; newly imported IDs are server-generated. All imported records are labeled synthetic.

Required CSV fields (timezone-aware occurred_at):

category,occurred_at,latitude,longitude,police_station,description,status
Theft,2026-10-02T12:30:00+05:30,11.9332,79.8299,Demo Zone B,SYNTHETIC TEST RECORD,reported

JSON can contain an array of incident objects, or an object with an incidents array. Valid statuses: reported, under_investigation, closed. Allowed categories are defined in backend/app/schemas.py.

Important: Zones mode and pin suggestions use fictional display polygons (not authorized police jurisdictions). Other analytics/grid zone filters use stored, editable labels. A displayed grid count or changed incident total does not imply a verified hotspot, public safety risk or successful intervention.

Project layout

CrimeMap/
├── backend/             FastAPI, SQLAlchemy, auth, tests and seed utilities
├── frontend/            React/Vite app and static sample CSV
├── data/                Canonical 100-record synthetic seed
├── docs/
│   ├── SETUP.md         Local setup, security, databases and testing
│   ├── CLOUD_DEPLOYMENT.md  Deployed Cloud Run architecture and teammate runbook
│   └── DEMO.md          Five-minute demo and manual QA checklist
├── compose.yaml         Optional local PostgreSQL
└── start.py             Start FastAPI + Vite together

Google Cloud Run deployment

The repository includes a production multistage Dockerfile for one HTTPS frontend/API URL and an explicit Cloud SQL PostgreSQL mode (no ephemeral SQLite fallback). Accounts and fictional seed data are initialized once by a restricted Cloud Run Job, not by web-server startup. For the live resource inventory, deployment walkthrough, Cloud Shell commands, teammate access and operations, read Cloud deployment and teammate handoff. Provisioning Google Cloud services is manual and may consume trial credits; nothing is deployed or billed by cloning this repository.

Appearance: projector light mode + dark mode

Light mode is the default for bright-room projection, with stronger contrast for incident tables, maps, analytics, prevention planning, admin screens and sign-in. The Light mode / Dark mode toggle is available on both the login screen and in the workspace header. Your choice persists in this browser using localStorage (key crimemap-theme); it is not an account setting in the database.

Dark mode preserves the original navy/blue CrimeMap styling. Tailwind CSS v4 is now integrated with Vite via @tailwindcss/vite, so utilities compile into the local and Cloud Run production bundle with no runtime CDN. Existing component CSS remains in place. Tailwind's global Preflight reset is deliberately excluded in frontend/src/tailwind.css to avoid breaking established styles, while frontend/src/theme.css holds the light-mode overrides. New UI code can gradually adopt Tailwind utility classes.

Cloud deployment: pushing UI changes to GitHub does not automatically redeploy the existing Cloud Run service. After CI passes, follow the deployment handoff's update procedure to build a new image and deploy a new revision. Do not rerun the database initialization job.

Testing and demo

Run cd backend && .venv/bin/python -m pytest -q for backend tests; from frontend/ run npm test and npm run build. CI also checks PostgreSQL schema/seed behavior. API route details are available in FastAPI's interactive local API docs when the server is running.

For presenting the complete Record → Map → Analyse → Prevent → Review → Present workflow, use the five-minute demo guide.

Deployment warning: This is a development-only proof of concept. Do not import actual police, victim, witness or operational data; public deployment would require authorization, verified geographic data, production security/privacy controls, proper migrations, backups and independent review.