chandrakantamandal/crowdshield

Purpose and System Shape

CrowdShield is a hackathon MVP for predictive venue crowd safety: telemetry is simulated or eventually camera-derived, scored for risk, persisted, and presented to operator and citizen clients. It is a multi-runtime repository rather than a single application: Python API, React simulation, React web console, and Expo mobile app.

Telemetry Source and Simulation

The digital-twin simulator is the primary current telemetry producer. Its crowd engine generates zone-level movement and density state, its risk view supports visualization, and telemetry synchronization posts five zones to the backend when enabled.

• Simulation/src/engine/CrowdEngine.js

• Simulation/src/engine/TelemetrySync.js

• Simulation/src/App.jsx

The separate computer-vision prototype/planned ingestion source contains detection, tracking, and metrics scripts, but is not shown as wired into the API:

• Ai/detect.py

• Ai/tracker.py

• Ai/metrics.py

FastAPI Ingestion and Live State

The backend entry point is FastAPI in Server/main.py, with crowd and risk routers. POST /api/crowd/metrics validates a Metrics payload, updates process-local latest metrics, persists where Supabase is configured, and makes current data available to polling consumers. The in-memory store enables degraded operation without database credentials but is process-local and non-durable.

• Server/main.py

• Server/routers/crowd.py

• Server/shared_data.py

• Server/models.py

Risk and Operational Decisioning

Risk calculation is deterministic and explainable: density, speed, surge, bottleneck, and flow conflict produce a 0–100 score, level, and reasons. Recommendations are gated by the resulting SAFE/WARNING/HIGH/CRITICAL level. Risk endpoints expose calculation, event retrieval, and recommendation generation.

• Server/services/risk_engine.py

• Server/services/recommendation_engine.py

• Server/routers/risk.py

Persistence, Identity, and Security Boundary

Supabase provides Postgres persistence, authentication, profiles/roles, and RLS for both clients. Server persistence is isolated in the database adapter; it can boot without Supabase but loses durable history/events. SQL migrations define the core domain tables: profiles, venues, crowd data, risk events, incidents, and alerts.

• Server/db.py

• App/db/migrations/0001_db_init.sql

• App/db/migrations/0002_backend_persistence.sql

A known schema boundary remains: flow_conflict reaches the engine but is not persisted by the backend’s crowd-data insert.

Operator Web Console

The Vite React admin app enters through Web/src/main.jsx and route composition. Protected routes/auth use Supabase, while live operational views poll the FastAPI API for telemetry and risk events. Dashboard pages compose map, alert, camera, and telemetry components; they should remain consumers rather than owners of risk logic.

• Web/src/main.jsx

• Web/src/router/AppRoutes.jsx

• Web/src/lib/useLiveData.js

• Web/src/features/admin/pages/Dashboard.jsx

Citizen Mobile App

The Expo Router app starts at the root layout/index and separates auth from tabbed citizen experiences. It uses Supabase for auth/domain data and the backend API for live risk-related data; notification support is centralized in the risk-notification provider and utilities.

• App/app/_layout.tsx

• App/app/(tabs)/_layout.tsx

• App/components/RiskNotificationProvider.tsx

• App/lib/api.ts

Runtime and Control Flow

Run the Python service on port 8000, simulation on 3000, web console on 5173, and Expo separately. Primary flow is: simulator tick → backend metrics ingestion → memory plus Supabase persistence → risk/event creation → web polling and mobile alert consumption. External boundaries are Supabase URL/anon-key configuration, Expo notification services, and planned YOLO/OpenCV camera sources. Current live delivery is polling rather than WebSocket/SSE.