# wiedehopf/readsb architecture

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

- Interactive diagram: https://gitdiagram.com/wiedehopf/readsb
- Repository: https://github.com/wiedehopf/readsb

## Overview

Readsb is an ADS-B/Mode-S receiver and tracking backend. Its principal workflow takes radio or network input, demodulates and decodes aircraft messages, updates tracked aircraft state, then exposes data through network feeds, JSON/API output, and optional globe history. The README documents feed modes and globe-history features; source excerpts and the index establish module ownership but do not show every runtime call, so uncertain links are dashed.

Main entry points: [`net_io.c`](https://github.com/wiedehopf/readsb/blob/dev/net_io.c) (Message Handling), [`readsb.c`](https://github.com/wiedehopf/readsb/blob/dev/readsb.c) (Readsb Runtime), [`mode_s.c`](https://github.com/wiedehopf/readsb/blob/dev/mode_s.c) (Mode S Decoder), [`track.c`](https://github.com/wiedehopf/readsb/blob/dev/track.c) (Position Tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Signal Ingestion"]
  node_main["Readsb Runtime<br/>[readsb.c]"]
  node_receiver["Receiver Control<br/>[receiver.c]"]
  node_sdr["SDR Drivers<br/>[sdr.c]"]
  node_sdr_backends["SDR Backends<br/>[sdr_rtlsdr.c]"]
  node_sample_convert["Sample Conversion<br/>[convert.c]"]
  node_net_input["Network Input<br/>[net_io.c]"]
end

subgraph group_decode["Message Decoding"]
  node_demod["Signal Demodulation<br/>[demod_2400.c]"]
  node_mode_s["Mode S Decoder<br/>[mode_s.c]"]
  node_mode_ac["Mode A/C Decoder<br/>[mode_ac.c]"]
  node_uat["UAT Decoder<br/>[uat_decode.c]"]
  node_comm_b["Comm-B Decode<br/>[comm_b.c]"]
  node_message_dispatch["Message Handling<br/>[net_io.c]"]
end

subgraph group_tracking["Aircraft Tracking"]
  node_aircraft["Aircraft Records<br/>[aircraft.c]"]
  node_track["Position Tracking<br/>[track.c]"]
  node_stats["Receiver Statistics<br/>[stats.c]"]
end

subgraph group_output["Data Outputs"]
  node_json["JSON Output<br/>[json_out.c]"]
  node_api["Readsb API<br/>[api.c]"]
  node_globe["Globe Index<br/>[globe_index.c]"]
  node_network_output["Network Feeds<br/>[net_io.c]"]
  node_trace["Trace History<br/>[track.c]"]
end

node_operator(("Operator / Receiver"))
node_clients(("Feed Consumers"))

node_operator -.->|"configures"| node_main
node_main -.->|"configures"| node_receiver
node_receiver -.->|"selects input"| node_sdr
node_sdr -.->|"dispatches to"| node_sdr_backends
node_sdr_backends -.->|"supplies samples"| node_sample_convert
node_sample_convert -.->|"converts samples"| node_demod
node_net_input -->|"passes messages"| node_message_dispatch
node_demod -.->|"decodes messages"| node_mode_s
node_mode_s -.->|"decodes fields"| node_comm_b
node_mode_s -.->|"submits messages"| node_message_dispatch
node_mode_ac -.->|"submits messages"| node_message_dispatch
node_uat -.->|"submits messages"| node_message_dispatch
node_message_dispatch -->|"gets or creates"| node_aircraft
node_aircraft -.->|"updates state"| node_track
node_main -.->|"updates statistics"| node_stats
node_track -.->|"writes aircraft data"| node_json
node_json -.->|"serves data"| node_api
node_json -.->|"builds index"| node_globe
node_track -.->|"records history"| node_trace
node_message_dispatch -.->|"forwards messages"| node_network_output
node_network_output -->|"sends feeds"| node_clients
node_api -->|"serves aircraft data"| node_clients

click node_main "https://github.com/wiedehopf/readsb/blob/dev/readsb.c"
click node_receiver "https://github.com/wiedehopf/readsb/blob/dev/receiver.c"
click node_sdr "https://github.com/wiedehopf/readsb/blob/dev/sdr.c"
click node_sdr_backends "https://github.com/wiedehopf/readsb/blob/dev/sdr_rtlsdr.c"
click node_sample_convert "https://github.com/wiedehopf/readsb/blob/dev/convert.c"
click node_demod "https://github.com/wiedehopf/readsb/blob/dev/demod_2400.c"
click node_net_input "https://github.com/wiedehopf/readsb/blob/dev/net_io.c"
click node_mode_s "https://github.com/wiedehopf/readsb/blob/dev/mode_s.c"
click node_mode_ac "https://github.com/wiedehopf/readsb/blob/dev/mode_ac.c"
click node_uat "https://github.com/wiedehopf/readsb/blob/dev/uat2esnt/uat_decode.c"
click node_comm_b "https://github.com/wiedehopf/readsb/blob/dev/comm_b.c"
click node_message_dispatch "https://github.com/wiedehopf/readsb/blob/dev/net_io.c"
click node_aircraft "https://github.com/wiedehopf/readsb/blob/dev/aircraft.c"
click node_track "https://github.com/wiedehopf/readsb/blob/dev/track.c"
click node_stats "https://github.com/wiedehopf/readsb/blob/dev/stats.c"
click node_json "https://github.com/wiedehopf/readsb/blob/dev/json_out.c"
click node_api "https://github.com/wiedehopf/readsb/blob/dev/api.c"
click node_globe "https://github.com/wiedehopf/readsb/blob/dev/globe_index.c"
click node_network_output "https://github.com/wiedehopf/readsb/blob/dev/net_io.c"
click node_trace "https://github.com/wiedehopf/readsb/blob/dev/track.c"

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_main,node_receiver,node_sdr,node_sdr_backends,node_sample_convert,node_net_input toneBlue
class node_demod,node_mode_s,node_mode_ac,node_uat,node_comm_b,node_message_dispatch toneAmber
class node_aircraft,node_track,node_stats toneMint
class node_json,node_api,node_globe,node_network_output,node_trace toneRose
class node_operator,node_clients toneIndigo
```

## Components

### Signal Ingestion

- [Readsb Runtime](https://github.com/wiedehopf/readsb/blob/dev/readsb.c): `readsb.c`
- [Receiver Control](https://github.com/wiedehopf/readsb/blob/dev/receiver.c): `receiver.c`
- [SDR Drivers](https://github.com/wiedehopf/readsb/blob/dev/sdr.c): `sdr.c`
- [SDR Backends](https://github.com/wiedehopf/readsb/blob/dev/sdr_rtlsdr.c): `sdr_rtlsdr.c`
- [Sample Conversion](https://github.com/wiedehopf/readsb/blob/dev/convert.c): `convert.c`
- [Network Input](https://github.com/wiedehopf/readsb/blob/dev/net_io.c): `net_io.c`

### Message Decoding

- [Signal Demodulation](https://github.com/wiedehopf/readsb/blob/dev/demod_2400.c): `demod_2400.c`
- [Mode S Decoder](https://github.com/wiedehopf/readsb/blob/dev/mode_s.c): `mode_s.c`
- [Mode A/C Decoder](https://github.com/wiedehopf/readsb/blob/dev/mode_ac.c): `mode_ac.c`
- [UAT Decoder](https://github.com/wiedehopf/readsb/blob/dev/uat2esnt/uat_decode.c): `uat2esnt/uat_decode.c`
- [Comm-B Decode](https://github.com/wiedehopf/readsb/blob/dev/comm_b.c): `comm_b.c`
- [Message Handling](https://github.com/wiedehopf/readsb/blob/dev/net_io.c): `net_io.c`

### Aircraft Tracking

- [Aircraft Records](https://github.com/wiedehopf/readsb/blob/dev/aircraft.c): `aircraft.c`
- [Position Tracking](https://github.com/wiedehopf/readsb/blob/dev/track.c): `track.c`
- [Receiver Statistics](https://github.com/wiedehopf/readsb/blob/dev/stats.c): `stats.c`

### Data Outputs

- [JSON Output](https://github.com/wiedehopf/readsb/blob/dev/json_out.c): `json_out.c`
- [Readsb API](https://github.com/wiedehopf/readsb/blob/dev/api.c): `api.c`
- [Globe Index](https://github.com/wiedehopf/readsb/blob/dev/globe_index.c): `globe_index.c`
- [Network Feeds](https://github.com/wiedehopf/readsb/blob/dev/net_io.c): `net_io.c`
- [Trace History](https://github.com/wiedehopf/readsb/blob/dev/track.c): `track.c`

### Other components

- **Operator / Receiver**
- **Feed Consumers**

## Connections

- Operator / Receiver → Readsb Runtime: configures
- Readsb Runtime → Receiver Control: configures
- Receiver Control → SDR Drivers: selects input
- SDR Drivers → SDR Backends: dispatches to
- SDR Backends → Sample Conversion: supplies samples
- Sample Conversion → Signal Demodulation: converts samples
- Network Input → Message Handling: passes messages (evidence: `net_io.c`)
- Signal Demodulation → Mode S Decoder: decodes messages
- Mode S Decoder → Comm-B Decode: decodes fields
- Mode S Decoder → Message Handling: submits messages
- Mode A/C Decoder → Message Handling: submits messages
- UAT Decoder → Message Handling: submits messages
- Message Handling → Aircraft Records: gets or creates (evidence: `net_io.c`)
- Aircraft Records → Position Tracking: updates state
- Readsb Runtime → Receiver Statistics: updates statistics
- Position Tracking → JSON Output: writes aircraft data
- JSON Output → Readsb API: serves data
- JSON Output → Globe Index: builds index
- Position Tracking → Trace History: records history (evidence: `track.c`)
- Message Handling → Network Feeds: forwards messages (evidence: `net_io.c`)
- Network Feeds → Feed Consumers: sends feeds
- Readsb API → Feed Consumers: serves aircraft data
