# xxbubziexx/scanscribe architecture

> Architecture diagram of the GitHub repository xxbubziexx/scanscribe, 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/scanscribe
- Repository: https://github.com/xxbubziexx/scanscribe

## Overview

ScanScribe is a public-safety radio transcription and incident-intelligence station. Its principal workflow captures scanner audio, transcribes it, extracts entities, routes transmissions into incident threads, and presents live incidents and analytics in a browser console. The graph also preserves the documented conversational intelligence, dataset review/export, mapping, and authentication capabilities. Some frontend and ingestion connections are documented in the README but their implementation was not sampled; those links are dashed where the code-level relationship is unverified.

Main entry points: [`app/services/events/pipeline.py`](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/events/pipeline.py) (Transcript Routing), [`app/frontend/src/App.tsx`](https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/App.tsx) (Web Console), [`app/main.py`](https://github.com/xxbubziexx/scanscribe/blob/main/app/main.py) (HTTP API), [`app/services/events/incidents.py`](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/events/incidents.py) (Incident Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Audio Ingestion"]
  node_watcher["Audio Watcher<br/>[watcher.py]"]
  node_queue["Processing Queue<br/>[queue_processor.py]"]
  node_transcription["Speech Recognition"]
  node_transcripts[("Transcript Records<br/>[log_entry.py]")]
end

subgraph group_intelligence["Incident Intelligence"]
  node_event_worker["Event Worker<br/>[events_worker.py]"]
  node_pipeline["Transcript Routing<br/>[pipeline.py]"]
  node_ner["Entity Recognition<br/>[ner_service.py]"]
  node_router["LLM Router"]
  node_event_context["Incident Context<br/>[context.py]"]
  node_incident_lifecycle["Incident Lifecycle<br/>[incidents.py]"]
  node_events[("Incident Records<br/>[event.py]")]
  node_geocoder["Geocoding"]
end

subgraph group_api["Platform Services"]
  node_websocket["Live Updates<br/>[websocket.py]"]
  node_insights["Analytics Engine<br/>[insights_engine.py]"]
  node_database[("Unified Database<br/>[database.py]")]
  node_settings["Configuration<br/>[config.py]"]
  node_logging["Logging Setup<br/>[logging_config.py]"]
  node_api_routes["HTTP API<br/>[main.py]"]
  node_chat_routes["Chat API<br/>[chat.py]"]
end

subgraph group_frontend["Operator Console"]
  node_spa["Web Console<br/>[App.tsx]"]
  node_command_center["Command Center"]
  node_events_ui["Incident Hub<br/>[index.tsx]"]
  node_intel_ui["Intelligence Console<br/>[IntelPage.tsx]"]
  node_dataset_ui["Dataset Studio<br/>[DatasetPage.tsx]"]
  node_dashboard["Live Dashboard<br/>[DashboardPage.tsx]"]
end

subgraph group_identity["Accounts"]
  node_auth_routes["Authentication<br/>[auth.py]"]
  node_users[("User Accounts<br/>[user.py]")]
end

node_scanner(("Radio Source"))
node_browser(("Operator"))

node_scanner -.->|"supplies audio"| node_watcher
node_watcher -.->|"enqueues audio"| node_queue
node_queue -.->|"processes audio"| node_transcription
node_transcription -.->|"stores transcript"| node_transcripts
node_event_worker -->|"delegates to"| node_pipeline
node_pipeline -->|"extracts entities"| node_ner
node_pipeline -->|"routes transcript"| node_router
node_pipeline -->|"uses context"| node_event_context
node_pipeline -->|"applies decision"| node_incident_lifecycle
node_incident_lifecycle -.->|"creates incidents"| node_events
node_incident_lifecycle -->|"dispatches geocoding"| node_geocoder
node_pipeline -->|"broadcasts updates"| node_websocket
node_api_routes -->|"starts worker"| node_queue
node_api_routes -->|"starts worker"| node_event_worker
node_api_routes -->|"initializes storage"| node_database
node_database -->|"loads settings"| node_settings
node_insights -->|"queries events"| node_events
node_insights -->|"queries transcripts"| node_transcripts
node_browser -.->|"opens console"| node_spa
node_spa -.->|"presents map"| node_command_center
node_spa -.->|"presents incidents"| node_events_ui
node_spa -.->|"opens conversations"| node_intel_ui
node_spa -.->|"reviews datasets"| node_dataset_ui
node_spa -.->|"shows live feed"| node_dashboard
node_browser -.->|"authenticates"| node_auth_routes
node_auth_routes -->|"reads and writes"| node_users
node_intel_ui -.->|"queries traffic"| node_chat_routes
node_chat_routes -.->|"queries history"| node_database
node_command_center -.->|"maps locations"| node_geocoder
node_websocket -.->|"pushes updates"| node_dashboard
node_logging -->|"supports logging"| node_websocket

click node_watcher "https://github.com/xxbubziexx/scanscribe/blob/main/app/services/watcher.py"
click node_queue "https://github.com/xxbubziexx/scanscribe/blob/main/app/services/queue_processor.py"
click node_transcription "https://github.com/xxbubziexx/scanscribe/blob/main/app/services/transcription_engine.py"
click node_transcripts "https://github.com/xxbubziexx/scanscribe/blob/main/app/models/log_entry.py"
click node_event_worker "https://github.com/xxbubziexx/scanscribe/blob/main/app/services/events_worker.py"
click node_pipeline "https://github.com/xxbubziexx/scanscribe/blob/main/app/services/events/pipeline.py"
click node_ner "https://github.com/xxbubziexx/scanscribe/blob/main/app/services/ner_service.py"
click node_router "https://github.com/xxbubziexx/scanscribe/blob/main/app/services/events_router_engine.py"
click node_event_context "https://github.com/xxbubziexx/scanscribe/blob/main/app/services/events/context.py"
click node_incident_lifecycle "https://github.com/xxbubziexx/scanscribe/blob/main/app/services/events/incidents.py"
click node_events "https://github.com/xxbubziexx/scanscribe/blob/main/app/models/event.py"
click node_geocoder "https://github.com/xxbubziexx/scanscribe/blob/main/app/services/geocoder_service.py"
click node_websocket "https://github.com/xxbubziexx/scanscribe/blob/main/app/services/websocket.py"
click node_insights "https://github.com/xxbubziexx/scanscribe/blob/main/app/services/insights_engine.py"
click node_database "https://github.com/xxbubziexx/scanscribe/blob/main/app/database.py"
click node_settings "https://github.com/xxbubziexx/scanscribe/blob/main/app/config.py"
click node_logging "https://github.com/xxbubziexx/scanscribe/blob/main/app/logging_config.py"
click node_api_routes "https://github.com/xxbubziexx/scanscribe/blob/main/app/main.py"
click node_spa "https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/App.tsx"
click node_command_center "https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/pages/CommandCenter/CommandCenterPage.tsx"
click node_events_ui "https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/pages/Events/Incidents/index.tsx"
click node_intel_ui "https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/pages/Intel/IntelPage.tsx"
click node_dataset_ui "https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/pages/DataExplorer/DatasetPage.tsx"
click node_dashboard "https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/pages/Dashboard/DashboardPage.tsx"
click node_auth_routes "https://github.com/xxbubziexx/scanscribe/blob/main/app/routes/auth.py"
click node_users "https://github.com/xxbubziexx/scanscribe/blob/main/app/models/user.py"
click node_chat_routes "https://github.com/xxbubziexx/scanscribe/blob/main/app/routes/chat.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_watcher,node_queue,node_transcription,node_transcripts toneBlue
class node_event_worker,node_pipeline,node_ner,node_router,node_event_context,node_incident_lifecycle,node_events,node_geocoder toneAmber
class node_websocket,node_insights,node_database,node_settings,node_logging,node_api_routes,node_chat_routes toneMint
class node_spa,node_command_center,node_events_ui,node_intel_ui,node_dataset_ui,node_dashboard toneRose
class node_auth_routes,node_users,node_scanner,node_browser toneIndigo
```

## Components

### Audio Ingestion

- [Audio Watcher](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/watcher.py): `app/services/watcher.py`
- [Processing Queue](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/queue_processor.py): `app/services/queue_processor.py`
- [Speech Recognition](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/transcription_engine.py): `app/services/transcription_engine.py`
- [Transcript Records](https://github.com/xxbubziexx/scanscribe/blob/main/app/models/log_entry.py): `app/models/log_entry.py`

### Incident Intelligence

- [Event Worker](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/events_worker.py): `app/services/events_worker.py`
- [Transcript Routing](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/events/pipeline.py): `app/services/events/pipeline.py`
- [Entity Recognition](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/ner_service.py): `app/services/ner_service.py`
- [LLM Router](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/events_router_engine.py): `app/services/events_router_engine.py`
- [Incident Context](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/events/context.py): `app/services/events/context.py`
- [Incident Lifecycle](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/events/incidents.py): `app/services/events/incidents.py`
- [Incident Records](https://github.com/xxbubziexx/scanscribe/blob/main/app/models/event.py): `app/models/event.py`
- [Geocoding](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/geocoder_service.py): `app/services/geocoder_service.py`

### Platform Services

- [Live Updates](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/websocket.py): `app/services/websocket.py`
- [Analytics Engine](https://github.com/xxbubziexx/scanscribe/blob/main/app/services/insights_engine.py): `app/services/insights_engine.py`
- [Unified Database](https://github.com/xxbubziexx/scanscribe/blob/main/app/database.py): `app/database.py`
- [Configuration](https://github.com/xxbubziexx/scanscribe/blob/main/app/config.py): `app/config.py`
- [Logging Setup](https://github.com/xxbubziexx/scanscribe/blob/main/app/logging_config.py): `app/logging_config.py`
- [HTTP API](https://github.com/xxbubziexx/scanscribe/blob/main/app/main.py): `app/main.py`
- [Chat API](https://github.com/xxbubziexx/scanscribe/blob/main/app/routes/chat.py): `app/routes/chat.py`

### Operator Console

- [Web Console](https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/App.tsx): `app/frontend/src/App.tsx`
- [Command Center](https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/pages/CommandCenter/CommandCenterPage.tsx): `app/frontend/src/pages/CommandCenter/CommandCenterPage.tsx`
- [Incident Hub](https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/pages/Events/Incidents/index.tsx): `app/frontend/src/pages/Events/Incidents/index.tsx`
- [Intelligence Console](https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/pages/Intel/IntelPage.tsx): `app/frontend/src/pages/Intel/IntelPage.tsx`
- [Dataset Studio](https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/pages/DataExplorer/DatasetPage.tsx): `app/frontend/src/pages/DataExplorer/DatasetPage.tsx`
- [Live Dashboard](https://github.com/xxbubziexx/scanscribe/blob/main/app/frontend/src/pages/Dashboard/DashboardPage.tsx): `app/frontend/src/pages/Dashboard/DashboardPage.tsx`

### Accounts

- [Authentication](https://github.com/xxbubziexx/scanscribe/blob/main/app/routes/auth.py): `app/routes/auth.py`
- [User Accounts](https://github.com/xxbubziexx/scanscribe/blob/main/app/models/user.py): `app/models/user.py`

### Other components

- **Radio Source**
- **Operator**

## Connections

- Radio Source → Audio Watcher: supplies audio
- Audio Watcher → Processing Queue: enqueues audio
- Processing Queue → Speech Recognition: processes audio
- Speech Recognition → Transcript Records: stores transcript
- Event Worker → Transcript Routing: delegates to (evidence: `app/services/events_worker.py`)
- Transcript Routing → Entity Recognition: extracts entities (evidence: `app/services/events/pipeline.py`)
- Transcript Routing → LLM Router: routes transcript (evidence: `app/services/events/pipeline.py`)
- Transcript Routing → Incident Context: uses context (evidence: `app/services/events/pipeline.py`)
- Transcript Routing → Incident Lifecycle: applies decision (evidence: `app/services/events/pipeline.py`)
- Incident Lifecycle → Incident Records: creates incidents
- Incident Lifecycle → Geocoding: dispatches geocoding
- Transcript Routing → Live Updates: broadcasts updates (evidence: `app/services/events/pipeline.py`)
- HTTP API → Processing Queue: starts worker (evidence: `app/main.py`)
- HTTP API → Event Worker: starts worker (evidence: `app/main.py`)
- HTTP API → Unified Database: initializes storage (evidence: `app/main.py`)
- Unified Database → Configuration: loads settings (evidence: `app/database.py`)
- Analytics Engine → Incident Records: queries events (evidence: `app/services/insights_engine.py`)
- Analytics Engine → Transcript Records: queries transcripts (evidence: `app/services/insights_engine.py`)
- Operator → Web Console: opens console
- Web Console → Command Center: presents map
- Web Console → Incident Hub: presents incidents
- Web Console → Intelligence Console: opens conversations
- Web Console → Dataset Studio: reviews datasets
- Web Console → Live Dashboard: shows live feed
- Operator → Authentication: authenticates
- Authentication → User Accounts: reads and writes (evidence: `app/routes/auth.py`)
- Intelligence Console → Chat API: queries traffic
- Chat API → Unified Database: queries history
- Command Center → Geocoding: maps locations
- Live Updates → Live Dashboard: pushes updates
- Logging Setup → Live Updates: supports logging (evidence: `app/services/websocket.py`)
