# vk-ant/sonarwise architecture

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

- Interactive diagram: https://gitdiagram.com/vk-ant/sonarwise
- Repository: https://github.com/vk-ant/sonarwise

## Overview

Sonarwise is a pluggable audio indexing and retrieval engine. Users submit recordings through the Python API or CLI; the central pipeline prepares and segments audio, derives transcripts and optional speaker/event/language metadata, stores searchable segments, and serves text, audio, speaker, and event queries. It also documents live listening, conversation analytics, clip extraction, and export. The pipeline excerpt is partial, so the graph reflects documented capabilities and indexed module references without asserting unshown implementation details.

Main entry points: [`sonarwise/core/pipeline.py`](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/pipeline.py) (SonarWise pipeline), [`sonarwise/core/store.py`](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/store.py) (Segment and speaker store), [`sonarwise/__init__.py`](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/__init__.py) (Python API), [`sonarwise/cli.py`](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/cli.py) (Command line)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_api["Python API<br/>[__init__.py]"]
  node_cli["Command line<br/>[cli.py]"]
end

subgraph group_index["Audio indexing"]
  node_pipeline["SonarWise pipeline<br/>[pipeline.py]"]
  node_audio["Audio I/O<br/>[audio_io.py]"]
  node_preprocess["Audio preprocessing<br/>[preprocessor.py]"]
  node_chunker["Audio chunking<br/>[chunker.py]"]
  node_transcriber["Transcription<br/>[transcriber.py]"]
  node_diarizer["Speaker diarization<br/>[diarizer.py]"]
  node_events["Event classification"]
  node_language["Language detection"]
  node_live["Live listening<br/>[stream_listener.py]"]
end

subgraph group_retrieve["Search and intelligence"]
  node_embedder["Audio embeddings<br/>[embedder.py]"]
  node_speaker_embed["Speaker voiceprints"]
  node_store[("Segment and speaker store<br/>[store.py]")]
  node_search["Semantic and event search<br/>[pipeline.py]"]
  node_analytics["Conversation analytics<br/>[pipeline.py]"]
  node_clips_export["Clip extraction and export<br/>[pipeline.py]"]
end

subgraph group_runtime["Runtime services"]
  node_models["Audio and result models<br/>[models.py]"]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("Audio user"))

node_user -->|"uses"| node_api
node_user -->|"runs commands"| node_cli
node_api -->|"creates"| node_pipeline
node_cli -->|"invokes"| node_pipeline
node_pipeline -.->|"configures"| node_config
node_pipeline -->|"loads audio"| node_audio
node_pipeline -->|"preprocesses"| node_preprocess
node_pipeline -->|"segments audio"| node_chunker
node_pipeline -->|"transcribes segments"| node_transcriber
node_pipeline -->|"assigns speakers"| node_diarizer
node_pipeline -->|"classifies events"| node_events
node_pipeline -->|"detects language"| node_language
node_pipeline -->|"embeds audio"| node_embedder
node_pipeline -->|"embeds voices"| node_speaker_embed
node_pipeline -->|"stores segments"| node_store
node_pipeline -->|"uses data models"| node_models
node_pipeline -->|"serves queries"| node_search
node_search -->|"searches segments"| node_store
node_search -->|"embeds text queries"| node_embedder
node_pipeline -->|"analyzes conversations"| node_analytics
node_analytics -->|"reads segments"| node_store
node_pipeline -->|"extracts and exports"| node_clips_export
node_pipeline -->|"starts listening"| node_live
node_live -->|"captures audio"| node_audio

click node_api "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/__init__.py"
click node_cli "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/cli.py"
click node_pipeline "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/pipeline.py"
click node_audio "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/utils/audio_io.py"
click node_preprocess "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/preprocessor.py"
click node_chunker "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/chunker.py"
click node_transcriber "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/transcriber.py"
click node_diarizer "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/diarizer.py"
click node_events "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/event_classifier.py"
click node_language "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/language_detector.py"
click node_models "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/models.py"
click node_embedder "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/embedder.py"
click node_speaker_embed "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/speaker_embedder.py"
click node_store "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/store.py"
click node_search "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/pipeline.py"
click node_analytics "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/pipeline.py"
click node_clips_export "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/pipeline.py"
click node_live "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/stream_listener.py"
click node_config "https://github.com/vk-ant/sonarwise/blob/main/sonarwise/config.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_api,node_cli,node_user toneBlue
class node_pipeline,node_audio,node_preprocess,node_chunker,node_transcriber,node_diarizer,node_events,node_language,node_live toneAmber
class node_embedder,node_speaker_embed,node_store,node_search,node_analytics,node_clips_export toneMint
class node_models,node_config toneRose
```

## Components

### User entry points

- [Python API](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/__init__.py): `sonarwise/__init__.py`
- [Command line](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/cli.py): `sonarwise/cli.py`

### Audio indexing

- [SonarWise pipeline](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/pipeline.py): `sonarwise/core/pipeline.py`
- [Audio I/O](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/utils/audio_io.py): `sonarwise/utils/audio_io.py`
- [Audio preprocessing](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/preprocessor.py): `sonarwise/core/preprocessor.py`
- [Audio chunking](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/chunker.py): `sonarwise/core/chunker.py`
- [Transcription](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/transcriber.py): `sonarwise/core/transcriber.py`
- [Speaker diarization](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/diarizer.py): `sonarwise/core/diarizer.py`
- [Event classification](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/event_classifier.py): `sonarwise/core/event_classifier.py`
- [Language detection](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/language_detector.py): `sonarwise/core/language_detector.py`
- [Live listening](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/stream_listener.py): `sonarwise/core/stream_listener.py`

### Search and intelligence

- [Audio embeddings](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/embedder.py): `sonarwise/core/embedder.py`
- [Speaker voiceprints](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/speaker_embedder.py): `sonarwise/core/speaker_embedder.py`
- [Segment and speaker store](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/store.py): `sonarwise/core/store.py`
- [Semantic and event search](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/pipeline.py): `sonarwise/core/pipeline.py`
- [Conversation analytics](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/pipeline.py): `sonarwise/core/pipeline.py`
- [Clip extraction and export](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/pipeline.py): `sonarwise/core/pipeline.py`

### Runtime services

- [Audio and result models](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/core/models.py): `sonarwise/core/models.py`
- [Configuration](https://github.com/vk-ant/sonarwise/blob/main/sonarwise/config.py): `sonarwise/config.py`

### Other components

- **Audio user**

## Connections

- Audio user → Python API: uses (evidence: `README.md`)
- Audio user → Command line: runs commands (evidence: `README.md`)
- Python API → SonarWise pipeline: creates (evidence: `sonarwise/__init__.py`)
- Command line → SonarWise pipeline: invokes (evidence: `sonarwise/cli.py`)
- SonarWise pipeline → Configuration: configures (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Audio I/O: loads audio (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Audio preprocessing: preprocesses (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Audio chunking: segments audio (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Transcription: transcribes segments (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Speaker diarization: assigns speakers (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Event classification: classifies events (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Language detection: detects language (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Audio embeddings: embeds audio (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Speaker voiceprints: embeds voices (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Segment and speaker store: stores segments (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Audio and result models: uses data models (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Semantic and event search: serves queries (evidence: `README.md`)
- Semantic and event search → Segment and speaker store: searches segments (evidence: `sonarwise/core/pipeline.py`)
- Semantic and event search → Audio embeddings: embeds text queries (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Conversation analytics: analyzes conversations (evidence: `sonarwise/core/pipeline.py`)
- Conversation analytics → Segment and speaker store: reads segments (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Clip extraction and export: extracts and exports (evidence: `sonarwise/core/pipeline.py`)
- SonarWise pipeline → Live listening: starts listening (evidence: `sonarwise/core/pipeline.py`)
- Live listening → Audio I/O: captures audio (evidence: `sonarwise/core/stream_listener.py`)
