How lakshya1729git/iit_kgp_internship works
1. System shape
- This is a Python research prototype with a FastAPI backend and a single-page Leaflet map frontend served from app/static/index.html.
- The architecture is centered on one flow: get routes immediately, then enrich them asynchronously with disruption intelligence.
2. User-facing boundary
- The browser UI is the thin presentation layer: source/destination selection, route display, and color-coded risk overlays.
- Static assets live under app/static/, with the frontend depending on the API for route computation and disruption results.
3. API and orchestration layer
- app/api.py is the main server entry point for the web app; app/main.py exists as a CLI/debug pipeline.
- This layer coordinates the major subsystems rather than doing heavy computation itself: routing, ingestion, LLM extraction, scoring, and persistence.
4. Configuration and environment
- app/config.py centralizes runtime settings from .env, including LLM keys and external API credentials.
- The repo is designed to work with at least one LLM provider, plus optional live data providers such as TomTom and NewsAPI.
5. Route computation subsystem
- app/routing/route_engine.py is the core pathfinding component, responsible for generating multiple candidate routes and exporting them in map-friendly form.
- Supporting modules handle geocoding, map matching, timetable-aware multimodal routing, and cost calculation.
- This is the “fast path” in the system: it produces usable routes within seconds before disruption analysis finishes.
6. Live and external data ingestion
- app/ingestion/ contains connectors for the external signal sources the system watches:
- Google News RSS
- NewsAPI
- TomTom live traffic incidents
- optional weather feeds
- web scraping for additional sources
- These fetchers are the main ingress boundary from the outside world into the analysis pipeline.
7. LLM-based disruption extraction
- app/llm/ turns noisy text from news and advisories into structured traffic events.
- extractor.py likely orchestrates the LLM chain; schema.py defines the structured event shape; filter.py and location_resolver.py clean, deduplicate, and normalize results.
- prompts.py shows the system is tuned for Kolkata-specific traffic/event interpretation and retry behavior.
8. Event scoring and risk model
- app/scoring/ converts extracted disruptions into route impact.
- The key idea is a weighted signal model: event severity and confidence feed congestion/risk scores, while impact_duration.py estimates how long an event matters.
- confidence.py refines the LLM certainty into a more usable confidence measure for downstream ranking.
9. Fusion and planned probabilistic layers
- app/fusion/bayesian_fusion.py is a placeholder for a future Bayesian data-fusion layer.
- The README makes clear this repo currently implements Layer 1 only; Layer 2 and Layer 3 are planned extensions, not active parts of the runtime path.
10. Persistence boundary
- app/database/models.py defines SQLAlchemy models backed by a local traffic_events.db-style store.
- This persistence layer is used to retain extracted events and support repeated analysis, rather than relying purely on in-memory processing.
11. Weather-aware augmentation
- app/weather/ adds route-adjacent weather risk logic.
- Weather is not the core planner input, but it is an auxiliary signal that can change event interpretation or route risk.
12. Utility and shared processing
- app/utils/helpers.py contains shared text-cleaning, deduplication, and timestamp handling used across ingestion and extraction.
- This module is a glue layer that keeps normalization consistent before data reaches scoring or persistence.
13. End-to-end data flow
- Typical flow is: user request → route engine returns alternatives → background ingestion pulls live/news data → LLM extracts structured events → filters/location resolver normalize them → scoring assigns route risk → frontend updates map with risk colors and markers.
- The architecture is intentionally split into a low-latency route path and a slower analytical enrichment path.
14. Operational characteristics
- The system is local-first for development, with external dependencies only where needed for routing, news, incident, and LLM access.
- The repo also includes docs/project-handoff.md, which acts as the detailed engineering handoff for future layers and extensions.
Main entry points: api.py API Server · extractor.py LLM Extractor · congestion_score.py Risk Scoring · filter.py LLM Normalizer
Components 19
Presentation
Browser-facing map UI and static assets
- Map UI · Single-page map interface for route selection and risk overlays
app/static/index.html - Client Logic · Browser-side route display and map updates
app/static/scripts.js
Backend
API, orchestration, routing, persistence, and shared runtime settings
- API Server · Main web entrypoint coordinating route, ingestion, scoring, and persistence flows
app/api.py - CLI Pipeline · Command-line and debugging entrypoint for offline or manual runs
app/main.py - Runtime Config · Centralized environment and credential configuration
app/config.py - Route Engine · Generates candidate routes and map-friendly outputs quickly
app/routing/route_engine.py - Routing Support · Geocoding, map matching, multimodal transit, and route cost helpers
app/routing/geocoder.py - Event Store · Persistent storage for extracted traffic events and analysis state
app/database/models.py
Signals
External data ingestion and normalization of disruption evidence
- RSS Feed · Google News RSS connector for live disruption signals
app/ingestion/rss_fetcher.py - NewsAPI · External news connector for disruption coverage
app/ingestion/news_fetcher.py - TomTom Live · Live traffic incident connector
app/ingestion/tomtom_fetcher.py - Weather Feed · Optional weather signal ingestion
app/ingestion/weather_fetcher.py - Web Scraper · Fallback connector for additional disruption sources
app/ingestion/web_scraper.py
Intelligence
LLM extraction, scoring, and experimental fusion/model layers
- LLM Extractor · Turns noisy text into structured traffic events
app/llm/extractor.py - LLM Normalizer · Parsing, filtering, schema shaping, and location resolution
app/llm/filter.py - Risk Scoring · Computes confidence, duration, and congestion impact
app/scoring/congestion_score.py - Weather Risk · Adds weather-aware route risk adjustment
app/weather/weather_risk.py - Fusion Layer · Placeholder for future Bayesian data fusion
app/fusion/bayesian_fusion.py - HGNN · Graph-based experimental learning stack for future enrichment
app/hgnn/model.py
Connections 21
- Map UI → API Server: route request · User interactions submit route queries to the backend
- Client Logic → API Server: api calls · Client script fetches routes and updated risk data
- API Server → Runtime Config: loads · Server reads runtime settings and credentials
- API Server → Route Engine: compute routes · Returns fast route alternatives immediately
- API Server → Event Store: store events · Persists extracted disruptions and analysis state
- API Server → LLM Extractor: enrich async · Triggers disruption extraction after route response
- CLI Pipeline → Route Engine: offline run · CLI pipeline can exercise routing directly
- Route Engine → Routing Support: uses · Route engine depends on geocoding and multimodal helpers
- RSS Feed → LLM Extractor: news text · RSS items feed the LLM extraction pipeline
- NewsAPI → LLM Extractor: articles · NewsAPI content is normalized into structured events
- TomTom Live → LLM Normalizer: incidents · Traffic incidents are cleaned and normalized before scoring
- Weather Feed → Weather Risk: weather data · Weather signals inform route-adjacent risk logic
- Web Scraper → LLM Extractor: scraped text · Scraped source material enters extraction and filtering
- LLM Extractor → LLM Normalizer: structured events · LLM output is parsed, filtered, and location-resolved
- LLM Normalizer → Event Store: normalized events · Clean event records are written to persistence
- LLM Normalizer → Risk Scoring: event inputs · Normalized disruptions feed route impact scoring
- Risk Scoring → Route Engine: risk overlay · Scored disruptions influence route ranking and map coloring
- Weather Risk → Risk Scoring: context signal · Weather can modify final risk assessment
- Fusion Layer → Risk Scoring: future fusion · Planned probabilistic layer may refine scoring later
- HGNN → Risk Scoring: future model · Experimental graph model may contribute downstream risk signals
- API Server → Client Logic: serve assets · Backend serves the static browser application