# altunsumerve/vlf-noise-scout architecture

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

- Interactive diagram: https://gitdiagram.com/altunsumerve/vlf-noise-scout
- Repository: https://github.com/altunsumerve/vlf-noise-scout

## Overview

VLF Noise Scout is a dual-channel natural-radio receiver and live listening station. Its main workflow takes antenna and reference-probe audio through capture and adaptive noise cancellation, then exposes raw and cleaned MP3 streams to the web interface. The interface also provides a waterfall, recent-audio recording, a lightning map and transmitter results; separate command-line tools diagnose the capture chain and scan known transmitters. The live stream ended in August 2026. Backend flow is supported by sampled source; several interface features and integrations are documented or named in excerpts, but their full implementations were not sampled.

Main entry points: [`web/app.js`](https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js) (Station interface), [`server/vlf_stream/server.py`](https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/server.py) (HTTP server), [`server/vlf_stream/audio.py`](https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/audio.py) (Audio pipeline), [`server/vlf_stream/transmitters.py`](https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/transmitters.py) (Transmitter catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_receiver["Receiver and diagnostics"]
  node_hardware["Dual-channel receiver<br/>[README.md]"]
  node_soundcard["Sound-card input"]
  node_probecheck["Capture diagnostics<br/>[probe_check.py]"]
  node_levelmonitor["Level monitor<br/>[canli_seviye.py]"]
  node_scanner["Transmitter scan<br/>[verici_avi.py]"]
end

subgraph group_backend["Audio backend"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_pipeline["Audio pipeline<br/>[audio.py]"]
  node_canceller["Adaptive cancellation<br/>[dsp.py]"]
  node_encoderhub["MP3 broadcast<br/>[streaming.py]"]
  node_api["HTTP server<br/>[server.py]"]
end

subgraph group_web["Web listening interface"]
  node_interface["Station interface<br/>[app.js]"]
  node_rawclean["Raw and clean audio<br/>[app.js]"]
  node_waterfall["Event waterfall<br/>[app.js]"]
  node_recording["Recent recording<br/>[app.js]"]
  node_map["Lightning map<br/>[app.js]"]
  node_txdisplay["Transmitter table<br/>[app.js]"]
  node_staticlist["Static transmitter list<br/>[transmitters.json]"]
end

subgraph group_results["Transmitter results"]
  node_scanfile["Scan results<br/>[son_tarama.json]"]
  node_txservice["Transmitter catalog<br/>[transmitters.py]"]
end

node_radio(("VLF signals"))
node_visitor(("Listener"))
node_blitzortung["Blitzortung network"]

node_radio -->|"induces signals"| node_hardware
node_hardware -->|"feeds audio"| node_soundcard
node_soundcard -.->|"captures audio"| node_pipeline
node_pipeline -->|"uses settings"| node_settings
node_pipeline -->|"processes blocks"| node_canceller
node_pipeline -->|"encodes raw and clean"| node_encoderhub
node_api -->|"starts and reports"| node_pipeline
node_api -->|"routes audio streams"| node_encoderhub
node_probecheck -->|"tests capture"| node_soundcard
node_levelmonitor -->|"monitors levels"| node_soundcard
node_scanner -->|"scans input"| node_soundcard
node_scanner -->|"writes results"| node_scanfile
node_api -->|"serves results"| node_txservice
node_txservice -->|"reads results"| node_scanfile
node_visitor -->|"opens station"| node_interface
node_interface -->|"requests streams"| node_api
node_api -->|"streams MP3"| node_encoderhub
node_interface -->|"switches channels"| node_rawclean
node_interface -->|"renders spectrum"| node_waterfall
node_interface -->|"records recent audio"| node_recording
node_interface -->|"shows lightning"| node_map
node_map -.->|"embeds map data"| node_blitzortung
node_interface -->|"renders table"| node_txdisplay
node_txdisplay -->|"fetches scan data"| node_txservice
node_txdisplay -->|"falls back to list"| node_staticlist

click node_hardware "https://github.com/altunsumerve/vlf-noise-scout/blob/main/hardware/README.md"
click node_probecheck "https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/tools/probe_check.py"
click node_levelmonitor "https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/tools/canli_seviye.py"
click node_scanner "https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/tools/verici_avi.py"
click node_settings "https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/config.py"
click node_pipeline "https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/audio.py"
click node_canceller "https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/dsp.py"
click node_encoderhub "https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/streaming.py"
click node_api "https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/server.py"
click node_scanfile "https://github.com/altunsumerve/vlf-noise-scout/blob/main/data/son_tarama.json"
click node_txservice "https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/transmitters.py"
click node_interface "https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js"
click node_rawclean "https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js"
click node_waterfall "https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js"
click node_recording "https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js"
click node_map "https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js"
click node_txdisplay "https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js"
click node_staticlist "https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/transmitters.json"

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_hardware,node_soundcard,node_probecheck,node_levelmonitor,node_scanner toneBlue
class node_settings,node_pipeline,node_canceller,node_encoderhub,node_api toneAmber
class node_interface,node_rawclean,node_waterfall,node_recording,node_map,node_txdisplay,node_staticlist toneMint
class node_scanfile,node_txservice toneRose
class node_radio,node_visitor,node_blitzortung toneIndigo
```

## Components

### Receiver and diagnostics

- [Dual-channel receiver](https://github.com/altunsumerve/vlf-noise-scout/blob/main/hardware/README.md): `hardware/README.md`
- **Sound-card input**
- [Capture diagnostics](https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/tools/probe_check.py): `server/tools/probe_check.py`
- [Level monitor](https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/tools/canli_seviye.py): `server/tools/canli_seviye.py`
- [Transmitter scan](https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/tools/verici_avi.py): `server/tools/verici_avi.py`

### Audio backend

- [Runtime settings](https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/config.py): `server/vlf_stream/config.py`
- [Audio pipeline](https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/audio.py): `server/vlf_stream/audio.py`
- [Adaptive cancellation](https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/dsp.py): `server/vlf_stream/dsp.py`
- [MP3 broadcast](https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/streaming.py): `server/vlf_stream/streaming.py`
- [HTTP server](https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/server.py): `server/vlf_stream/server.py`

### Web listening interface

- [Station interface](https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js): `web/app.js`
- [Raw and clean audio](https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js): `web/app.js`
- [Event waterfall](https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js): `web/app.js`
- [Recent recording](https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js): `web/app.js`
- [Lightning map](https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js): `web/app.js`
- [Transmitter table](https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/app.js): `web/app.js`
- [Static transmitter list](https://github.com/altunsumerve/vlf-noise-scout/blob/main/web/transmitters.json): `web/transmitters.json`

### Transmitter results

- [Scan results](https://github.com/altunsumerve/vlf-noise-scout/blob/main/data/son_tarama.json): `data/son_tarama.json`
- [Transmitter catalog](https://github.com/altunsumerve/vlf-noise-scout/blob/main/server/vlf_stream/transmitters.py): `server/vlf_stream/transmitters.py`

### Other components

- **VLF signals**
- **Listener**
- **Blitzortung network**

## Connections

- VLF signals → Dual-channel receiver: induces signals (evidence: `README.md`)
- Dual-channel receiver → Sound-card input: feeds audio (evidence: `README.md`)
- Sound-card input → Audio pipeline: captures audio
- Audio pipeline → Runtime settings: uses settings (evidence: `server/vlf_stream/audio.py`)
- Audio pipeline → Adaptive cancellation: processes blocks (evidence: `server/vlf_stream/audio.py`)
- Audio pipeline → MP3 broadcast: encodes raw and clean (evidence: `server/vlf_stream/audio.py`)
- HTTP server → Audio pipeline: starts and reports (evidence: `server/vlf_stream/server.py`)
- HTTP server → MP3 broadcast: routes audio streams (evidence: `server/vlf_stream/server.py`)
- Capture diagnostics → Sound-card input: tests capture (evidence: `server/tools/probe_check.py`)
- Level monitor → Sound-card input: monitors levels (evidence: `server/tools/canli_seviye.py`)
- Transmitter scan → Sound-card input: scans input (evidence: `server/tools/verici_avi.py`)
- Transmitter scan → Scan results: writes results (evidence: `README.md`)
- HTTP server → Transmitter catalog: serves results (evidence: `server/vlf_stream/server.py`)
- Transmitter catalog → Scan results: reads results (evidence: `server/vlf_stream/transmitters.py`)
- Listener → Station interface: opens station (evidence: `README.md`)
- Station interface → HTTP server: requests streams (evidence: `web/app.js`)
- HTTP server → MP3 broadcast: streams MP3 (evidence: `server/vlf_stream/server.py`)
- Station interface → Raw and clean audio: switches channels (evidence: `web/app.js`)
- Station interface → Event waterfall: renders spectrum (evidence: `web/app.js`)
- Station interface → Recent recording: records recent audio (evidence: `web/app.js`)
- Station interface → Lightning map: shows lightning (evidence: `README.md`)
- Lightning map → Blitzortung network: embeds map data (evidence: `README.md`)
- Station interface → Transmitter table: renders table (evidence: `web/app.js`)
- Transmitter table → Transmitter catalog: fetches scan data (evidence: `web/app.js`)
- Transmitter table → Static transmitter list: falls back to list (evidence: `web/app.js`)
