Marga

ASTraM-compatible parking intelligence module built for Flipkart Gridlock 2.0 Round 2.

Marga helps a Traffic Management Center officer decide where to send limited patrol teams next under fixed capacity. It uses official parking-violation records to rank approximately 200m enforcement grids for the next two-hour forecast window, then closes the loop through assignment, officer update, and evidence replay.

What the prototype does

• ranks the next patrol shift under fixed capacity
• shows a 200m grid-based command surface instead of fake road geometry
• explains why a zone is prioritized
• lets the TMC assign teams and log overrides
• lets officers accept, reach, resolve, and close assignments
• proves allocation value on an untouched historical holdout

Core claim

On the untouched 28-day historical holdout, Marga's Top-10 recommendations captured 52.2% more future recorded obstruction burden than deploying patrols using historical parking density alone.

Supporting evidence:

• Marga Top-10 capture: 19.2%
• Historical-density Top-10 capture: 12.6%
• Relative lift over baseline: +52.2%
• Capacity: same Top-10 patrol zones
• Evaluation style: retrospective, official organizer-provided BTP records

Claim boundary

Use this wording consistently:

Marga does not claim measured congestion reduction. It shows that, under the same Top-10 patrol capacity, the system identifies zones that captured more future recorded obstruction burden than a historical-density baseline on the untouched holdout.

Do not claim:

• reduced congestion by X%
• recovered road capacity by X%
• reduced travel time by X%
• reduced queue length by X%

Stack

• Frontend: Next.js 16, TypeScript, Tailwind CSS, shadcn/ui
• Backend: FastAPI
• ML artifact: Kaggle-trained LightGBM deployment model
• State: seeded in-memory backend store plus browser fallback state
• Map: Leaflet/OpenStreetMap operational surface with real 200m grid overlays
• Assistant: optional read-only Groq, Gemini, or OpenAI provider with deterministic fallback

Product routes

• / or /command-center: TMC command center
• /officer: officer workflow
• /evidence: holdout proof, replay, methodology, limitations, provenance
• /future-integrations: explicitly out-of-MVP future scope
• /alerts: redirect to /future-integrations

MVP feature set

• live deployment forecast mode
• holdout replay mode in the same command center
• adjustable patrol capacity K
• focused enforcement vs coverage discovery toggle
• ranked dispatch queue
• explainable selected-zone panel
• assignment state machine with human override logging
• officer accept, en-route, on-scene, outcome, unable-to-reach, and close workflow
• evidence center with frozen holdout proof and provenance
• read-only operations assistant with deterministic fallback
• manual reset for repeatable judging

Repository layout

This Git repository is rooted at client/.

client/
  app/                     Next.js app routes
  backend/                 FastAPI backend and tests
  components/              command center, officer, evidence, and shell UI
  data/                    compact packaged forecast/replay/fallback artifacts
  docs/                    PRD, deployment notes, Theme 1 research, ML pipeline summary
  ml/                      Kaggle training and artifact export pipeline
  evidence/                frozen metrics and proof tables
  lib/                     frontend constants, helpers, assistant grounding
  models/                  deployment model and schema artifacts

Local setup

1. Prerequisites

• Node.js 20+
• pnpm
• Python 3.12+

2. Frontend environment

Create client/.env.local.

NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000
NEXT_PUBLIC_MAP_PROVIDER=leaflet
NEXT_PUBLIC_POLL_INTERVAL_MS=4000
NEXT_PUBLIC_DEFAULT_TEAM_CAPACITY=10
NEXT_PUBLIC_ENABLE_MAP_FALLBACK=true
NEXT_PUBLIC_ENABLE_INFERENCE_FALLBACK=true

3. Backend environment

Create client/backend/.env.

MARGA_ENV=dev
MARGA_MODEL_PATH=../models/hotspot_count_model.txt
MARGA_FEATURE_SCHEMA_PATH=../models/feature_schema.json
MARGA_FORECAST_SNAPSHOT_PATH=../data/latest_inference_snapshot.parquet
MARGA_REPLAY_SNAPSHOT_PATH=../data/holdout_replay_snapshot.json
MARGA_FALLBACK_PATH=../data/fallback_ranked_zones.json
MARGA_MODEL_VERSION=Marga-LGBM-v1
MARGA_SCHEMA_VERSION=1
MARGA_DEFAULT_K=10
MARGA_MAX_K=20
MARGA_CORS_ORIGINS=http://localhost:3000

# Assistant provider
LLM_PROVIDER=disabled
OPENAI_API_KEY=
OPENAI_MODEL=
GROQ_API_KEY=
GROQ_MODEL=
GEMINI_API_KEY=
GEMINI_MODEL=

# Telegram bot integration
TELEGRAM_BOT_TOKEN=
TELEGRAM_WEBHOOK_SECRET=

Supported LLM_PROVIDER values:

• disabled
• openai
• groq
• gemini

If disabled or unavailable, the assistant falls back to deterministic grounded responses.

Run locally

Frontend

From the repo root client/:

pnpm install
pnpm dev

Frontend runs at:

http://localhost:3000

Backend

From client/:

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Backend runs at:

http://127.0.0.1:8000

Health endpoint:

http://127.0.0.1:8000/health

Telegram bot setup

The Telegram integration is designed for reliable MVP officer updates:

• TMC assigns from the dashboard
• assignment card is pushed to the registered team chat
• officer updates status from Telegram inline buttons
• backend updates assignment state
• dashboard reflects the new state through polling

1. Create the bot

• create a bot with @BotFather
• copy the bot token into TELEGRAM_BOT_TOKEN
• generate any private random string for TELEGRAM_WEBHOOK_SECRET

2. Start backend locally

Run the FastAPI backend first so the webhook endpoint exists:

cd backend
.venv\Scripts\activate
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

3. Expose the backend publicly

Telegram requires a public HTTPS webhook URL. During local development, use a tunnel such as ngrok.

Example:

ngrok http 8000

Assume ngrok gives:

https://abc123.ngrok-free.app

4. Register the webhook

Call the backend setup route with the public webhook URL:

POST http://127.0.0.1:8000/integrations/telegram/setup?url=https://abc123.ngrok-free.app/integrations/telegram/webhook

You can open this from Swagger or call it with PowerShell. Keep it on one line:

Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8000/integrations/telegram/setup?url=https://abc123.ngrok-free.app/integrations/telegram/webhook"

If your backend is deployed on Render, replace 127.0.0.1:8000 with your Render backend URL:

Invoke-RestMethod -Method Post -Uri "https://marga-yz4u.onrender.com/integrations/telegram/setup?url=https://abc123.ngrok-free.app/integrations/telegram/webhook"

5. Register officer chat

From Telegram, send one of:

/start TEAM-01

or

/register TEAM-01

This binds the Telegram chat to that patrol team. The mapping persists across backend restarts in the current MVP.

6. Test the workflow

• create an assignment for the same team from the command center
• confirm the assignment card appears in Telegram
• click:
  • Accept
  • En Route
  • On Scene
  • an outcome button
  • Close Assignment
• confirm the dashboard updates status and timestamp

MVP boundary

• manual Telegram updates are the intended prototype workflow
• no live GPS or geofencing is required for this version
• webhook source is protected by TELEGRAM_WEBHOOK_SECRET
• stale/invalid buttons are rejected by the backend state machine

Verification

From client/:

pnpm build
pnpm exec tsc --noEmit
pnpm run lint

From client/ for backend tests:

.\backend\.venv\Scripts\python.exe -m pytest .\backend\tests

Current clean-check expectation:

• production build passes
• TypeScript passes
• lint passes
• backend tests pass

Deployment

Recommended deployment shape:

• FastAPI backend on Render
• Next.js frontend on Render or Vercel

The repository already includes:

• render.yaml
• docs/RENDER_DEPLOYMENT.md

Important deployment note:

• NEXT_PUBLIC_API_BASE_URL is a build-time frontend variable
• deploy the backend first or redeploy the frontend after the backend URL is known

Competition-fit summary

Why this prototype is not a generic dashboard:

• it answers a concrete TMC decision: where to send limited patrol teams next
• it compares against a naive historical-density baseline
• it preserves human override
• it closes the loop from recommendation to field outcome
• it keeps evidence and claim boundaries explicit

Mind map

Reference planning mind map used to shape the final narrative:

Useful docs

• docs/PRD.md
• docs/RENDER_DEPLOYMENT.md
• docs/THEME1_RESEARCH.md
• docs/ML_PIPELINE.md
• ml/kaggle_theme1_pipeline.py

Extra: AI Overview

Optional AI-generated overview of the Marga concept and forecasting approach:

• Watch here

Disclaimer

Prototype for Flipkart Gridlock 2.0. Designed as an ASTraM-compatible parking intelligence module. Not an official BTP deployment or endorsement.