# mondalsrinjoy14-coder/aerotrace architecture

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

- Interactive diagram: https://gitdiagram.com/mondalsrinjoy14-coder/aerotrace
- Repository: https://github.com/mondalsrinjoy14-coder/aerotrace

## Overview

AeroTrace is a research prototype for investigating possible GNSS interference from aircraft ADS-B data; its alerts are candidate evidence, not confirmation. The main workflow is analyst dashboard or CSV input → API ingestion and validation → stored observations → physics-based detection, multi-aircraft clustering, and event interpretation → persisted evidence and alerts → dashboard review. Live provider ingestion, alert integrations, and optional ML are additional capabilities. The graph follows documented behavior and indexed references; some unsampled subsystem internals and wiring are necessarily summarized or omitted.

Main entry points: [`Aerotrace-main/backend/app/detectors/service.py`](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/detectors/service.py) (Detection orchestration), [`Aerotrace-main/backend/app/api/routes.py`](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/api/routes.py) (HTTP API), [`Aerotrace-main/src/components/Dashboard.tsx`](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/src/components/Dashboard.tsx) (Dashboard), [`Aerotrace-main/src/lib/api.ts`](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/src/lib/api.ts) (Typed API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Analyst interface"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_airspace["Airspace view<br/>[AirspaceView.tsx]"]
  node_csvtracking["CSV replay<br/>[CsvTracking.tsx]"]
  node_explorer["Track explorer<br/>[explorer.ts]"]
  node_api_client["Typed API client<br/>[api.ts]"]
end

subgraph group_ingest["Observation ingestion"]
  node_http_api["HTTP API<br/>[routes.py]"]
  node_provider_ingest["ADS-B providers<br/>[opensky.py]"]
  node_csv_import["CSV import<br/>[csv_import.py]"]
  node_normalization["Observation normalization<br/>[observations.py]"]
  node_ingest_pipeline["Ingest pipeline<br/>[pipeline.py]"]
end

subgraph group_analysis["Detection and investigation"]
  node_detection_service["Detection orchestration<br/>[service.py]"]
  node_physics_detectors["Physics checks<br/>[detectors.py]"]
  node_detector_features["Track features<br/>[features.py]"]
  node_clustering["Spatial clustering<br/>[clustering.py]"]
  node_events["Investigation events<br/>[clustering.py]"]
end

subgraph group_state["Persistence and alerts"]
  node_store[("SQLite store<br/>[store.py]")]
  node_alert_rules["Alert evaluation<br/>[alerts.py]"]
  node_notifications["Notifications<br/>[notifications.py]"]
end

subgraph group_optional["Optional modeling"]
  node_ml_service["Model inference<br/>[service.py]"]
  node_ml_features["ML features<br/>[features.py]"]
  node_lstm["LSTM training<br/>[lstm_pipeline.py]"]
end

node_analyst(("Analyst"))

node_analyst -->|"reviews"| node_dashboard
node_dashboard -->|"requests data"| node_api_client
node_dashboard -->|"renders"| node_airspace
node_dashboard -->|"renders"| node_csvtracking
node_airspace -->|"fetches observations"| node_api_client
node_airspace -->|"builds tracks"| node_explorer
node_csvtracking -->|"submits CSV"| node_api_client
node_api_client -->|"calls endpoints"| node_http_api
node_http_api -->|"dispatches fetch"| node_provider_ingest
node_http_api -->|"parses uploads"| node_csv_import
node_http_api -->|"submits records"| node_ingest_pipeline
node_ingest_pipeline -->|"normalizes rows"| node_normalization
node_ingest_pipeline -->|"writes observations"| node_store
node_http_api -->|"starts detection"| node_detection_service
node_detection_service -->|"reads tracks"| node_store
node_detection_service -->|"runs checks"| node_physics_detectors
node_physics_detectors -->|"uses features"| node_detector_features
node_detection_service -->|"clusters detections"| node_clustering
node_detection_service -->|"interprets clusters"| node_events
node_detection_service -->|"persists results"| node_store
node_detection_service -->|"evaluates alerts"| node_alert_rules
node_alert_rules -->|"reads and writes rules"| node_store
node_alert_rules -->|"dispatches notices"| node_notifications
node_http_api -->|"requests model status"| node_ml_service
node_ml_service -->|"extracts vectors"| node_ml_features
node_ml_service -->|"uses sequence contract"| node_lstm

click node_dashboard "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/src/components/Dashboard.tsx"
click node_airspace "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/src/components/AirspaceView.tsx"
click node_csvtracking "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/src/components/CsvTracking.tsx"
click node_explorer "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/src/lib/explorer.ts"
click node_api_client "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/src/lib/api.ts"
click node_http_api "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/api/routes.py"
click node_provider_ingest "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ingestion/opensky.py"
click node_csv_import "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ingestion/csv_import.py"
click node_normalization "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ingestion/observations.py"
click node_ingest_pipeline "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ingestion/pipeline.py"
click node_detection_service "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/detectors/service.py"
click node_physics_detectors "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/detectors/detectors.py"
click node_detector_features "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/detectors/features.py"
click node_clustering "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/detectors/clustering.py"
click node_events "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/detectors/clustering.py"
click node_store "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/store.py"
click node_alert_rules "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/alerts.py"
click node_notifications "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/notifications.py"
click node_ml_service "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ml/service.py"
click node_ml_features "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ml/features.py"
click node_lstm "https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ml/lstm_pipeline.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_dashboard,node_airspace,node_csvtracking,node_explorer,node_api_client toneBlue
class node_http_api,node_provider_ingest,node_csv_import,node_normalization,node_ingest_pipeline toneAmber
class node_detection_service,node_physics_detectors,node_detector_features,node_clustering,node_events toneMint
class node_store,node_alert_rules,node_notifications toneRose
class node_ml_service,node_ml_features,node_lstm,node_analyst toneIndigo
```

## Components

### Analyst interface

- [Dashboard](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/src/components/Dashboard.tsx): `Aerotrace-main/src/components/Dashboard.tsx`
- [Airspace view](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/src/components/AirspaceView.tsx): `Aerotrace-main/src/components/AirspaceView.tsx`
- [CSV replay](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/src/components/CsvTracking.tsx): `Aerotrace-main/src/components/CsvTracking.tsx`
- [Track explorer](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/src/lib/explorer.ts): `Aerotrace-main/src/lib/explorer.ts`
- [Typed API client](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/src/lib/api.ts): `Aerotrace-main/src/lib/api.ts`

### Observation ingestion

- [HTTP API](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/api/routes.py): `Aerotrace-main/backend/app/api/routes.py`
- [ADS-B providers](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ingestion/opensky.py): `Aerotrace-main/backend/app/ingestion/opensky.py`
- [CSV import](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ingestion/csv_import.py): `Aerotrace-main/backend/app/ingestion/csv_import.py`
- [Observation normalization](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ingestion/observations.py): `Aerotrace-main/backend/app/ingestion/observations.py`
- [Ingest pipeline](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ingestion/pipeline.py): `Aerotrace-main/backend/app/ingestion/pipeline.py`

### Detection and investigation

- [Detection orchestration](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/detectors/service.py): `Aerotrace-main/backend/app/detectors/service.py`
- [Physics checks](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/detectors/detectors.py): `Aerotrace-main/backend/app/detectors/detectors.py`
- [Track features](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/detectors/features.py): `Aerotrace-main/backend/app/detectors/features.py`
- [Spatial clustering](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/detectors/clustering.py): `Aerotrace-main/backend/app/detectors/clustering.py`
- [Investigation events](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/detectors/clustering.py): `Aerotrace-main/backend/app/detectors/clustering.py`

### Persistence and alerts

- [SQLite store](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/store.py): `Aerotrace-main/backend/app/store.py`
- [Alert evaluation](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/alerts.py): `Aerotrace-main/backend/app/alerts.py`
- [Notifications](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/notifications.py): `Aerotrace-main/backend/app/notifications.py`

### Optional modeling

- [Model inference](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ml/service.py): `Aerotrace-main/backend/app/ml/service.py`
- [ML features](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ml/features.py): `Aerotrace-main/backend/app/ml/features.py`
- [LSTM training](https://github.com/mondalsrinjoy14-coder/aerotrace/blob/main/Aerotrace-main/backend/app/ml/lstm_pipeline.py): `Aerotrace-main/backend/app/ml/lstm_pipeline.py`

### Other components

- **Analyst**

## Connections

- Analyst → Dashboard: reviews
- Dashboard → Typed API client: requests data (evidence: `Aerotrace-main/src/components/Dashboard.tsx`)
- Dashboard → Airspace view: renders (evidence: `Aerotrace-main/src/components/Dashboard.tsx`)
- Dashboard → CSV replay: renders (evidence: `Aerotrace-main/src/components/Dashboard.tsx`)
- Airspace view → Typed API client: fetches observations (evidence: `Aerotrace-main/src/components/AirspaceView.tsx`)
- Airspace view → Track explorer: builds tracks (evidence: `Aerotrace-main/src/components/AirspaceView.tsx`)
- CSV replay → Typed API client: submits CSV (evidence: `Aerotrace-main/src/components/CsvTracking.tsx`)
- Typed API client → HTTP API: calls endpoints (evidence: `Aerotrace-main/src/lib/api.ts`)
- HTTP API → ADS-B providers: dispatches fetch (evidence: `Aerotrace-main/backend/app/api/routes.py`)
- HTTP API → CSV import: parses uploads (evidence: `Aerotrace-main/backend/app/api/routes.py`)
- HTTP API → Ingest pipeline: submits records (evidence: `Aerotrace-main/backend/app/api/routes.py`)
- Ingest pipeline → Observation normalization: normalizes rows (evidence: `Aerotrace-main/backend/app/ingestion/pipeline.py`)
- Ingest pipeline → SQLite store: writes observations (evidence: `Aerotrace-main/backend/app/ingestion/pipeline.py`)
- HTTP API → Detection orchestration: starts detection (evidence: `Aerotrace-main/backend/app/api/routes.py`)
- Detection orchestration → SQLite store: reads tracks (evidence: `Aerotrace-main/backend/app/detectors/service.py`)
- Detection orchestration → Physics checks: runs checks (evidence: `Aerotrace-main/backend/app/detectors/service.py`)
- Physics checks → Track features: uses features (evidence: `Aerotrace-main/backend/app/detectors/detectors.py`)
- Detection orchestration → Spatial clustering: clusters detections (evidence: `Aerotrace-main/backend/app/detectors/service.py`)
- Detection orchestration → Investigation events: interprets clusters (evidence: `Aerotrace-main/backend/app/detectors/service.py`)
- Detection orchestration → SQLite store: persists results (evidence: `Aerotrace-main/backend/app/detectors/service.py`)
- Detection orchestration → Alert evaluation: evaluates alerts (evidence: `Aerotrace-main/backend/app/detectors/service.py`)
- Alert evaluation → SQLite store: reads and writes rules (evidence: `Aerotrace-main/backend/app/alerts.py`)
- Alert evaluation → Notifications: dispatches notices (evidence: `Aerotrace-main/backend/app/alerts.py`)
- HTTP API → Model inference: requests model status (evidence: `Aerotrace-main/backend/app/api/routes.py`)
- Model inference → ML features: extracts vectors (evidence: `Aerotrace-main/backend/app/ml/service.py`)
- Model inference → LSTM training: uses sequence contract (evidence: `Aerotrace-main/backend/app/ml/service.py`)
