InfraFlow: Cognitive Urban Architect

Transform 6 months of civil engineering into 6 minutes of AI-powered diagnosis

🎯 Overview

InfraFlow is a forensic infrastructure agent that moves urban planning from capacity-based expansion to efficiency-based geometric optimization. Instead of widening roads—which induces demand—InfraFlow diagnoses congestion root causes and auto-generates Uninterrupted Flow Interchanges (UFI).

✨ Features

• 🔍 Forensic Discovery: 24-hour "Time-Machine" traffic probing with Google Routes API
• 🧠 Cognitive Processing: Gemini Thinking Mode for intelligent design selection
• 🏗️ Generative Design: Auto-generated DDI, Roundabout, and optimized signal geometries
• 🎮 Digital Twin: SUMO micro-simulation for validation
• 📊 Impact Visualization: Before/after comparison with LOS, travel time, and CO₂ metrics

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• Node.js 18+ (for local development)
• Python 3.11+ (for local development)

Using Docker (Recommended)

# Clone the repository
git clone https://github.com/your-org/infraflow.git
cd infraflow

# Copy environment template
cp backend/.env.example backend/.env
# Edit .env with your API keys

# Start all services
docker-compose up -d

# Access the application
# Frontend: http://localhost:3000
# API Docs: http://localhost:8000/docs

Local Development

# Backend
cd backend
python -m venv venv
venv\Scripts\activate  # Windows
pip install -r requirements.txt
uvicorn main:app --reload

# Frontend (new terminal)
cd frontend
npm install
npm run dev

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      FRONTEND (React + Deck.gl)             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ MapView  │  │Inspector │  │ Thinking │  │ Impact   │   │
│  │(Pin Drop)│  │ Panel    │  │ Trace    │  │ Slider   │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      BACKEND (FastAPI)                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │/v1/forensics │  │/v1/architect │  │/v1/simulation│      │
│  │ • probe      │  │ • generate   │  │ • run        │      │
│  │ • status     │  │ • design     │  │ • results    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                              │
            ┌─────────────────┼─────────────────┐
            ▼                 ▼                 ▼
    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
    │ PostgreSQL   │  │    Redis     │  │    SUMO      │
    │ + PostGIS    │  │   (Cache)    │  │ (Simulation) │
    └──────────────┘  └──────────────┘  └──────────────┘

📡 API Endpoints

Method	Endpoint	Description
POST	/v1/forensics/probe	Initiate 24-hour traffic probe
GET	/v1/forensics/probe/{id}/status	Check probe status
GET	/v1/forensics/probe/{id}/friction-curve	Get friction analysis
POST	/v1/architect/generate	Generate AI-powered design
GET	/v1/architect/design/{id}	Get design result
GET	/v1/architect/thinking-trace/{id}	Get Gemini reasoning
POST	/v1/simulation/run	Run SUMO simulation
GET	/v1/simulation/sumo-results/{id}	Get simulation results

🔧 Configuration

Copy .env.example to .env and configure:

# Required
GOOGLE_MAPS_API_KEY=your_key_here
GEMINI_API_KEY=your_key_here

# Database
DATABASE_URL=postgresql+asyncpg://infraflow:infraflow@localhost:5432/infraflow

# Optional
SUMO_HOME=/path/to/sumo
DEBUG=true

📊 Design Types

Design	Conflict Points	Best For
Roundabout	8 (vs 32)	Arterial junctions, balanced flow
DDI	18 (vs 32)	Heavy left turns, highway interchanges
Signal Optimized	24 (vs 32)	Constrained spaces, moderate volumes

🧪 Testing

# Backend tests
cd backend
pytest tests/ -v

# Frontend tests
cd frontend
npm test

📜 License

MIT License - see LICENSE for details.

---

Made with 🧠 by the InfraFlow Team