# xoolive/traffic architecture

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

- Interactive diagram: https://gitdiagram.com/xoolive/traffic
- Repository: https://github.com/xoolive/traffic

## Overview

traffic is a Python toolbox for accessing, processing, analyzing, and visualizing air-traffic trajectories and airspaces. The main user workflow is to obtain traffic or reference data, work with it through the library’s trajectory/domain objects and analysis algorithms, then visualize or export results. The graph preserves major documented source families, analytical capabilities, and visualization alongside the central runtime layers. Relationships are limited to README statements and SOURCE INDEX references; unsampled modules are represented at subsystem level where their exact implementation path is not evidenced.

Main entry points: [`src/traffic/data/__init__.py`](https://github.com/xoolive/traffic/blob/master/src/traffic/data/__init__.py) (Data access facade), [`src/traffic/core/traffic.py`](https://github.com/xoolive/traffic/blob/master/src/traffic/core/traffic.py) (Traffic collection), [`src/traffic/core/flight.py`](https://github.com/xoolive/traffic/blob/master/src/traffic/core/flight.py) (Flight trajectory), [`src/traffic/core/structure.py`](https://github.com/xoolive/traffic/blob/master/src/traffic/core/structure.py) (Domain structures)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Data access"]
  node_data_facade["Data access facade<br/>[__init__.py]"]
  node_opensky["OpenSky access<br/>[opensky.py]"]
  node_adsb_decode["ADS-B decoding<br/>[decode.py]"]
  node_eurocontrol["Eurocontrol sources"]
  node_datasets["Open datasets"]
end

subgraph group_domain["Air traffic model"]
  node_traffic_obj["Traffic collection<br/>[traffic.py]"]
  node_flight_obj["Flight trajectory<br/>[flight.py]"]
  node_airspace_obj["Airspace model<br/>[airspace.py]"]
  node_flightplan_obj["Flight plan<br/>[flightplan.py]"]
  node_statevectors["State vectors<br/>[sv.py]"]
  node_time_intervals["Time intervals<br/>[intervals.py]"]
  node_shared_ops["Shared data operations<br/>[mixins.py]"]
  node_data_structures["Domain structures<br/>[structure.py]"]
end

subgraph group_analysis["Trajectory analysis"]
  node_filters["Trajectory filters"]
  node_navigation["Flight phases"]
  node_prediction["Trajectory prediction"]
  node_performance["Aircraft performance<br/>[openap.py]"]
  node_ground["Ground movement"]
end

subgraph group_reference["Reference data"]
  node_airport_data["Airport reference<br/>[airports.py]"]
  node_aircraft_data["Aircraft reference<br/>[aircraft.py]"]
  node_airways_data["Airway reference<br/>[airways.py]"]
  node_navaids_data["Navaid reference<br/>[navaid.py]"]
  node_runways_data["Runway reference<br/>[runways.py]"]
end

subgraph group_output["Visualization"]
  node_leaflet["Interactive maps<br/>[leaflet.py]"]
  node_other_viz["Other visual exports"]
end

node_user(("Analyst"))
node_opensky_service{{"OpenSky Network"}}

node_user -->|"analyzes"| node_traffic_obj
node_user -->|"accesses data"| node_data_facade
node_data_facade -->|"provides access"| node_opensky
node_data_facade -->|"provides access"| node_adsb_decode
node_data_facade -->|"provides access"| node_eurocontrol
node_data_facade -.->|"provides access"| node_datasets
node_opensky -->|"requests data"| node_opensky_service
node_opensky -->|"uses decoder"| node_adsb_decode
node_data_facade -->|"loads reference"| node_airport_data
node_data_facade -->|"loads reference"| node_aircraft_data
node_data_facade -->|"loads reference"| node_airways_data
node_data_facade -->|"loads reference"| node_navaids_data
node_data_facade -->|"loads reference"| node_runways_data
node_traffic_obj -->|"uses trajectories"| node_flight_obj
node_traffic_obj -->|"uses airspaces"| node_airspace_obj
node_traffic_obj -->|"uses plans"| node_flightplan_obj
node_traffic_obj -->|"uses vectors"| node_statevectors
node_traffic_obj -->|"uses intervals"| node_time_intervals
node_traffic_obj -->|"dispatches filters"| node_filters
node_traffic_obj -->|"renders maps"| node_leaflet
node_traffic_obj -->|"renders plots"| node_other_viz
node_flight_obj -->|"applies filters"| node_filters
node_flight_obj -->|"exposes phases"| node_navigation
node_flight_obj -->|"exposes prediction"| node_prediction
node_flight_obj -->|"uses performance"| node_performance
node_flight_obj -->|"uses operations"| node_shared_ops
node_flightplan_obj -->|"resolves navaids"| node_navaids_data
node_data_structures -->|"uses runway data"| node_runways_data
node_airport_data -->|"uses structures"| node_data_structures
node_airways_data -->|"uses structures"| node_data_structures
node_navaids_data -->|"uses structures"| node_data_structures
node_eurocontrol -->|"builds routes"| node_airways_data
node_eurocontrol -->|"joins navaids"| node_navaids_data
node_flight_obj -->|"renders trajectory"| node_leaflet
node_user -->|"views results"| node_leaflet

click node_data_facade "https://github.com/xoolive/traffic/blob/master/src/traffic/data/__init__.py"
click node_opensky "https://github.com/xoolive/traffic/blob/master/src/traffic/data/adsb/opensky.py"
click node_adsb_decode "https://github.com/xoolive/traffic/blob/master/src/traffic/data/adsb/decode.py"
click node_eurocontrol "https://github.com/xoolive/traffic/tree/master/src/traffic/data/eurocontrol"
click node_datasets "https://github.com/xoolive/traffic/tree/master/src/traffic/data/datasets"
click node_traffic_obj "https://github.com/xoolive/traffic/blob/master/src/traffic/core/traffic.py"
click node_flight_obj "https://github.com/xoolive/traffic/blob/master/src/traffic/core/flight.py"
click node_airspace_obj "https://github.com/xoolive/traffic/blob/master/src/traffic/core/airspace.py"
click node_flightplan_obj "https://github.com/xoolive/traffic/blob/master/src/traffic/core/flightplan.py"
click node_statevectors "https://github.com/xoolive/traffic/blob/master/src/traffic/core/sv.py"
click node_time_intervals "https://github.com/xoolive/traffic/blob/master/src/traffic/core/intervals.py"
click node_shared_ops "https://github.com/xoolive/traffic/blob/master/src/traffic/core/mixins.py"
click node_data_structures "https://github.com/xoolive/traffic/blob/master/src/traffic/core/structure.py"
click node_filters "https://github.com/xoolive/traffic/tree/master/src/traffic/algorithms/filters"
click node_navigation "https://github.com/xoolive/traffic/tree/master/src/traffic/algorithms/navigation"
click node_prediction "https://github.com/xoolive/traffic/tree/master/src/traffic/algorithms/prediction"
click node_performance "https://github.com/xoolive/traffic/blob/master/src/traffic/algorithms/performance/openap.py"
click node_ground "https://github.com/xoolive/traffic/tree/master/src/traffic/algorithms/ground"
click node_airport_data "https://github.com/xoolive/traffic/blob/master/src/traffic/data/basic/airports.py"
click node_aircraft_data "https://github.com/xoolive/traffic/blob/master/src/traffic/data/basic/aircraft.py"
click node_airways_data "https://github.com/xoolive/traffic/blob/master/src/traffic/data/basic/airways.py"
click node_navaids_data "https://github.com/xoolive/traffic/blob/master/src/traffic/data/basic/navaid.py"
click node_runways_data "https://github.com/xoolive/traffic/blob/master/src/traffic/data/basic/runways.py"
click node_leaflet "https://github.com/xoolive/traffic/blob/master/src/traffic/visualize/leaflet.py"
click node_other_viz "https://github.com/xoolive/traffic/tree/master/src/traffic/visualize"

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_data_facade,node_opensky,node_adsb_decode,node_eurocontrol,node_datasets toneBlue
class node_traffic_obj,node_flight_obj,node_airspace_obj,node_flightplan_obj,node_statevectors,node_time_intervals,node_shared_ops,node_data_structures toneAmber
class node_filters,node_navigation,node_prediction,node_performance,node_ground toneMint
class node_airport_data,node_aircraft_data,node_airways_data,node_navaids_data,node_runways_data toneRose
class node_leaflet,node_other_viz,node_user,node_opensky_service toneIndigo
```

## Components

### Data access

- [Data access facade](https://github.com/xoolive/traffic/blob/master/src/traffic/data/__init__.py): `src/traffic/data/__init__.py`
- [OpenSky access](https://github.com/xoolive/traffic/blob/master/src/traffic/data/adsb/opensky.py): `src/traffic/data/adsb/opensky.py`
- [ADS-B decoding](https://github.com/xoolive/traffic/blob/master/src/traffic/data/adsb/decode.py): `src/traffic/data/adsb/decode.py`
- [Eurocontrol sources](https://github.com/xoolive/traffic/tree/master/src/traffic/data/eurocontrol): `src/traffic/data/eurocontrol`
- [Open datasets](https://github.com/xoolive/traffic/tree/master/src/traffic/data/datasets): `src/traffic/data/datasets`

### Air traffic model

- [Traffic collection](https://github.com/xoolive/traffic/blob/master/src/traffic/core/traffic.py): `src/traffic/core/traffic.py`
- [Flight trajectory](https://github.com/xoolive/traffic/blob/master/src/traffic/core/flight.py): `src/traffic/core/flight.py`
- [Airspace model](https://github.com/xoolive/traffic/blob/master/src/traffic/core/airspace.py): `src/traffic/core/airspace.py`
- [Flight plan](https://github.com/xoolive/traffic/blob/master/src/traffic/core/flightplan.py): `src/traffic/core/flightplan.py`
- [State vectors](https://github.com/xoolive/traffic/blob/master/src/traffic/core/sv.py): `src/traffic/core/sv.py`
- [Time intervals](https://github.com/xoolive/traffic/blob/master/src/traffic/core/intervals.py): `src/traffic/core/intervals.py`
- [Shared data operations](https://github.com/xoolive/traffic/blob/master/src/traffic/core/mixins.py): `src/traffic/core/mixins.py`
- [Domain structures](https://github.com/xoolive/traffic/blob/master/src/traffic/core/structure.py): `src/traffic/core/structure.py`

### Trajectory analysis

- [Trajectory filters](https://github.com/xoolive/traffic/tree/master/src/traffic/algorithms/filters): `src/traffic/algorithms/filters`
- [Flight phases](https://github.com/xoolive/traffic/tree/master/src/traffic/algorithms/navigation): `src/traffic/algorithms/navigation`
- [Trajectory prediction](https://github.com/xoolive/traffic/tree/master/src/traffic/algorithms/prediction): `src/traffic/algorithms/prediction`
- [Aircraft performance](https://github.com/xoolive/traffic/blob/master/src/traffic/algorithms/performance/openap.py): `src/traffic/algorithms/performance/openap.py`
- [Ground movement](https://github.com/xoolive/traffic/tree/master/src/traffic/algorithms/ground): `src/traffic/algorithms/ground`

### Reference data

- [Airport reference](https://github.com/xoolive/traffic/blob/master/src/traffic/data/basic/airports.py): `src/traffic/data/basic/airports.py`
- [Aircraft reference](https://github.com/xoolive/traffic/blob/master/src/traffic/data/basic/aircraft.py): `src/traffic/data/basic/aircraft.py`
- [Airway reference](https://github.com/xoolive/traffic/blob/master/src/traffic/data/basic/airways.py): `src/traffic/data/basic/airways.py`
- [Navaid reference](https://github.com/xoolive/traffic/blob/master/src/traffic/data/basic/navaid.py): `src/traffic/data/basic/navaid.py`
- [Runway reference](https://github.com/xoolive/traffic/blob/master/src/traffic/data/basic/runways.py): `src/traffic/data/basic/runways.py`

### Visualization

- [Interactive maps](https://github.com/xoolive/traffic/blob/master/src/traffic/visualize/leaflet.py): `src/traffic/visualize/leaflet.py`
- [Other visual exports](https://github.com/xoolive/traffic/tree/master/src/traffic/visualize): `src/traffic/visualize`

### Other components

- **Analyst**
- **OpenSky Network**

## Connections

- Analyst → Traffic collection: analyzes
- Analyst → Data access facade: accesses data
- Data access facade → OpenSky access: provides access (evidence: `src/traffic/data/__init__.py`)
- Data access facade → ADS-B decoding: provides access (evidence: `src/traffic/data/__init__.py`)
- Data access facade → Eurocontrol sources: provides access (evidence: `src/traffic/data/__init__.py`)
- Data access facade → Open datasets: provides access
- OpenSky access → OpenSky Network: requests data (evidence: `src/traffic/data/adsb/opensky.py`)
- OpenSky access → ADS-B decoding: uses decoder (evidence: `src/traffic/data/adsb/opensky.py`)
- Data access facade → Airport reference: loads reference (evidence: `src/traffic/data/__init__.py`)
- Data access facade → Aircraft reference: loads reference (evidence: `src/traffic/data/__init__.py`)
- Data access facade → Airway reference: loads reference (evidence: `src/traffic/data/__init__.py`)
- Data access facade → Navaid reference: loads reference (evidence: `src/traffic/data/__init__.py`)
- Data access facade → Runway reference: loads reference (evidence: `src/traffic/data/__init__.py`)
- Traffic collection → Flight trajectory: uses trajectories (evidence: `src/traffic/core/traffic.py`)
- Traffic collection → Airspace model: uses airspaces (evidence: `src/traffic/core/traffic.py`)
- Traffic collection → Flight plan: uses plans (evidence: `src/traffic/core/traffic.py`)
- Traffic collection → State vectors: uses vectors (evidence: `src/traffic/core/traffic.py`)
- Traffic collection → Time intervals: uses intervals (evidence: `src/traffic/core/traffic.py`)
- Traffic collection → Trajectory filters: dispatches filters (evidence: `src/traffic/core/traffic.py`)
- Traffic collection → Interactive maps: renders maps (evidence: `src/traffic/core/traffic.py`)
- Traffic collection → Other visual exports: renders plots (evidence: `src/traffic/core/traffic.py`)
- Flight trajectory → Trajectory filters: applies filters (evidence: `src/traffic/core/flight.py`)
- Flight trajectory → Flight phases: exposes phases (evidence: `src/traffic/core/flight.py`)
- Flight trajectory → Trajectory prediction: exposes prediction (evidence: `src/traffic/core/flight.py`)
- Flight trajectory → Aircraft performance: uses performance (evidence: `src/traffic/core/flight.py`)
- Flight trajectory → Shared data operations: uses operations (evidence: `src/traffic/core/flight.py`)
- Flight plan → Navaid reference: resolves navaids
- Domain structures → Runway reference: uses runway data (evidence: `src/traffic/core/structure.py`)
- Airport reference → Domain structures: uses structures (evidence: `src/traffic/data/basic/airports.py`)
- Airway reference → Domain structures: uses structures (evidence: `src/traffic/data/basic/airways.py`)
- Navaid reference → Domain structures: uses structures (evidence: `src/traffic/data/basic/navaid.py`)
- Eurocontrol sources → Airway reference: builds routes (evidence: `src/traffic/data/eurocontrol/aixm/routes.py`)
- Eurocontrol sources → Navaid reference: joins navaids (evidence: `src/traffic/data/eurocontrol/ddr/routes.py`)
- Flight trajectory → Interactive maps: renders trajectory (evidence: `src/traffic/visualize/leaflet.py`)
- Analyst → Interactive maps: views results
