# priyadarsh912/airindex-india architecture

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

- Interactive diagram: https://gitdiagram.com/priyadarsh912/airindex-india
- Repository: https://github.com/priyadarsh912/airindex-india

## Overview

AirIndex India collects airfare observations, cleans and scores them, then computes weighted and alternative price indices for CPI-oriented monitoring. Its user-facing workflow is the React dashboard consuming a FastAPI service and presenting index trends, anomalies, backtests, explainability, and observation data. Collection includes live Google Flights scraping and a generated DGCA-modeled reference series; persistence supports a local SQL ledger and Supabase. The README documents additional compliance, basket, and institutional API capabilities, but their internal wiring is not established by the sampled excerpts, so uncertain links are left out or marked unverified.

Main entry points: [`frontend/src/App.jsx`](https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/App.jsx) (Dashboard application), [`backend/quality_engine.py`](https://github.com/priyadarsh912/airindex-india/blob/main/backend/quality_engine.py) (Quality pipeline), [`backend/providers/fast_flights_provider.py`](https://github.com/priyadarsh912/airindex-india/blob/main/backend/providers/fast_flights_provider.py) (FastFlights provider), [`backend/scraper/corridor_runner.py`](https://github.com/priyadarsh912/airindex-india/blob/main/backend/scraper/corridor_runner.py) (Corridor runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection and storage"]
  node_fast_provider["FastFlights provider"]
  node_google_scraper["Google Flights scraper<br/>[google_flights.py]"]
  node_corridor_runner["Corridor runner<br/>[corridor_runner.py]"]
  node_scheduler["Autonomous collection"]
  node_collector_planner["Collector planner"]
  node_fixture_data["Reference data generator<br/>[data_generator.py]"]
  node_persistence[("Observation persistence<br/>[supabase.py]")]
  node_db_client["Database client<br/>[db_client.py]"]
end

subgraph group_processing["Fare processing"]
  node_fare_normalizer["Fare normalizer<br/>[fare_normalizer.py]"]
  node_fee_deriver["Fee derivation<br/>[fee_deriver.py]"]
  node_fare_validator["Fare validation<br/>[fare_validator.py]"]
  node_quality["Quality pipeline<br/>[quality_engine.py]"]
  node_flight_registry[("Flight registry<br/>[flight_registry.py]")]
end

subgraph group_analytics["Statistical analytics"]
  node_basket["Representative basket"]
  node_index_engine["Airfare index engine<br/>[index_engine.py]"]
  node_anomaly["Surge and anomalies<br/>[anomaly_engine.py]"]
  node_backtest["Backtest analytics<br/>[backtest_engine.py]"]
  node_clustering["Corridor clustering"]
  node_compliance["Collection compliance"]
end

subgraph group_service["API service"]
  node_api["FastAPI service<br/>[main.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_frontend_app["Dashboard application<br/>[App.jsx]"]
  node_data_hook["Dashboard data hook<br/>[useAirScopeData.js]"]
  node_trend_view["Index trend view"]
  node_explorer_view["Observation explorer"]
  node_surge_view["Surge alerts view"]
  node_explain_view["Index explainability"]
  node_backtest_view["Backtest view"]
  node_basket_view["Basket management view<br/>[PSDBasketView.jsx]"]
  node_source_view["Source comparison view"]
  node_integrity_view["Data integrity view"]
  node_api_docs_view["API documentation view<br/>[APIDocsView.jsx]"]
end

node_user(("Institutional user"))

node_user -->|"uses"| node_frontend_app
node_frontend_app -->|"loads data"| node_data_hook
node_frontend_app -->|"renders"| node_trend_view
node_frontend_app -->|"renders"| node_surge_view
node_frontend_app -->|"renders"| node_explorer_view
node_frontend_app -->|"renders"| node_explain_view
node_frontend_app -->|"renders"| node_backtest_view
node_frontend_app -->|"renders"| node_integrity_view
node_frontend_app -->|"renders"| node_api_docs_view
node_frontend_app -->|"renders"| node_basket_view
node_frontend_app -->|"renders"| node_source_view
node_fast_provider -->|"scrapes via"| node_google_scraper
node_fast_provider -->|"normalizes via"| node_fare_normalizer
node_google_scraper -.->|"persists observations"| node_persistence
node_corridor_runner -.->|"uses scraper"| node_google_scraper
node_corridor_runner -.->|"uses client"| node_db_client
node_scheduler -.->|"dispatches"| node_corridor_runner
node_collector_planner -.->|"selects provider"| node_fast_provider
node_persistence -.->|"uses ledger"| node_db_client
node_quality -.->|"validates fares"| node_fare_validator
node_quality -.->|"normalizes classes"| node_fare_normalizer
node_quality -->|"cleaned data"| node_index_engine
node_basket -.->|"supplies weights"| node_index_engine
node_fixture_data -.->|"generates benchmark"| node_backtest
node_anomaly -.->|"alerts shown in"| node_surge_view
node_index_engine -.->|"contributions shown in"| node_explain_view
node_backtest -.->|"results shown in"| node_backtest_view
node_api -.->|"serves data"| node_data_hook

click node_fast_provider "https://github.com/priyadarsh912/airindex-india/blob/main/backend/providers/fast_flights_provider.py"
click node_google_scraper "https://github.com/priyadarsh912/airindex-india/blob/main/backend/scraper/google_flights.py"
click node_corridor_runner "https://github.com/priyadarsh912/airindex-india/blob/main/backend/scraper/corridor_runner.py"
click node_scheduler "https://github.com/priyadarsh912/airindex-india/blob/main/backend/autonomous_scheduler.py"
click node_collector_planner "https://github.com/priyadarsh912/airindex-india/blob/main/backend/collector_planner.py"
click node_fixture_data "https://github.com/priyadarsh912/airindex-india/blob/main/backend/data_generator.py"
click node_persistence "https://github.com/priyadarsh912/airindex-india/blob/main/backend/database/supabase.py"
click node_db_client "https://github.com/priyadarsh912/airindex-india/blob/main/backend/db_client.py"
click node_fare_normalizer "https://github.com/priyadarsh912/airindex-india/blob/main/backend/fare_normalizer.py"
click node_fee_deriver "https://github.com/priyadarsh912/airindex-india/blob/main/backend/fee_deriver.py"
click node_fare_validator "https://github.com/priyadarsh912/airindex-india/blob/main/backend/fare_validator.py"
click node_quality "https://github.com/priyadarsh912/airindex-india/blob/main/backend/quality_engine.py"
click node_flight_registry "https://github.com/priyadarsh912/airindex-india/blob/main/backend/flight_registry.py"
click node_basket "https://github.com/priyadarsh912/airindex-india/blob/main/backend/psd_basket_manager.py"
click node_index_engine "https://github.com/priyadarsh912/airindex-india/blob/main/backend/index_engine.py"
click node_anomaly "https://github.com/priyadarsh912/airindex-india/blob/main/backend/anomaly_engine.py"
click node_backtest "https://github.com/priyadarsh912/airindex-india/blob/main/backend/backtest_engine.py"
click node_clustering "https://github.com/priyadarsh912/airindex-india/blob/main/backend/clustering_engine.py"
click node_compliance "https://github.com/priyadarsh912/airindex-india/blob/main/backend/compliance_gateway.py"
click node_api "https://github.com/priyadarsh912/airindex-india/blob/main/backend/main.py"
click node_frontend_app "https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/App.jsx"
click node_data_hook "https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/hooks/useAirScopeData.js"
click node_trend_view "https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/IndexTrendChart.jsx"
click node_explorer_view "https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/DataExplorerView.jsx"
click node_surge_view "https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/SurgeAlertsPanel.jsx"
click node_explain_view "https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/ExplainabilityView.jsx"
click node_backtest_view "https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/BacktestValidationView.jsx"
click node_basket_view "https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/PSDBasketView.jsx"
click node_source_view "https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/SourceComparisonView.jsx"
click node_integrity_view "https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/DataIntegrityView.jsx"
click node_api_docs_view "https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/APIDocsView.jsx"

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_fast_provider,node_google_scraper,node_corridor_runner,node_scheduler,node_collector_planner,node_fixture_data,node_persistence,node_db_client,node_user toneBlue
class node_fare_normalizer,node_fee_deriver,node_fare_validator,node_quality,node_flight_registry toneAmber
class node_basket,node_index_engine,node_anomaly,node_backtest,node_clustering,node_compliance toneMint
class node_api toneRose
class node_frontend_app,node_data_hook,node_trend_view,node_explorer_view,node_surge_view,node_explain_view,node_backtest_view,node_basket_view,node_source_view,node_integrity_view,node_api_docs_view toneIndigo
```

## Components

### Collection and storage

- [FastFlights provider](https://github.com/priyadarsh912/airindex-india/blob/main/backend/providers/fast_flights_provider.py): `backend/providers/fast_flights_provider.py`
- [Google Flights scraper](https://github.com/priyadarsh912/airindex-india/blob/main/backend/scraper/google_flights.py): `backend/scraper/google_flights.py`
- [Corridor runner](https://github.com/priyadarsh912/airindex-india/blob/main/backend/scraper/corridor_runner.py): `backend/scraper/corridor_runner.py`
- [Autonomous collection](https://github.com/priyadarsh912/airindex-india/blob/main/backend/autonomous_scheduler.py): `backend/autonomous_scheduler.py`
- [Collector planner](https://github.com/priyadarsh912/airindex-india/blob/main/backend/collector_planner.py): `backend/collector_planner.py`
- [Reference data generator](https://github.com/priyadarsh912/airindex-india/blob/main/backend/data_generator.py): `backend/data_generator.py`
- [Observation persistence](https://github.com/priyadarsh912/airindex-india/blob/main/backend/database/supabase.py): `backend/database/supabase.py`
- [Database client](https://github.com/priyadarsh912/airindex-india/blob/main/backend/db_client.py): `backend/db_client.py`

### Fare processing

- [Fare normalizer](https://github.com/priyadarsh912/airindex-india/blob/main/backend/fare_normalizer.py): `backend/fare_normalizer.py`
- [Fee derivation](https://github.com/priyadarsh912/airindex-india/blob/main/backend/fee_deriver.py): `backend/fee_deriver.py`
- [Fare validation](https://github.com/priyadarsh912/airindex-india/blob/main/backend/fare_validator.py): `backend/fare_validator.py`
- [Quality pipeline](https://github.com/priyadarsh912/airindex-india/blob/main/backend/quality_engine.py): `backend/quality_engine.py`
- [Flight registry](https://github.com/priyadarsh912/airindex-india/blob/main/backend/flight_registry.py): `backend/flight_registry.py`

### Statistical analytics

- [Representative basket](https://github.com/priyadarsh912/airindex-india/blob/main/backend/psd_basket_manager.py): `backend/psd_basket_manager.py`
- [Airfare index engine](https://github.com/priyadarsh912/airindex-india/blob/main/backend/index_engine.py): `backend/index_engine.py`
- [Surge and anomalies](https://github.com/priyadarsh912/airindex-india/blob/main/backend/anomaly_engine.py): `backend/anomaly_engine.py`
- [Backtest analytics](https://github.com/priyadarsh912/airindex-india/blob/main/backend/backtest_engine.py): `backend/backtest_engine.py`
- [Corridor clustering](https://github.com/priyadarsh912/airindex-india/blob/main/backend/clustering_engine.py): `backend/clustering_engine.py`
- [Collection compliance](https://github.com/priyadarsh912/airindex-india/blob/main/backend/compliance_gateway.py): `backend/compliance_gateway.py`

### API service

- [FastAPI service](https://github.com/priyadarsh912/airindex-india/blob/main/backend/main.py): `backend/main.py`

### Dashboard

- [Dashboard application](https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Dashboard data hook](https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/hooks/useAirScopeData.js): `frontend/src/hooks/useAirScopeData.js`
- [Index trend view](https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/IndexTrendChart.jsx): `frontend/src/components/IndexTrendChart.jsx`
- [Observation explorer](https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/DataExplorerView.jsx): `frontend/src/components/DataExplorerView.jsx`
- [Surge alerts view](https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/SurgeAlertsPanel.jsx): `frontend/src/components/SurgeAlertsPanel.jsx`
- [Index explainability](https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/ExplainabilityView.jsx): `frontend/src/components/ExplainabilityView.jsx`
- [Backtest view](https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/BacktestValidationView.jsx): `frontend/src/components/BacktestValidationView.jsx`
- [Basket management view](https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/PSDBasketView.jsx): `frontend/src/components/PSDBasketView.jsx`
- [Source comparison view](https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/SourceComparisonView.jsx): `frontend/src/components/SourceComparisonView.jsx`
- [Data integrity view](https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/DataIntegrityView.jsx): `frontend/src/components/DataIntegrityView.jsx`
- [API documentation view](https://github.com/priyadarsh912/airindex-india/blob/main/frontend/src/components/APIDocsView.jsx): `frontend/src/components/APIDocsView.jsx`

### Other components

- **Institutional user**

## Connections

- Institutional user → Dashboard application: uses (evidence: `README.md`)
- Dashboard application → Dashboard data hook: loads data (evidence: `frontend/src/App.jsx`)
- Dashboard application → Index trend view: renders (evidence: `frontend/src/App.jsx`)
- Dashboard application → Surge alerts view: renders (evidence: `frontend/src/App.jsx`)
- Dashboard application → Observation explorer: renders (evidence: `frontend/src/App.jsx`)
- Dashboard application → Index explainability: renders (evidence: `frontend/src/App.jsx`)
- Dashboard application → Backtest view: renders (evidence: `frontend/src/App.jsx`)
- Dashboard application → Data integrity view: renders (evidence: `frontend/src/App.jsx`)
- Dashboard application → API documentation view: renders (evidence: `frontend/src/App.jsx`)
- Dashboard application → Basket management view: renders (evidence: `frontend/src/App.jsx`)
- Dashboard application → Source comparison view: renders (evidence: `frontend/src/App.jsx`)
- FastFlights provider → Google Flights scraper: scrapes via (evidence: `backend/providers/fast_flights_provider.py`)
- FastFlights provider → Fare normalizer: normalizes via (evidence: `backend/providers/fast_flights_provider.py`)
- Google Flights scraper → Observation persistence: persists observations
- Corridor runner → Google Flights scraper: uses scraper (evidence: `backend/scraper/corridor_runner.py`)
- Corridor runner → Database client: uses client (evidence: `backend/scraper/corridor_runner.py`)
- Autonomous collection → Corridor runner: dispatches
- Collector planner → FastFlights provider: selects provider (evidence: `backend/collector_planner.py`)
- Observation persistence → Database client: uses ledger (evidence: `backend/database/supabase.py`)
- Quality pipeline → Fare validation: validates fares (evidence: `backend/quality_engine.py`)
- Quality pipeline → Fare normalizer: normalizes classes (evidence: `backend/quality_engine.py`)
- Quality pipeline → Airfare index engine: cleaned data (evidence: `README.md`)
- Representative basket → Airfare index engine: supplies weights (evidence: `backend/index_engine.py`)
- Reference data generator → Backtest analytics: generates benchmark (evidence: `backend/backtest_engine.py`)
- Surge and anomalies → Surge alerts view: alerts shown in
- Airfare index engine → Index explainability: contributions shown in
- Backtest analytics → Backtest view: results shown in
- FastAPI service → Dashboard data hook: serves data