# svmtejas84/capstone architecture

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

- Interactive diagram: https://gitdiagram.com/svmtejas84/capstone
- Repository: https://github.com/svmtejas84/capstone

## Overview

1. **System shape**
   This is a multi-component Python + TypeScript monorepo for “toxicity-aware navigation.” The core architecture is a pipeline: external data sources feed ingestion, ingestion publishes live state to Redis, the graph/risk layer computes exposure-aware edge costs, routing and matching produce candidate corridors, a FastAPI service exposes results, and a Vite/React frontend visualizes them.

2. **External data boundary**
   The system depends on three live data families: Open-Meteo weather, Open-Meteo air quality, and AQICN/CPCB station observations. Road topology comes from OpenStreetMap via OSMnx. These sources are treated as upstream inputs and are normalized into local Parquet datasets under `data/raw/` and derived graph artifacts under `data/`.

3. **Ingestion and data fusion layer**
   The `ingestion/` package is the live and batch data boundary. It contains fetchers, bias correction, data fusion, nowcasting, traffic-spike handling, and a Redis publisher. This layer turns heterogeneous source data into a unified stream/state model for downstream consumers. The scripts in `scripts/` complement this by pulling archives, repairing gaps, and syncing startup data.

4. **State transport and runtime backbone**
   Redis is the main runtime bus. The README indicates weather, air quality, and sensor streams are published there as near-real-time topics/streams. This makes the system event-driven: ingestion writes state, and the API/routing side reads the latest state without directly coupling to source APIs.

5. **Physics and graph learning layer**
   The `gnn/` package is the toxicity estimation engine. It combines physics-informed plume modeling, wind/edge weighting, and a trained PyTorch model (`gnn/model_weights/pi_gnn_v1.pt`) to estimate edge-level pollutant exposure. Supporting modules like `graph_builder.py`, `edge_weights.py`, `plume_physics.py`, and `wake_predictor.py` define the model’s core data transformations and priors.

6. **Graph artifact boundary**
   The road graph is a distinct artifact produced from OSM data and stored as projected, city-specific graph files. The README references a UTM Zone 43N Bangalore graph and tensorized graph outputs used for GNN training. This separates static infrastructure geometry from live environmental state, which is important for diagramming the data flow.

7. **Routing layer**
   The `router/` package converts toxicity estimates into path costs and routes. It computes inhaled-dose-based edge costs using concentration, respiratory minute volume, and travel time, then runs A* search over the road graph. There is an optional Rust acceleration path in `router/rust_astar/`, which is a performance boundary rather than a functional one.

8. **API service boundary**
   `router/api/main.py` exposes the backend as a FastAPI service. The README names endpoints for health, plume, route, and audit lookup. This service is the main synchronous interface between the model/routing stack and the frontend, and it also reads from Redis state and graph/model artifacts.

9. **Matching and equilibrium layer**
   The `matcher/` package is a separate decision layer that allocates commuters to corridors using Gale-Shapley stable matching, quotas, segment preferences, and equilibrium checks. This sits above raw pathfinding: routing produces candidate corridors, while matching distributes users across them to avoid congestion or unsafe concentration on a single path.

10. **Auditability and reproducibility**
   `router/stake_audit.py` and the `/audit/{hash}` endpoint provide an immutable decision trace. The audit includes request context, model version, graph snapshot, stream state, and timestamps. Architecturally, this is a compliance/reproducibility boundary around route generation.

11. **Frontend presentation layer**
   `frontend/` is a separate Vite + React + TypeScript application. Components like `PlumeMap`, `RoutePanel`, `EquilibriumViz`, `AgentSim`, and `AuditViewer` suggest the UI is organized around map visualization, route comparison, simulation, and audit inspection. It consumes the FastAPI backend via `frontend/src/api/client.ts` and stream-like hooks for plume/route updates.

12. **Shared utilities and configuration**
   `shared/` holds cross-cutting concerns used by multiple backend packages: config, geo utilities, logging, physics config, Redis client, and schemas. This package is the common contract layer that keeps ingestion, routing, matcher, and API aligned on data shapes and deployment settings.

13. **Operational and deployment boundaries**
   The repo includes `docker-compose.yml`, GitHub Actions CI/deploy workflows, and startup scripts like `scripts/quickstart.sh` and `scripts/sync_on_entry.py`. That indicates the system is designed to run as a small set of cooperating services rather than a single monolith: Redis + ingestion worker + FastAPI backend + frontend, with optional Rust acceleration and offline batch prep.

14. **What to emphasize in an architecture diagram**
   The most important boundaries are: external data sources vs. local processing, batch data preparation vs. live stream ingestion, Redis as the live state bus, GNN/physics as the exposure engine, routing/matching as decision layers, API as the synchronous interface, and the frontend as the visualization/interaction layer. The static graph/model artifacts and the audit trail should be shown as separate storage and traceability components.

Main entry points: [`ingestion`](https://github.com/svmtejas84/capstone/tree/main/ingestion) (Ingestion), [`router/api/main.py`](https://github.com/svmtejas84/capstone/blob/main/router/api/main.py) (FastAPI), [`shared/redis_client.py`](https://github.com/svmtejas84/capstone/blob/main/shared/redis_client.py) (Redis bus), [`router`](https://github.com/svmtejas84/capstone/tree/main/router) (Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sources["External sources"]
  node_open_meteo_weather(("Weather<br/>external source"))
  node_open_meteo_air(("Air quality<br/>external source"))
  node_aqicn_cpcb(("Station obs<br/>external source"))
end

subgraph group_data["Data layer"]
  node_osm_graph[("Road graph<br/>graph artifact")]
  node_raw_datasets[("Raw data<br/>local datasets")]
  node_scripts["Prep scripts<br/>batch prep"]
end

subgraph group_core["Core backend"]
  node_ingestion["Ingestion<br/>live fusion"]
  node_redis_bus[("Redis bus<br/>state backbone<br/>[redis_client.py]")]
  node_gnn["Exposure engine<br/>physics-gnn"]
  node_route_costs["Edge costs<br/>routing cost model<br/>[edge_cost.py]"]
  node_router_core["Router<br/>pathfinding"]
  node_matcher["Matcher<br/>allocation"]
  node_audit["Audit trail<br/>traceability<br/>[stake_audit.py]"]
  node_api["FastAPI<br/>service api<br/>[main.py]"]
  node_shared["Shared core<br/>common contracts"]
end

subgraph group_ui["Frontend"]
  node_frontend_app["Web app<br/>react ui"]
end

subgraph group_ops["Operations"]
  node_docker_compose["Compose<br/>deployment<br/>[docker-compose.yml]"]
  node_ci_cd["CI/CD<br/>automation<br/>[workflows]"]
end

node_open_meteo_weather -->|"weather"| node_ingestion
node_open_meteo_air -->|"air"| node_ingestion
node_aqicn_cpcb -->|"stations"| node_ingestion
node_osm_graph -->|"graph input"| node_gnn
node_raw_datasets -->|"batch input"| node_ingestion
node_scripts -->|"prepare"| node_raw_datasets
node_scripts -->|"build"| node_osm_graph
node_ingestion -->|"publish"| node_redis_bus
node_redis_bus -->|"state"| node_gnn
node_redis_bus -->|"latest state"| node_router_core
node_shared -->|"contracts"| node_ingestion
node_shared -->|"physics config"| node_gnn
node_shared -->|"geo/config"| node_router_core
node_gnn -->|"exposure"| node_route_costs
node_route_costs -->|"weights"| node_router_core
node_router_core -->|"candidate corridors"| node_matcher
node_matcher -->|"results"| node_api
node_router_core -->|"trace"| node_audit
node_audit -->|"lookup"| node_api
node_api -->|"serve"| node_frontend_app
node_redis_bus -->|"live reads"| node_api
node_docker_compose -->|"runs"| node_redis_bus
node_docker_compose -->|"runs"| node_api
node_ci_cd -->|"validate"| node_api
node_ci_cd -->|"validate"| node_frontend_app

click node_osm_graph "https://github.com/svmtejas84/capstone/tree/main/data"
click node_raw_datasets "https://github.com/svmtejas84/capstone/tree/main/data/raw"
click node_scripts "https://github.com/svmtejas84/capstone/tree/main/scripts"
click node_ingestion "https://github.com/svmtejas84/capstone/tree/main/ingestion"
click node_redis_bus "https://github.com/svmtejas84/capstone/blob/main/shared/redis_client.py"
click node_gnn "https://github.com/svmtejas84/capstone/tree/main/gnn"
click node_route_costs "https://github.com/svmtejas84/capstone/blob/main/router/edge_cost.py"
click node_router_core "https://github.com/svmtejas84/capstone/tree/main/router"
click node_matcher "https://github.com/svmtejas84/capstone/tree/main/matcher"
click node_audit "https://github.com/svmtejas84/capstone/blob/main/router/stake_audit.py"
click node_api "https://github.com/svmtejas84/capstone/blob/main/router/api/main.py"
click node_frontend_app "https://github.com/svmtejas84/capstone/tree/main/frontend/src"
click node_shared "https://github.com/svmtejas84/capstone/tree/main/shared"
click node_docker_compose "https://github.com/svmtejas84/capstone/blob/main/docker-compose.yml"
click node_ci_cd "https://github.com/svmtejas84/capstone/blob/main/.github/workflows"

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_open_meteo_weather,node_open_meteo_air,node_aqicn_cpcb toneBlue
class node_osm_graph,node_raw_datasets,node_scripts toneAmber
class node_ingestion,node_redis_bus,node_gnn,node_route_costs,node_router_core,node_matcher,node_audit,node_api,node_shared toneMint
class node_frontend_app toneRose
class node_docker_compose,node_ci_cd toneIndigo
```

## Components

### External sources

Upstream environmental and road-data inputs.

- **Weather**: external source · Open-Meteo weather feeds used for wind and atmospheric context.
- **Air quality**: external source · Open-Meteo air-quality feeds used as live environmental input.
- **Station obs**: external source · AQICN/CPCB station observations for ground-truth pollutant measurements.

### Data layer

Batch ingestion, fusion, and local artifacts.

- [Road graph](https://github.com/svmtejas84/capstone/tree/main/data): graph artifact · Projected road-network artifact derived from OpenStreetMap/OSMnx and stored under data/. · `data`
- [Raw data](https://github.com/svmtejas84/capstone/tree/main/data/raw): local datasets · Normalized Parquet and checkpointed source data under data/raw/. · `data/raw`
- [Prep scripts](https://github.com/svmtejas84/capstone/tree/main/scripts): batch prep · Archive pulls, gap repair, graph tensor build, and startup sync scripts. · `scripts`

### Core backend

Live state bus, exposure modeling, routing, matching, and API.

- [Ingestion](https://github.com/svmtejas84/capstone/tree/main/ingestion): live fusion · Fetchers, bias correction, data fusion, nowcasting, and traffic-spike handling. · `ingestion`
- [Redis bus](https://github.com/svmtejas84/capstone/blob/main/shared/redis_client.py): state backbone · Live runtime bus for weather, air quality, and sensor streams. · `shared/redis_client.py`
- [Exposure engine](https://github.com/svmtejas84/capstone/tree/main/gnn): physics-gnn · Physics-informed plume modeling and trained GNN edge exposure estimation. · `gnn`
- [Edge costs](https://github.com/svmtejas84/capstone/blob/main/router/edge_cost.py): routing cost model · Turns exposure and inhalation into inhaled-dose-based edge weights. · `router/edge_cost.py`
- [Router](https://github.com/svmtejas84/capstone/tree/main/router): pathfinding · A* routing over the road graph, including optional Rust acceleration. · `router`
- [Matcher](https://github.com/svmtejas84/capstone/tree/main/matcher): allocation · Stable matching, quotas, route pools, and equilibrium checks for commuter assignment. · `matcher`
- [Audit trail](https://github.com/svmtejas84/capstone/blob/main/router/stake_audit.py): traceability · Immutable decision trace with request context, model version, graph snapshot, and stream state. · `router/stake_audit.py`
- [FastAPI](https://github.com/svmtejas84/capstone/blob/main/router/api/main.py): service api · Synchronous backend surface for health, plume, route, and audit endpoints. · `router/api/main.py`
- [Shared core](https://github.com/svmtejas84/capstone/tree/main/shared): common contracts · Shared config, geo utilities, logging, physics settings, Redis client, and schemas. · `shared`

### Frontend

Browser application for visualization and interaction.

- [Web app](https://github.com/svmtejas84/capstone/tree/main/frontend/src): react ui · Vite/React frontend for plume maps, routes, equilibrium views, simulations, and audits. · `frontend/src`

### Operations

Deployment, startup, and reproducibility boundaries.

- [Compose](https://github.com/svmtejas84/capstone/blob/main/docker-compose.yml): deployment · Service composition for Redis, backend, worker flows, and frontend. · `docker-compose.yml`
- [CI/CD](https://github.com/svmtejas84/capstone/blob/main/.github/workflows): automation · GitHub Actions workflows for validation and deployment. · `.github/workflows`

## Connections

- Weather → Ingestion: weather · Weather feeds are fetched and normalized into the live pipeline.
- Air quality → Ingestion: air · Air-quality feeds are fetched and normalized into the live pipeline.
- Station obs → Ingestion: stations · Station observations are fused into the live pipeline.
- Road graph → Exposure engine: graph input · Static road geometry is consumed for exposure modeling.
- Raw data → Ingestion: batch input · Archived and checkpointed data support ingestion and repair.
- Prep scripts → Raw data: prepare · Scripts pull archives, repair gaps, and build derived datasets.
- Prep scripts → Road graph: build · Scripts produce graph tensors and derived graph artifacts.
- Ingestion → Redis bus: publish · Ingestion publishes near-real-time streams and state to Redis.
- Redis bus → Exposure engine: state · The exposure engine reads live environmental state.
- Redis bus → Router: latest state · Routing reads current stream state without direct source coupling.
- Shared core → Ingestion: contracts · Shared config, schemas, and utilities align ingestion with the rest of the system.
- Shared core → Exposure engine: physics config · Shared physics and schema utilities support model computation.
- Shared core → Router: geo/config · Shared geometry and config support routing calculations.
- Exposure engine → Edge costs: exposure · Edge-level exposure estimates feed routing cost calculation.
- Edge costs → Router: weights · Dose-based costs are used by the A* router.
- Router → Matcher: candidate corridors · Routing provides corridor options for commuter allocation.
- Matcher → FastAPI: results · Matching outcomes are exposed through the backend service.
- Router → Audit trail: trace · Route decisions are captured for reproducibility and compliance.
- Audit trail → FastAPI: lookup · Audit records are retrievable through the service API.
- FastAPI → Web app: serve · Frontend consumes route, plume, and audit endpoints from the API.
- Redis bus → FastAPI: live reads · API reads current stream state for synchronous requests.
- Compose → Redis bus: runs · Compose defines the runtime backbone for local deployment.
- Compose → FastAPI: runs · Compose orchestrates the backend service.
- CI/CD → FastAPI: validate · Workflows test and deploy backend changes.
- CI/CD → Web app: validate · Workflows test and deploy frontend changes.
