akumascoffin/rdio-scanner

1. This repository is a three-part product: a Go backend in server/, an Angular web client in client/, and a native Android client in android/. The backend is the central runtime; the web client is compiled into static assets and embedded into the Go binary at build time.

2. The core server is a long-running HTTP application that exposes the browser UI, admin UI, public REST API, WebSocket/live updates, and recorder ingestion endpoints. It is the architectural hub connecting incoming call data, persisted metadata, transcripts, and downstream consumers.

3. Call ingestion is driven by recorder integrations. The server can accept API-based uploads from supported recorders and also monitor directories for “one audio file per call” workflows. This ingest path feeds metadata parsing, persistence, optional transcription, and live broadcast to connected clients.

4. Persistence is abstracted behind the server’s database layer and supports SQLite by default, with PostgreSQL, MySQL, and MariaDB as options. The README emphasizes PostgreSQL as the preferred deployment for large installs because search and stats rely on database indexes and concurrent ingest/search workloads.

5. Search and browsing are first-class server features. The backend stores call records, transcripts, systems, talkgroups, units, tags, and stats-related aggregates, then serves filtered search results and deep links to the web UI. Transcript search is optimized at the database level, which is important for diagramming the data flow from ingest to indexed query.

6. Transcription is a separate backend subsystem. The server can send audio to Groq Whisper, manage multiple API keys, retry on failures, and conditionally hold call visibility until transcript text is available. This makes transcription an asynchronous enrichment stage after ingestion rather than part of the initial upload path.

7. Real-time behavior is handled through WebSockets and livefeed-style server push. The backend broadcasts current call activity, listener counts, and LCD-style status updates to web and mobile clients. The README’s “early-WS opener” and buffered sends indicate that realtime transport is a core performance boundary, not just a UI detail.

8. The web client in client/ is an Angular single-page application with two major user surfaces: the main scanner UI and the admin console. It includes components for search, stats, live feed, selection, and configuration management, plus a service layer that talks to the Go backend’s HTTP and WebSocket endpoints.

9. The admin area is a substantial subsystem rather than a small settings page. It manages systems, talkgroups, units, groups, API keys, access controls, downstreams, directory watch configuration, logs, statistics, and import/export tooling. In the architecture diagram, this is the control plane for server configuration and operational data.

10. The main web UI focuses on operator and listener experience: live transcript display, search, stats dashboard, and shareable deep links. The frontend is designed to consume the backend’s public data model and realtime updates, while the server remains responsible for authorization, filtering, and persistence.

11. The Android app in android/ is a separate native client built with Kotlin and Compose. It mirrors the live scanner experience, supports multiple connection profiles, background audio playback, and reconnect logic, and talks directly to the same backend rather than embedding the web app.

12. Supporting subsystems in the backend include audio playback/decode, downloader/repository logic, settings persistence, protocol/message modeling, network monitoring, and scheduler/background tasks. These are internal boundaries inside the Go service that connect file/audio handling, database operations, and client-facing APIs.

13. Deployment-wise, the architecture is usually a single Go executable plus a database, with optional external recorder processes supplying audio files. The embedded web app means there is no separate frontend server in production, and the Android app is optional as an additional client, not part of the backend runtime.

14. Overall data flow: recorder or uploader → Go ingest/parsing → database persistence and optional transcription → indexed search/stats/livefeed updates → Angular web UI or Android app consumption. That is the main end-to-end path an architecture diagram should emphasize.