# w9ml/squelch architecture

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

- Interactive diagram: https://gitdiagram.com/w9ml/squelch
- Repository: https://github.com/w9ml/squelch

## Overview

Squelch is a self-hosted, receive-only AllStarLink monitor: node audio is segmented into transmissions, enriched with radio metadata and speech/voice analysis, persisted, then exposed through a live searchable web UI. The graph keeps the documented optional capabilities visible; links are limited to relationships supported by the README or supplied source excerpts/index references, so unsampled implementation details are not treated as inspected.

Main entry points: [`squelch/pipeline.py`](https://github.com/w9ml/squelch/blob/main/squelch/pipeline.py) (Transmission pipeline), [`squelch/web.py`](https://github.com/w9ml/squelch/blob/main/squelch/web.py) (FastAPI service), [`squelch/db.py`](https://github.com/w9ml/squelch/blob/main/squelch/db.py) (Transmission database), [`web/src/components/Feed.tsx`](https://github.com/w9ml/squelch/blob/main/web/src/components/Feed.tsx) (Live transmission feed)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Radio ingest"]
  node_usrp["USRP segmenter<br/>[usrp.py]"]
  node_forwarded_mdc["Node MDC forwarding<br/>[mdc_ingest.py]"]
  node_source_events["Node source events<br/>[source_ingest.py]"]
end

subgraph group_analysis["Transmission analysis"]
  node_pipeline["Transmission pipeline<br/>[pipeline.py]"]
  node_transcription["Speech transcription<br/>[transcribe.py]"]
  node_captions["Live captions<br/>[livecaption.py]"]
  node_mdc_decode["MDC audio decode<br/>[mdc1200.py]"]
  node_dtmf["DTMF decode<br/>[dtmf.py]"]
  node_speaker_id["Voice identification<br/>[speakerid.py]"]
  node_titanet["TitaNet backend<br/>[titanet.py]"]
  node_callsigns["Callsign extraction<br/>[callsigns.py]"]
  node_say_again["Callsign correction<br/>[qrz.py]"]
  node_watchlist["Watchlist matching<br/>[watchlist.py]"]
  node_voter["Voter RSSI<br/>[voter.py]"]
end

subgraph group_data["Persistence and events"]
  node_db[("Transmission database<br/>[db.py]")]
  node_events["Live event broadcaster<br/>[events.py]"]
end

subgraph group_service["Web services"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_web["FastAPI service<br/>[web.py]"]
  node_auth["Accounts and sessions<br/>[auth.py]"]
  node_push["Web push alerts<br/>[webpush.py]"]
  node_exports["Case and data exports<br/>[export.py]"]
end

subgraph group_ui["Browser experience"]
  node_feed["Live transmission feed<br/>[Feed.tsx]"]
  node_tx_card["Transmission cards"]
  node_waveform["Waveform playback<br/>[WaveformPlayer.tsx]"]
  node_api_client["Browser API client<br/>[api.ts]"]
  node_app_state["Browser application state<br/>[app-context.tsx]"]
  node_cases_ui["Case management UI<br/>[CasesModal.tsx]"]
  node_settings_ui["Admin settings UI<br/>[SettingsModal.tsx]"]
end

node_node(("AllStarLink node"))
node_browser(("Monitor user"))
node_external_qrz["QRZ service"]
node_push_targets["Browser or webhook targets"]

node_node -->|"streams audio"| node_usrp
node_usrp -->|"submits segments"| node_pipeline
node_pipeline -.->|"stores transmissions"| node_db
node_pipeline -->|"decodes MDC"| node_mdc_decode
node_pipeline -->|"decodes tones"| node_dtmf
node_pipeline -.->|"transcribes audio"| node_transcription
node_pipeline -->|"identifies voice"| node_speaker_id
node_speaker_id -->|"uses backend"| node_titanet
node_pipeline -->|"extracts callsigns"| node_callsigns
node_pipeline -->|"checks callsigns"| node_say_again
node_say_again -.->|"enriches stations"| node_external_qrz
node_pipeline -->|"matches alerts"| node_watchlist
node_pipeline -->|"sends alerts"| node_push
node_push -->|"delivers notices"| node_push_targets
node_node -->|"forwards MDC"| node_forwarded_mdc
node_forwarded_mdc -->|"attaches identifiers"| node_db
node_node -->|"reports audio origin"| node_source_events
node_source_events -->|"updates origin"| node_db
node_pipeline -->|"publishes updates"| node_events
node_events -.->|"broadcasts feed"| node_web
node_web -->|"reads and writes"| node_db
node_web -->|"checks access"| node_auth
node_auth -->|"stores accounts"| node_db
node_web -.->|"serves case exports"| node_exports
node_web -.->|"uses settings"| node_config
node_browser -->|"views transmissions"| node_feed
node_feed -->|"reads state"| node_app_state
node_feed -->|"renders cards"| node_tx_card
node_tx_card -->|"renders playback"| node_waveform
node_feed -.->|"loads feed"| node_api_client
node_api_client -.->|"calls API"| node_web
node_browser -->|"manages cases"| node_cases_ui
node_cases_ui -.->|"requests case actions"| node_api_client
node_browser -->|"changes settings"| node_settings_ui
node_settings_ui -.->|"submits settings"| node_api_client
node_voter -.->|"provides RSSI context"| node_pipeline
node_captions -.->|"streams provisional text"| node_browser

click node_usrp "https://github.com/w9ml/squelch/blob/main/squelch/usrp.py"
click node_forwarded_mdc "https://github.com/w9ml/squelch/blob/main/squelch/mdc_ingest.py"
click node_source_events "https://github.com/w9ml/squelch/blob/main/squelch/source_ingest.py"
click node_pipeline "https://github.com/w9ml/squelch/blob/main/squelch/pipeline.py"
click node_transcription "https://github.com/w9ml/squelch/blob/main/squelch/transcribe.py"
click node_captions "https://github.com/w9ml/squelch/blob/main/squelch/livecaption.py"
click node_mdc_decode "https://github.com/w9ml/squelch/blob/main/squelch/mdc1200.py"
click node_dtmf "https://github.com/w9ml/squelch/blob/main/squelch/dtmf.py"
click node_speaker_id "https://github.com/w9ml/squelch/blob/main/squelch/speakerid.py"
click node_titanet "https://github.com/w9ml/squelch/blob/main/squelch/titanet.py"
click node_callsigns "https://github.com/w9ml/squelch/blob/main/squelch/callsigns.py"
click node_say_again "https://github.com/w9ml/squelch/blob/main/squelch/qrz.py"
click node_watchlist "https://github.com/w9ml/squelch/blob/main/squelch/watchlist.py"
click node_voter "https://github.com/w9ml/squelch/blob/main/squelch/voter.py"
click node_db "https://github.com/w9ml/squelch/blob/main/squelch/db.py"
click node_events "https://github.com/w9ml/squelch/blob/main/squelch/events.py"
click node_config "https://github.com/w9ml/squelch/blob/main/squelch/config.py"
click node_web "https://github.com/w9ml/squelch/blob/main/squelch/web.py"
click node_auth "https://github.com/w9ml/squelch/blob/main/squelch/auth.py"
click node_push "https://github.com/w9ml/squelch/blob/main/squelch/webpush.py"
click node_exports "https://github.com/w9ml/squelch/blob/main/squelch/export.py"
click node_feed "https://github.com/w9ml/squelch/blob/main/web/src/components/Feed.tsx"
click node_tx_card "https://github.com/w9ml/squelch/blob/main/web/src/components/TransmissionCard.tsx"
click node_waveform "https://github.com/w9ml/squelch/blob/main/web/src/components/WaveformPlayer.tsx"
click node_api_client "https://github.com/w9ml/squelch/blob/main/web/src/lib/api.ts"
click node_app_state "https://github.com/w9ml/squelch/blob/main/web/src/state/app-context.tsx"
click node_cases_ui "https://github.com/w9ml/squelch/blob/main/web/src/components/modals/CasesModal.tsx"
click node_settings_ui "https://github.com/w9ml/squelch/blob/main/web/src/components/modals/SettingsModal.tsx"

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_usrp,node_forwarded_mdc,node_source_events,node_browser,node_push_targets toneBlue
class node_pipeline,node_transcription,node_captions,node_mdc_decode,node_dtmf,node_speaker_id,node_titanet,node_callsigns,node_say_again,node_watchlist,node_voter toneAmber
class node_db,node_events toneMint
class node_config,node_web,node_auth,node_push,node_exports toneRose
class node_feed,node_tx_card,node_waveform,node_api_client,node_app_state,node_cases_ui,node_settings_ui,node_node,node_external_qrz toneIndigo
```

## Components

### Radio ingest

- [USRP segmenter](https://github.com/w9ml/squelch/blob/main/squelch/usrp.py): `squelch/usrp.py`
- [Node MDC forwarding](https://github.com/w9ml/squelch/blob/main/squelch/mdc_ingest.py): `squelch/mdc_ingest.py`
- [Node source events](https://github.com/w9ml/squelch/blob/main/squelch/source_ingest.py): `squelch/source_ingest.py`

### Transmission analysis

- [Transmission pipeline](https://github.com/w9ml/squelch/blob/main/squelch/pipeline.py): `squelch/pipeline.py`
- [Speech transcription](https://github.com/w9ml/squelch/blob/main/squelch/transcribe.py): `squelch/transcribe.py`
- [Live captions](https://github.com/w9ml/squelch/blob/main/squelch/livecaption.py): `squelch/livecaption.py`
- [MDC audio decode](https://github.com/w9ml/squelch/blob/main/squelch/mdc1200.py): `squelch/mdc1200.py`
- [DTMF decode](https://github.com/w9ml/squelch/blob/main/squelch/dtmf.py): `squelch/dtmf.py`
- [Voice identification](https://github.com/w9ml/squelch/blob/main/squelch/speakerid.py): `squelch/speakerid.py`
- [TitaNet backend](https://github.com/w9ml/squelch/blob/main/squelch/titanet.py): `squelch/titanet.py`
- [Callsign extraction](https://github.com/w9ml/squelch/blob/main/squelch/callsigns.py): `squelch/callsigns.py`
- [Callsign correction](https://github.com/w9ml/squelch/blob/main/squelch/qrz.py): `squelch/qrz.py`
- [Watchlist matching](https://github.com/w9ml/squelch/blob/main/squelch/watchlist.py): `squelch/watchlist.py`
- [Voter RSSI](https://github.com/w9ml/squelch/blob/main/squelch/voter.py): `squelch/voter.py`

### Persistence and events

- [Transmission database](https://github.com/w9ml/squelch/blob/main/squelch/db.py): `squelch/db.py`
- [Live event broadcaster](https://github.com/w9ml/squelch/blob/main/squelch/events.py): `squelch/events.py`

### Web services

- [Runtime configuration](https://github.com/w9ml/squelch/blob/main/squelch/config.py): `squelch/config.py`
- [FastAPI service](https://github.com/w9ml/squelch/blob/main/squelch/web.py): `squelch/web.py`
- [Accounts and sessions](https://github.com/w9ml/squelch/blob/main/squelch/auth.py): `squelch/auth.py`
- [Web push alerts](https://github.com/w9ml/squelch/blob/main/squelch/webpush.py): `squelch/webpush.py`
- [Case and data exports](https://github.com/w9ml/squelch/blob/main/squelch/export.py): `squelch/export.py`

### Browser experience

- [Live transmission feed](https://github.com/w9ml/squelch/blob/main/web/src/components/Feed.tsx): `web/src/components/Feed.tsx`
- [Transmission cards](https://github.com/w9ml/squelch/blob/main/web/src/components/TransmissionCard.tsx): `web/src/components/TransmissionCard.tsx`
- [Waveform playback](https://github.com/w9ml/squelch/blob/main/web/src/components/WaveformPlayer.tsx): `web/src/components/WaveformPlayer.tsx`
- [Browser API client](https://github.com/w9ml/squelch/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Browser application state](https://github.com/w9ml/squelch/blob/main/web/src/state/app-context.tsx): `web/src/state/app-context.tsx`
- [Case management UI](https://github.com/w9ml/squelch/blob/main/web/src/components/modals/CasesModal.tsx): `web/src/components/modals/CasesModal.tsx`
- [Admin settings UI](https://github.com/w9ml/squelch/blob/main/web/src/components/modals/SettingsModal.tsx): `web/src/components/modals/SettingsModal.tsx`

### Other components

- **AllStarLink node**
- **Monitor user**
- **QRZ service**
- **Browser or webhook targets**

## Connections

- AllStarLink node → USRP segmenter: streams audio
- USRP segmenter → Transmission pipeline: submits segments (evidence: `squelch/pipeline.py`)
- Transmission pipeline → Transmission database: stores transmissions (evidence: `squelch/pipeline.py`)
- Transmission pipeline → MDC audio decode: decodes MDC (evidence: `squelch/pipeline.py`)
- Transmission pipeline → DTMF decode: decodes tones (evidence: `squelch/pipeline.py`)
- Transmission pipeline → Speech transcription: transcribes audio (evidence: `squelch/pipeline.py`)
- Transmission pipeline → Voice identification: identifies voice (evidence: `squelch/pipeline.py`)
- Voice identification → TitaNet backend: uses backend (evidence: `squelch/speakerid.py`)
- Transmission pipeline → Callsign extraction: extracts callsigns (evidence: `squelch/pipeline.py`)
- Transmission pipeline → Callsign correction: checks callsigns (evidence: `squelch/pipeline.py`)
- Callsign correction → QRZ service: enriches stations
- Transmission pipeline → Watchlist matching: matches alerts (evidence: `squelch/pipeline.py`)
- Transmission pipeline → Web push alerts: sends alerts (evidence: `squelch/pipeline.py`)
- Web push alerts → Browser or webhook targets: delivers notices
- AllStarLink node → Node MDC forwarding: forwards MDC (evidence: `squelch/mdc_ingest.py`)
- Node MDC forwarding → Transmission database: attaches identifiers (evidence: `squelch/mdc_ingest.py`)
- AllStarLink node → Node source events: reports audio origin (evidence: `squelch/source_ingest.py`)
- Node source events → Transmission database: updates origin (evidence: `squelch/source_ingest.py`)
- Transmission pipeline → Live event broadcaster: publishes updates (evidence: `squelch/pipeline.py`)
- Live event broadcaster → FastAPI service: broadcasts feed (evidence: `squelch/web.py`)
- FastAPI service → Transmission database: reads and writes (evidence: `squelch/web.py`)
- FastAPI service → Accounts and sessions: checks access (evidence: `squelch/web.py`)
- Accounts and sessions → Transmission database: stores accounts (evidence: `squelch/auth.py`)
- FastAPI service → Case and data exports: serves case exports (evidence: `squelch/web.py`)
- FastAPI service → Runtime configuration: uses settings (evidence: `squelch/web.py`)
- Monitor user → Live transmission feed: views transmissions
- Live transmission feed → Browser application state: reads state (evidence: `web/src/components/Feed.tsx`)
- Live transmission feed → Transmission cards: renders cards (evidence: `web/src/components/Feed.tsx`)
- Transmission cards → Waveform playback: renders playback (evidence: `web/src/components/TransmissionCard.tsx`)
- Live transmission feed → Browser API client: loads feed
- Browser API client → FastAPI service: calls API
- Monitor user → Case management UI: manages cases
- Case management UI → Browser API client: requests case actions
- Monitor user → Admin settings UI: changes settings
- Admin settings UI → Browser API client: submits settings
- Voter RSSI → Transmission pipeline: provides RSSI context (evidence: `squelch/pipeline.py`)
- Live captions → Monitor user: streams provisional text
