🚀 RozgarRouter — Pan-India Decision Intelligence for Job Seekers

Multi-agent AI platform that balances Job Salary, Housing Rent, and Commute Costs to calculate "True Income" across India.

Built for the AI Hackathon — targeting "Connecting talent to local jobs" and "Traffic/Transit" themes.

---

🎯 What's Built (MVP Bridge — Ready to Fork)

The scaffold + bridge is complete. Both servers run, with dual WebSockets handling the conversational UI and the real-time agent swarm. Works without API keys (mock fallbacks) and with Gemini API (dynamic extraction).

✅ Working Now

Component	Status	Details
FastAPI Backend	✅ Running	localhost:8000 with WebSockets /ws/intake & /ws/pipeline
Next.js Frontend	✅ Running	localhost:3000 with "Minimalist Power" glass dashboard
Conversational Intake	✅ Working	Gemini dynamically builds identity bubble from chat
5-Agent LangGraph	✅ Working	Scout → Housing → Commuter → Auditor → Closer
Mock Services	✅ Fallback	Runs perfectly without Google Maps or Twilio keys
True Income Math	✅ Working	Net Income = Salary - Rent - Commute Cost
Adversarial Auditor	✅ VETO Logic	Hard limits on Commute Time, Quality of Life, and Hourly Rate

---

👥 Team Work Distribution (Bridge Strategy)

Core Idea: The backend architecture is locked. Everyone can now work in parallel to replace mocks with real APIs and polish the UI.

Person 1 — Backend AI Lead (Agent Logic)

Focus: Resolving Backend Weaknesses (Real APIs)

• backend/app/agents/housing.py — Upgrade from Gemini hallucination to a real Real Estate API (NoBroker/MagicBricks) or structured data if time permits.
• backend/app/services/gemini_service.py — Plug in GEMINI_API_KEY to test real structured output extraction for the Chat Intake. (✅ Completed - Using gemini-2.5-flash with robust Pydantic enum validation for transit modes).
• backend/app/data/jobs.json — (Stretch) Replace static JSON with a Vector Database for semantic search.

Person 2 — Frontend Visuals Lead

Focus: Cinematic animations + Map integration

• frontend/src/components/dashboard/MapOverlay.tsx — Replace SVG with real Google Maps API.
• Draw route polylines from the commuter agent data.
• Drop markers for Job Location and the Housing Agent's recommended residential area.
• Polish the red VETO animation (screen shake, glow).

Person 3 — Frontend UI/UX Lead

Focus: Conversational Chat Intake + Results

• ✅ COMPLETED: InteractionZone.tsx and IntelligenceBubble.tsx hooked up to ws://localhost:8000/ws/intake.
• ✅ COMPLETED: "Minimalist Power" UI implemented. Action panels removed for clean chat layout, dynamic progressive profile bubble added at the top.
• Polish the Job Cards to clearly show True Income breakdown: Salary - Rent - Commute.

Person 4 — Data & Tools Lead

Focus: Real API integrations + Demo story

• backend/app/services/maps_service.py — Plug in Google Maps API for real traffic-adjusted commute times.
• backend/app/services/twilio_service.py — Plug in Twilio WhatsApp API.
• Curate jobs.json to tell a Pan-India story: e.g., ₹80k in Mumbai (high rent) vs ₹80k in Indore (low rent), showing how the Swarm calculates true viability.

---

🧠 Architecture

Dual WebSocket Flow

1. Intake Phase (/ws/intake): User chats with AI. Backend extracts parameters (Role, Salary, City, Phone) dynamically.
2. Execution Phase (/ws/pipeline): Frontend sends extracted profile to launch the swarm.

The 5-Agent Swarm (LangGraph)

Agent	Role	API / Math
🔍 Scout	Scans jobs, scores relevance	Gemini / Keyword
🏠 Housing	Recommends PG/1BHK & estimates rent	Gemini Real Estate
🚌 Commuter	Calculates commute time + transit cost	Google Maps
🛡️ Auditor	Adversarial validation. VETOs bad jobs	Salary - Rent - Commute
🎯 Closer	Auto-fills app + WhatsApp alert	Twilio

Auditor VETO Rules (Hard limits)

• ❌ Commute > 60 minutes one-way
• ❌ Quality of Life score < 6.0/10
• ❌ Effective hourly rate < ₹50/hr

---

⚡ Quick Start

Backend

cd backend
python -m venv .venv
.venv\Scripts\activate      # Windows
# source .venv/bin/activate # Mac/Linux

pip install -r requirements.txt
cp .env.example .env        # Add API keys here
uvicorn app.main:app --reload --port 8000

Frontend

cd frontend
npm install
npm run dev

Open http://localhost:3000 → Chat with the AI agent to define your target role, salary, and location → Watch the Swarm extract opportunities! 🚀

Test Pipeline (CLI)

cd backend
python test_pipeline.py      # Happy path
python test_rain.py          # Rain mode — all vetoed

---

📁 Project Structure

├── frontend/                  # Next.js 15 + Tailwind v4 + Zustand
│   └── src/
│       ├── app/               # Pages, layout, CSS design tokens
│       ├── components/
│       │   ├── dashboard/     # UserInputPanel, AgentConsole, MapOverlay,
│       │   │                  # LiveFillPanel, VetoOverlay
│       │   └── shared/        # Header
│       ├── hooks/             # useWebSocket.ts
│       ├── lib/               # types.ts, constants.ts, utils.ts
│       └── store/             # agentStore.ts (Zustand)
│
├── backend/                   # FastAPI + WebSocket + Agents
│   ├── .venv/                 # Python virtual environment
│   ├── app/
│   │   ├── agents/            # scout.py, commuter.py, auditor.py, closer.py
│   │   ├── models/            # schemas.py (Pydantic V2)
│   │   ├── services/          # gemini_service.py, maps_service.py, twilio_service.py
│   │   ├── data/              # jobs.json (20 Bengaluru listings)
│   │   ├── orchestrator.py    # Supervisor pipeline
│   │   ├── main.py            # FastAPI app + WS endpoint
│   │   └── config.py          # Pydantic Settings
│   ├── test_pipeline.py       # E2E test (happy path)
│   ├── test_rain.py           # E2E test (rain mode)
│   └── requirements.txt
│
└── README.md

---

🏆 Hackathon Judging Alignment

Criteria	How We Hit It
Takes Action	Auto-fills applications, sends real WhatsApp alerts with Twilio
Beyond Basics	4 AI agents collaborating via WebSocket, adversarial VETO logic
Real Tools	Google Maps API (real routes), Twilio (real messages), Gemini (real AI)
Community Impact	Helps Bengaluru gig workers avoid unsustainable commutes

---

Built with ❤️ for Bengaluru's workforce.