# adsbexchange/readsb architecture

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

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

## Overview

Readsb is an ADS-B/Mode-S receiver and aircraft-data backend. Its main user-facing flow is to obtain radio or network input, decode messages, maintain aircraft state, then expose or forward results. The README also documents Beast push/receive connections, BeastReduce forwarding, JSON-oriented aircraft output, heatmap generation, and interactive display. The source index identifies the relevant modules, but most runtime call paths were not excerpted, so several architectural links are shown as unverified rather than asserted as source-confirmed calls.

Main entry points: [`readsb.c`](https://github.com/adsbexchange/readsb/blob/master/readsb.c) (Readsb runtime), [`receiver.c`](https://github.com/adsbexchange/readsb/blob/master/receiver.c) (Receiver pipeline), [`aircraft.c`](https://github.com/adsbexchange/readsb/blob/master/aircraft.c) (Aircraft records), [`mode_s.c`](https://github.com/adsbexchange/readsb/blob/master/mode_s.c) (Mode S decode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Input and decoding"]
  node_receiver["Receiver pipeline<br/>[receiver.c]"]
  node_sdr["SDR backends<br/>[sdr.c]"]
  node_beast_sdr["Beast / file input<br/>[sdr_beast.c]"]
  node_mode_s["Mode S decode<br/>[mode_s.c]"]
  node_uat["UAT decode<br/>[uat_decode.c]"]
  node_commb["Comm-B decode<br/>[comm_b.c]"]
  node_crc["CRC correction<br/>[crc.c]"]
end

subgraph group_state["Aircraft state"]
  node_aircraft[("Aircraft records<br/>[aircraft.c]")]
  node_tracking["Position tracking<br/>[track.c]"]
end

subgraph group_outputs["Outputs and history"]
  node_network["Network services<br/>[net_io.c]"]
  node_json["JSON output<br/>[json_out.c]"]
  node_api["API output<br/>[api.c]"]
  node_globe[("Globe history<br/>[globe_index.c]")]
  node_lzo["LZO compression<br/>[minilzo.c]"]
end

subgraph group_operations["Runtime operations"]
  node_readsb["Readsb runtime<br/>[readsb.c]"]
  node_stats["Statistics<br/>[stats.c]"]
  node_interactive["Interactive display<br/>[interactive.c]"]
end

node_operator(("Operator"))
node_sdr_device(("SDR hardware"))
node_beast_peer(("Beast peer"))

node_operator -->|"runs"| node_readsb
node_sdr_device -.->|"supplies samples"| node_sdr
node_readsb -.->|"starts pipeline"| node_receiver
node_receiver -.->|"reads samples"| node_sdr
node_receiver -.->|"demodulates"| node_mode_s
node_receiver -.->|"demodulates"| node_uat
node_mode_s -.->|"checks messages"| node_crc
node_mode_s -.->|"decodes Comm-B"| node_commb
node_network -->|"creates or gets"| node_aircraft
node_tracking -.->|"updates state"| node_aircraft
node_readsb -.->|"configures connections"| node_network
node_beast_peer -->|"exchanges Beast"| node_network
node_aircraft -.->|"emits aircraft data"| node_json
node_readsb -.->|"serves data"| node_api
node_aircraft -.->|"records history"| node_globe
node_readsb -.->|"updates statistics"| node_stats
node_readsb -.->|"refreshes display"| node_interactive
node_globe -.->|"compresses output"| node_lzo

click node_readsb "https://github.com/adsbexchange/readsb/blob/master/readsb.c"
click node_receiver "https://github.com/adsbexchange/readsb/blob/master/receiver.c"
click node_sdr "https://github.com/adsbexchange/readsb/blob/master/sdr.c"
click node_beast_sdr "https://github.com/adsbexchange/readsb/blob/master/sdr_beast.c"
click node_mode_s "https://github.com/adsbexchange/readsb/blob/master/mode_s.c"
click node_uat "https://github.com/adsbexchange/readsb/blob/master/uat2esnt/uat_decode.c"
click node_commb "https://github.com/adsbexchange/readsb/blob/master/comm_b.c"
click node_crc "https://github.com/adsbexchange/readsb/blob/master/crc.c"
click node_aircraft "https://github.com/adsbexchange/readsb/blob/master/aircraft.c"
click node_tracking "https://github.com/adsbexchange/readsb/blob/master/track.c"
click node_network "https://github.com/adsbexchange/readsb/blob/master/net_io.c"
click node_json "https://github.com/adsbexchange/readsb/blob/master/json_out.c"
click node_api "https://github.com/adsbexchange/readsb/blob/master/api.c"
click node_globe "https://github.com/adsbexchange/readsb/blob/master/globe_index.c"
click node_stats "https://github.com/adsbexchange/readsb/blob/master/stats.c"
click node_interactive "https://github.com/adsbexchange/readsb/blob/master/interactive.c"
click node_lzo "https://github.com/adsbexchange/readsb/blob/master/minilzo/minilzo.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_receiver,node_sdr,node_beast_sdr,node_mode_s,node_uat,node_commb,node_crc toneBlue
class node_aircraft,node_tracking toneAmber
class node_network,node_json,node_api,node_globe,node_lzo toneMint
class node_readsb,node_stats,node_interactive toneRose
class node_operator,node_sdr_device,node_beast_peer toneIndigo
```

## Components

### Input and decoding

- [Receiver pipeline](https://github.com/adsbexchange/readsb/blob/master/receiver.c): `receiver.c`
- [SDR backends](https://github.com/adsbexchange/readsb/blob/master/sdr.c): `sdr.c`
- [Beast / file input](https://github.com/adsbexchange/readsb/blob/master/sdr_beast.c): `sdr_beast.c`
- [Mode S decode](https://github.com/adsbexchange/readsb/blob/master/mode_s.c): `mode_s.c`
- [UAT decode](https://github.com/adsbexchange/readsb/blob/master/uat2esnt/uat_decode.c): `uat2esnt/uat_decode.c`
- [Comm-B decode](https://github.com/adsbexchange/readsb/blob/master/comm_b.c): `comm_b.c`
- [CRC correction](https://github.com/adsbexchange/readsb/blob/master/crc.c): `crc.c`

### Aircraft state

- [Aircraft records](https://github.com/adsbexchange/readsb/blob/master/aircraft.c): `aircraft.c`
- [Position tracking](https://github.com/adsbexchange/readsb/blob/master/track.c): `track.c`

### Outputs and history

- [Network services](https://github.com/adsbexchange/readsb/blob/master/net_io.c): `net_io.c`
- [JSON output](https://github.com/adsbexchange/readsb/blob/master/json_out.c): `json_out.c`
- [API output](https://github.com/adsbexchange/readsb/blob/master/api.c): `api.c`
- [Globe history](https://github.com/adsbexchange/readsb/blob/master/globe_index.c): `globe_index.c`
- [LZO compression](https://github.com/adsbexchange/readsb/blob/master/minilzo/minilzo.c): `minilzo/minilzo.c`

### Runtime operations

- [Readsb runtime](https://github.com/adsbexchange/readsb/blob/master/readsb.c): `readsb.c`
- [Statistics](https://github.com/adsbexchange/readsb/blob/master/stats.c): `stats.c`
- [Interactive display](https://github.com/adsbexchange/readsb/blob/master/interactive.c): `interactive.c`

### Other components

- **Operator**
- **SDR hardware**
- **Beast peer**

## Connections

- Operator → Readsb runtime: runs
- SDR hardware → SDR backends: supplies samples
- Readsb runtime → Receiver pipeline: starts pipeline
- Receiver pipeline → SDR backends: reads samples
- Receiver pipeline → Mode S decode: demodulates
- Receiver pipeline → UAT decode: demodulates
- Mode S decode → CRC correction: checks messages
- Mode S decode → Comm-B decode: decodes Comm-B
- Network services → Aircraft records: creates or gets (evidence: `net_io.c`)
- Position tracking → Aircraft records: updates state
- Readsb runtime → Network services: configures connections
- Beast peer → Network services: exchanges Beast
- Aircraft records → JSON output: emits aircraft data
- Readsb runtime → API output: serves data
- Aircraft records → Globe history: records history
- Readsb runtime → Statistics: updates statistics
- Readsb runtime → Interactive display: refreshes display
- Globe history → LZO compression: compresses output