# xxbubziexx/scanner_controller architecture

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

- Interactive diagram: https://gitdiagram.com/xxbubziexx/scanner_controller
- Repository: https://github.com/xxbubziexx/scanner_controller

## Overview

This is a dual-Uniden-scanner controller: it discovers and configures radios, polls them through family-specific drivers, and coordinates duplicate-frequency/talkgroup avoidance while capturing audio for monitoring and ScanScribe delivery. Users operate it through either a desktop GUI or a FastAPI web service. Audio formatting, ProScan metadata, and feeder output are distinct result stages. The graph preserves README capabilities, but unsampled implementation details are represented only where the README or SOURCE INDEX supports the relationship.

Main entry points: [`engine/sync_manager.py`](https://github.com/xxbubziexx/scanner_controller/blob/main/engine/sync_manager.py) (Sync manager), [`server.py`](https://github.com/xxbubziexx/scanner_controller/blob/main/server.py) (Web service), [`feeder/scanscribe_feeder.py`](https://github.com/xxbubziexx/scanner_controller/blob/main/feeder/scanscribe_feeder.py) (ScanScribe feeder), [`drivers/driver_factory.py`](https://github.com/xxbubziexx/scanner_controller/blob/main/drivers/driver_factory.py) (Driver factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_desktop["Desktop GUI<br/>[gui.py]"]
  node_webservice["Web service<br/>[server.py]"]
  node_webui["Web interface<br/>[app.js]"]
end

subgraph group_radio["Radio discovery and drivers"]
  node_serial_discovery["Serial discovery<br/>[serial_detector.py]"]
  node_lan_discovery["LAN discovery<br/>[net_detector.py]"]
  node_factory["Driver factory<br/>[driver_factory.py]"]
  node_driver_base["Driver interface<br/>[base_driver.py]"]
  node_hp_driver["HomePatrol driver<br/>[bcd436hp.py]"]
  node_dma_driver["DMA driver<br/>[bcd996p2.py]"]
  node_classic_driver["Classic driver<br/>[classic_driver.py]"]
end

subgraph group_control["Synchronization and configuration"]
  node_config["Application config<br/>[config.py]"]
  node_sync["Sync manager<br/>[sync_manager.py]"]
end

subgraph group_audio["Audio and monitoring"]
  node_capture["Audio capture<br/>[recorder.py]"]
  node_monitor["Loopback monitor<br/>[recorder.py]"]
end

subgraph group_delivery["Recording delivery"]
  node_metadata["ProScan metadata"]
  node_feeder["ScanScribe feeder"]
  node_inbox[("Recording inbox")]
  node_webhook["Ingestion webhook"]
  node_transcription["Transcription pipeline"]
end

node_user(("Operator"))

node_user -->|"operates"| node_desktop
node_user -->|"operates"| node_webui
node_webservice -->|"serves"| node_webui
node_desktop -->|"controls"| node_sync
node_webservice -->|"controls"| node_sync
node_desktop -->|"configures"| node_config
node_webservice -->|"uses"| node_config
node_webservice -->|"probes ports"| node_serial_discovery
node_webservice -->|"discovers radios"| node_lan_discovery
node_sync -->|"reads settings"| node_config
node_sync -->|"creates drivers"| node_factory
node_sync -->|"polls radios"| node_driver_base
node_factory -->|"selects model"| node_hp_driver
node_factory -->|"selects model"| node_dma_driver
node_factory -->|"selects model"| node_classic_driver
node_hp_driver -->|"extends"| node_driver_base
node_sync -->|"starts capture"| node_capture
node_capture -->|"feeds audio"| node_monitor
node_sync -->|"dispatches calls"| node_feeder
node_feeder -->|"formats tags"| node_metadata
node_feeder -->|"drops recordings"| node_inbox
node_feeder -->|"posts recordings"| node_webhook
node_feeder -.->|"supports ingestion"| node_transcription

click node_desktop "https://github.com/xxbubziexx/scanner_controller/blob/main/gui.py"
click node_webservice "https://github.com/xxbubziexx/scanner_controller/blob/main/server.py"
click node_webui "https://github.com/xxbubziexx/scanner_controller/blob/main/static/app.js"
click node_config "https://github.com/xxbubziexx/scanner_controller/blob/main/config.py"
click node_serial_discovery "https://github.com/xxbubziexx/scanner_controller/blob/main/discovery/serial_detector.py"
click node_lan_discovery "https://github.com/xxbubziexx/scanner_controller/blob/main/discovery/net_detector.py"
click node_sync "https://github.com/xxbubziexx/scanner_controller/blob/main/engine/sync_manager.py"
click node_factory "https://github.com/xxbubziexx/scanner_controller/blob/main/drivers/driver_factory.py"
click node_driver_base "https://github.com/xxbubziexx/scanner_controller/blob/main/drivers/base_driver.py"
click node_hp_driver "https://github.com/xxbubziexx/scanner_controller/blob/main/drivers/bcd436hp.py"
click node_dma_driver "https://github.com/xxbubziexx/scanner_controller/blob/main/drivers/bcd996p2.py"
click node_classic_driver "https://github.com/xxbubziexx/scanner_controller/blob/main/drivers/classic_driver.py"
click node_capture "https://github.com/xxbubziexx/scanner_controller/blob/main/audio/recorder.py"
click node_monitor "https://github.com/xxbubziexx/scanner_controller/blob/main/audio/recorder.py"
click node_metadata "https://github.com/xxbubziexx/scanner_controller/blob/main/metadata/proscan_metadata.py"
click node_feeder "https://github.com/xxbubziexx/scanner_controller/blob/main/feeder/scanscribe_feeder.py"

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_desktop,node_webservice,node_webui toneBlue
class node_serial_discovery,node_lan_discovery,node_factory,node_driver_base,node_hp_driver,node_dma_driver,node_classic_driver toneAmber
class node_config,node_sync toneMint
class node_capture,node_monitor toneRose
class node_metadata,node_feeder,node_inbox,node_webhook,node_transcription,node_user toneIndigo
```

## Components

### User interfaces

- [Desktop GUI](https://github.com/xxbubziexx/scanner_controller/blob/main/gui.py): `gui.py`
- [Web service](https://github.com/xxbubziexx/scanner_controller/blob/main/server.py): `server.py`
- [Web interface](https://github.com/xxbubziexx/scanner_controller/blob/main/static/app.js): `static/app.js`

### Radio discovery and drivers

- [Serial discovery](https://github.com/xxbubziexx/scanner_controller/blob/main/discovery/serial_detector.py): `discovery/serial_detector.py`
- [LAN discovery](https://github.com/xxbubziexx/scanner_controller/blob/main/discovery/net_detector.py): `discovery/net_detector.py`
- [Driver factory](https://github.com/xxbubziexx/scanner_controller/blob/main/drivers/driver_factory.py): `drivers/driver_factory.py`
- [Driver interface](https://github.com/xxbubziexx/scanner_controller/blob/main/drivers/base_driver.py): `drivers/base_driver.py`
- [HomePatrol driver](https://github.com/xxbubziexx/scanner_controller/blob/main/drivers/bcd436hp.py): `drivers/bcd436hp.py`
- [DMA driver](https://github.com/xxbubziexx/scanner_controller/blob/main/drivers/bcd996p2.py): `drivers/bcd996p2.py`
- [Classic driver](https://github.com/xxbubziexx/scanner_controller/blob/main/drivers/classic_driver.py): `drivers/classic_driver.py`

### Synchronization and configuration

- [Application config](https://github.com/xxbubziexx/scanner_controller/blob/main/config.py): `config.py`
- [Sync manager](https://github.com/xxbubziexx/scanner_controller/blob/main/engine/sync_manager.py): `engine/sync_manager.py`

### Audio and monitoring

- [Audio capture](https://github.com/xxbubziexx/scanner_controller/blob/main/audio/recorder.py): `audio/recorder.py`
- [Loopback monitor](https://github.com/xxbubziexx/scanner_controller/blob/main/audio/recorder.py): `audio/recorder.py`

### Recording delivery

- [ProScan metadata](https://github.com/xxbubziexx/scanner_controller/blob/main/metadata/proscan_metadata.py): `metadata/proscan_metadata.py`
- [ScanScribe feeder](https://github.com/xxbubziexx/scanner_controller/blob/main/feeder/scanscribe_feeder.py): `feeder/scanscribe_feeder.py`
- **Recording inbox**
- **Ingestion webhook**
- **Transcription pipeline**

### Other components

- **Operator**

## Connections

- Operator → Desktop GUI: operates (evidence: `README.md`)
- Operator → Web interface: operates (evidence: `README.md`)
- Web service → Web interface: serves (evidence: `server.py`)
- Desktop GUI → Sync manager: controls (evidence: `gui.py`)
- Web service → Sync manager: controls (evidence: `server.py`)
- Desktop GUI → Application config: configures (evidence: `gui.py`)
- Web service → Application config: uses (evidence: `server.py`)
- Web service → Serial discovery: probes ports (evidence: `server.py`)
- Web service → LAN discovery: discovers radios (evidence: `server.py`)
- Sync manager → Application config: reads settings (evidence: `engine/sync_manager.py`)
- Sync manager → Driver factory: creates drivers (evidence: `engine/sync_manager.py`)
- Sync manager → Driver interface: polls radios (evidence: `engine/sync_manager.py`)
- Driver factory → HomePatrol driver: selects model (evidence: `drivers/driver_factory.py`)
- Driver factory → DMA driver: selects model (evidence: `drivers/driver_factory.py`)
- Driver factory → Classic driver: selects model (evidence: `drivers/driver_factory.py`)
- HomePatrol driver → Driver interface: extends (evidence: `drivers/bcd436hp.py`)
- Sync manager → Audio capture: starts capture (evidence: `engine/sync_manager.py`)
- Audio capture → Loopback monitor: feeds audio (evidence: `README.md`)
- Sync manager → ScanScribe feeder: dispatches calls (evidence: `engine/sync_manager.py`)
- ScanScribe feeder → ProScan metadata: formats tags (evidence: `feeder/scanscribe_feeder.py`)
- ScanScribe feeder → Recording inbox: drops recordings (evidence: `README.md`)
- ScanScribe feeder → Ingestion webhook: posts recordings (evidence: `README.md`)
- ScanScribe feeder → Transcription pipeline: supports ingestion (evidence: `README.md`)
