# lakshya1729git/iit_kgp_internship architecture

> Architecture diagram of the GitHub repository lakshya1729git/iit_kgp_internship, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lakshya1729git/iit_kgp_internship
- Repository: https://github.com/lakshya1729git/iit_kgp_internship

## Overview

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: [`app/api.py`](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/api.py) (API Server), [`app/llm/extractor.py`](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/llm/extractor.py) (LLM Extractor), [`app/scoring/congestion_score.py`](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/scoring/congestion_score.py) (Risk Scoring), [`app/llm/filter.py`](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/llm/filter.py) (LLM Normalizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_ui["Map UI<br/>leaflet spa<br/>[index.html]"]
  node_ui_js["Client Logic<br/>frontend script<br/>[scripts.js]"]
end

subgraph group_backend["Backend"]
  node_api["API Server<br/>fastapi entrypoint<br/>[api.py]"]
  node_main["CLI Pipeline<br/>debug runner<br/>[main.py]"]
  node_config["Runtime Config<br/>env settings<br/>[config.py]"]
  node_route_engine["Route Engine<br/>routing core<br/>[route_engine.py]"]
  node_routing_support["Routing Support<br/>geo routing<br/>[geocoder.py]"]
  node_db_models[("Event Store<br/>sqlalchemy models<br/>[models.py]")]
end

subgraph group_signals["Signals"]
  node_rss["RSS Feed<br/>news ingestion<br/>[rss_fetcher.py]"]
  node_newsapi["NewsAPI<br/>news ingestion<br/>[news_fetcher.py]"]
  node_tomtom["TomTom Live<br/>traffic ingestion<br/>[tomtom_fetcher.py]"]
  node_weather_ingest["Weather Feed<br/>weather ingestion<br/>[weather_fetcher.py]"]
  node_scraper["Web Scraper<br/>source scraping<br/>[web_scraper.py]"]
end

subgraph group_intelligence["Intelligence"]
  node_extractor["LLM Extractor<br/>llm orchestration<br/>[extractor.py]"]
  node_llm_support["LLM Normalizer<br/>llm cleanup<br/>[filter.py]"]
  node_scores["Risk Scoring<br/>impact model"]
  node_weather_risk["Weather Risk<br/>aux signal<br/>[weather_risk.py]"]
  node_bayes{{"Fusion Layer<br/>planned fusion<br/>[bayesian_fusion.py]"}}
  node_hgnn{{"HGNN<br/>experimental model<br/>[model.py]"}}
end

node_ui -->|"route request"| node_api
node_ui_js -->|"api calls"| node_api
node_api -->|"loads"| node_config
node_api -->|"compute routes"| node_route_engine
node_api -->|"store events"| node_db_models
node_api -.->|"enrich async"| node_extractor
node_main -->|"offline run"| node_route_engine
node_route_engine -->|"uses"| node_routing_support
node_rss -->|"news text"| node_extractor
node_newsapi -->|"articles"| node_extractor
node_tomtom -->|"incidents"| node_llm_support
node_weather_ingest -->|"weather data"| node_weather_risk
node_scraper -->|"scraped text"| node_extractor
node_extractor -->|"structured events"| node_llm_support
node_llm_support -->|"normalized events"| node_db_models
node_llm_support -->|"event inputs"| node_scores
node_scores -->|"risk overlay"| node_route_engine
node_weather_risk -->|"context signal"| node_scores
node_bayes -.->|"future fusion"| node_scores
node_hgnn -.->|"future model"| node_scores
node_api -->|"serve assets"| node_ui_js

click node_ui "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/static/index.html"
click node_ui_js "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/static/scripts.js"
click node_api "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/api.py"
click node_main "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/main.py"
click node_config "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/config.py"
click node_route_engine "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/routing/route_engine.py"
click node_routing_support "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/routing/geocoder.py"
click node_db_models "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/database/models.py"
click node_rss "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/ingestion/rss_fetcher.py"
click node_newsapi "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/ingestion/news_fetcher.py"
click node_tomtom "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/ingestion/tomtom_fetcher.py"
click node_weather_ingest "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/ingestion/weather_fetcher.py"
click node_scraper "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/ingestion/web_scraper.py"
click node_extractor "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/llm/extractor.py"
click node_llm_support "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/llm/filter.py"
click node_scores "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/scoring/congestion_score.py"
click node_weather_risk "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/weather/weather_risk.py"
click node_bayes "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/fusion/bayesian_fusion.py"
click node_hgnn "https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/hgnn/model.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_ui_js toneBlue
class node_api,node_main,node_config,node_route_engine,node_routing_support,node_db_models toneAmber
class node_rss,node_newsapi,node_tomtom,node_weather_ingest,node_scraper toneMint
class node_extractor,node_llm_support,node_scores,node_weather_risk,node_bayes,node_hgnn toneRose
```

## Components

### Presentation

Browser-facing map UI and static assets

- [Map UI](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/static/index.html): leaflet spa · Single-page map interface for route selection and risk overlays · `app/static/index.html`
- [Client Logic](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/static/scripts.js): frontend script · Browser-side route display and map updates · `app/static/scripts.js`

### Backend

API, orchestration, routing, persistence, and shared runtime settings

- [API Server](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/api.py): fastapi entrypoint · Main web entrypoint coordinating route, ingestion, scoring, and persistence flows · `app/api.py`
- [CLI Pipeline](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/main.py): debug runner · Command-line and debugging entrypoint for offline or manual runs · `app/main.py`
- [Runtime Config](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/config.py): env settings · Centralized environment and credential configuration · `app/config.py`
- [Route Engine](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/routing/route_engine.py): routing core · Generates candidate routes and map-friendly outputs quickly · `app/routing/route_engine.py`
- [Routing Support](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/routing/geocoder.py): geo routing · Geocoding, map matching, multimodal transit, and route cost helpers · `app/routing/geocoder.py`
- [Event Store](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/database/models.py): sqlalchemy models · Persistent storage for extracted traffic events and analysis state · `app/database/models.py`

### Signals

External data ingestion and normalization of disruption evidence

- [RSS Feed](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/ingestion/rss_fetcher.py): news ingestion · Google News RSS connector for live disruption signals · `app/ingestion/rss_fetcher.py`
- [NewsAPI](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/ingestion/news_fetcher.py): news ingestion · External news connector for disruption coverage · `app/ingestion/news_fetcher.py`
- [TomTom Live](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/ingestion/tomtom_fetcher.py): traffic ingestion · Live traffic incident connector · `app/ingestion/tomtom_fetcher.py`
- [Weather Feed](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/ingestion/weather_fetcher.py): weather ingestion · Optional weather signal ingestion · `app/ingestion/weather_fetcher.py`
- [Web Scraper](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/ingestion/web_scraper.py): source scraping · Fallback connector for additional disruption sources · `app/ingestion/web_scraper.py`

### Intelligence

LLM extraction, scoring, and experimental fusion/model layers

- [LLM Extractor](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/llm/extractor.py): llm orchestration · Turns noisy text into structured traffic events · `app/llm/extractor.py`
- [LLM Normalizer](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/llm/filter.py): llm cleanup · Parsing, filtering, schema shaping, and location resolution · `app/llm/filter.py`
- [Risk Scoring](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/scoring/congestion_score.py): impact model · Computes confidence, duration, and congestion impact · `app/scoring/congestion_score.py`
- [Weather Risk](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/weather/weather_risk.py): aux signal · Adds weather-aware route risk adjustment · `app/weather/weather_risk.py`
- [Fusion Layer](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/fusion/bayesian_fusion.py): planned fusion · Placeholder for future Bayesian data fusion · `app/fusion/bayesian_fusion.py`
- [HGNN](https://github.com/lakshya1729git/iit_kgp_internship/blob/main/app/hgnn/model.py): experimental model · Graph-based experimental learning stack for future enrichment · `app/hgnn/model.py`

## Connections

- 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