SimhasthaSetu is an integrated crowd-safety and assistance platform built for large events (originally developed for the Kumbh/Simhastha). It combines a Flutter-based cross-platform mobile/desktop frontend, a FastAPI backend, and a machine-learning crowd-detection service to provide live crowd monitoring, emergency SOS, weather alerts, chatbot assistance, and navigation help.

This README documents the project architecture, local development setup, how to run each component, available API endpoints, debugging tips, and next steps.

• Project overview
• Architecture and components
• Quick start (local dev)
  • Prerequisites
  • Backend
  • ML service
  • Frontend (Flutter)
• API reference (important endpoints)
• Developer notes & debugging
• Testing
• Contributing
• License

SimhasthaSetu provides:

• Live crowd heatmap and per-location crowd status (powered by an ML video-analysis service).
• Emergency SOS: users can trigger SOS events which are routed to backend responders and displayed in-app.
• Weather hazard alerts with a background updater.
• Chatbot/MCP integration for natural language help (intent routing to SOS, crowd check, navigation, etc.).
• Utilities for helplines, navigation, and crowd monitoring tools.

The project is organized as a monorepo with frontend (Flutter app), backend (FastAPI), and ml-service (Python ML service).

• Frontend: lib/ (Flutter app) — UI screens, SOS flow, heatmap, chat UI, and platform-aware API base URL handling.
• Backend: backend/ (FastAPI) — routes for /sos, /chat, /weather-alerts, /crowd/*, and utility tools in backend/tools/.
• ML service: ml-service/ (Python) — a FastAPI wrapper around a YOLO/ID-tracking-based crowd-analysis pipeline. Exposes /analyze.
• Build artifacts: build/, platform folders (android/, ios/, windows/, etc.).

There are convenience tools under backend/tools/: sos_tool.py, crowd_tool.py, chatbot_intent.py, weather_alerts.py, navigation_tool.py, etc.

This guide assumes you are on Windows (the repository contains config and notes oriented to Windows development). Adjust commands if using macOS/Linux.

Prerequisites

• Flutter SDK (stable) and flutter on PATH
• Python 3.11+ (used for backend) — prefer virtualenv/venv
• Python 3.9 (or compatible) for ML service if you run ML with the provided GPU/torch environment (see ml-service/ README)
• pip, virtualenv, and venv utilities
• (Optional) GPU drivers and PyTorch with CUDA if you want GPU acceleration for ML

Backend (FastAPI)

1. Create and activate a Python venv and install requirements for backend:

cd I:\Confidential\Kumbhu\backend
python -m venv .venv
.\.venv\Scripts\Activate
pip install -r requirements.txt

2. Start the backend (development):

# from project root
uvicorn backend.app.main:app --reload --port 8000

3. Health checks:

• http://127.0.0.1:8000/ -> backend running
• http://127.0.0.1:8000/weather-alerts -> weather cache
• http://127.0.0.1:8000/sos/debug -> (connectivity test)

ML service (lightweight wrapper)

The ML service contains a heavier YOLO/tracking pipeline. There is a small FastAPI wrapper in ml-service that exposes /analyze for a single video path request (used by the backend crowd_tool).

1. See ml-service/README.md for environment and GPU instructions (this service may require a separate environment). The repo includes crowd_detection.json sample output.

2. To run the ML HTTP API wrapper (if you want to call it directly):

cd I:\Confidential\Kumbhu\ml-service
# ensure correct python and deps (may require a specific env)
python -m uvicorn main:app --reload --port 8001

Frontend (Flutter)

1. Ensure flutter is installed and working; run flutter doctor.
2. From project root, run on Windows (desktop) or Android device/emulator:

# Windows desktop
flutter run -d windows

# Android emulator (ensure API_BASE is set to http://10.0.2.2:8000 for emulator)
flutter run -d emulator-5554 --dart-define=SOS_API_BASE=http://10.0.2.2:8000

Notes:

• Desktop builds default API base is http://127.0.0.1:8000.
• If running backend in a container or remote host, set --dart-define or SOS_API_BASE appropriately.

• GET / -> health
• GET /weather/hazard, GET /weather-alerts -> latest weather and hazard alerts
• POST /chat -> chatbot (body: {"user_id": "...", "query": "..."})
• GET /sos/debug -> quick connectivity check
• POST /sos/trigger -> trigger SOS (body JSON {"userId":..., "lat":..., "lon":...})
• GET /sos/active -> list active SOS events
• POST /sos/resolve/{sos_id} -> resolve event
• GET /crowd/omkaleshwar -> backend proxy to ML service for Omkaleshwar summary

ML service (ml-service)

• POST /analyze -> analyze a single video (body: {"video_path": "...", "ghat_name": "..."})

• SOS troubleshooting:

  • The app logs requests with debugPrint('SOS: POST ...') and logs backend responses; check the Flutter debug console and the backend uvicorn terminal for matching prints.
  • There is a /sos/debug endpoint for quick network checks.
  • The client uses a 10s timeout for SOS POSTs; if your ML/backend is slow, increase it or implement background job flow.

• Chatbot:

  • backend/tools/chatbot_intent.py uses sentence-transformers if installed; otherwise it falls back to keyword matching.
  • Greetings are handled early with a regex.

• ML service:

  • The ML code expects local video files for analysis; if you see "Video not found" errors, update ml-service video paths or provide your own.

• CORS is enabled for development in backend/app/main.py.

• Unit tests: add pytest tests in backend/tests and ml-service/tests for API wrappers and tools.
• Manual tests:
  • Trigger SOS from app -> verify backend log and /sos/active listing.
  • Call /crowd/omkaleshwar and confirm the backend proxies results from the ML service.
  • Use flutter run -d windows and monitor Flutter console for debugPrint messages.

• Follow the repo structure (frontend/backend/ml-service). Add unit tests for new behavior.
• Create feature branches against main and open PRs with descriptive titles and linked issues.

This project does not include a license file. Add a license (e.g., MIT) in LICENSE if you plan to open-source this project.

Primary maintainer: repo owner (check git remote for contact). For urgent live-event issues, use the in-app SOS flow for a hands-on verification.

If you'd like, I can also:

• Add a short CONTRIBUTING.md with tests and linters.
• Add a README inside ml-service/ with ML environment and GPU setup steps.
• Generate simple unit tests for backend/tools/chatbot_intent.py to verify greetings and intent routing.

A new Flutter project.

This project is a starting point for a Flutter application.

A few resources to get you started if this is your first Flutter project:

• Lab: Write your first Flutter app
• Cookbook: Useful Flutter samples

For help getting started with Flutter development, view the online documentation, which offers tutorials, samples, guidance on mobile development, and a full API reference.