# juanmc2005/diart architecture

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

- Interactive diagram: https://gitdiagram.com/juanmc2005/diart
- Repository: https://github.com/juanmc2005/diart

## Overview

##### Main System Components
a. Audio Sources
- FileAudioSource (pre‐recorded WAV)
- MicrophoneAudioSource (live capture via sounddevice/portaudio)
- WebSocketAudioSource (client/server over websockets)
b. Core Pipeline Blocks
- SegmentationModel (ONNX/PyTorch)
- EmbeddingModel (ONNX/PyTorch)
- Overlap-Aware Segmentation & SpeakerEmbedding (blocks)
- Incremental Clustering (diarization algorithm)
c. Streaming & Control
- StreamingInference (RxPY-powered observer pattern)
- CLI entry points (diart.stream, diart.tune, diart.benchmark, diart.serve, diart.client)
- Optimizer (Optuna based hyper-parameter tuner)
d. Outputs & Observers
- RTTMWriter (write diarization results)
- WebSocketAudioSource.send (stream RTTM back to client)
- Benchmark & evaluation modules

##### Relationships & Data Flow
a. Audio Source → StreamingInference → Pipeline Blocks → Observer Sinks
b. CLI & Configuration
- diart.stream / diart.serve instantiate StreamingInference with config (sample_rate, step, latency)
- diart.tune → Optimizer → repeatedly run Benchmark on offline datasets
- diart.benchmark / diart.inference.Benchmark → uses same pipeline blocks in batch mode

##### Architectural Patterns & Principles
- Modular Blocks: each functionality (segmentation, embedding, clustering) is a self-contained “block” in src/diart/blocks
- Reactive Streams: StreamingInference uses RxPY to implement a push-based dataflow (operators in diart.operators)
- Adapter Pattern: SegmentationModel/EmbeddingModel wrap third-party models (PyTorch/ONNX) behind a unified API
- Observer Pattern: sinks (RTTMWriter, WebSocketAudioSource) attach to inference to receive results
- CLI-driven extensibility: console commands in src/diart/console orchestrate pipelines, tuning, serving

##### Putting It All Together
– From StreamingInference, branch into the AI pipeline: SegmentationModel → EmbeddingModel → Incremental Clustering.
– Collect outputs into “Observers” on the right (RTTMWriter, WebSocket send, Benchmark).
– Above or below, show CLI commands invoking the same pipeline with different configs.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Sources
    subgraph "Sources" 
        direction TB
        FileAudioSource["FileAudioSource"]:::sources
        MicrophoneAudioSource["MicrophoneAudioSource"]:::sources
        WebSocketAudioSource["WebSocketAudioSource"]:::sources
    end

    %% Streaming & Control
    subgraph "Streaming & Control"
        direction TB
        StreamingInference["StreamingInference (RxPY)"]:::control
        subgraph "CLI Commands"
            direction TB
            StreamCLI["diart.stream"]:::control
            ServeCLI["diart.serve"]:::control
            ClientCLI["diart.client"]:::control
            TuneCLI["diart.tune"]:::control
            BenchmarkCLI["diart.benchmark"]:::control
        end
    end

    %% Core Pipeline Blocks
    subgraph "Core Pipeline Blocks"
        direction TB
        SegmentationModel["SegmentationModel"]:::pipeline
        EmbeddingModel["EmbeddingModel"]:::pipeline
        OverlapSegmentation["Overlap-Aware Segmentation"]:::pipeline
        Aggregation["SpeakerEmbedding Aggregation"]:::pipeline
        IncrementalClustering["Incremental Clustering"]:::pipeline
    end

    %% Observers / Sinks
    subgraph "Observers / Sinks"
        direction TB
        RTTMWriter["RTTMWriter"]:::sinks
        WebSocketSink["WebSocketAudioSource.send"]:::sinks
        BenchmarkCollector["Benchmark/Eval Collector"]:::sinks
    end

    %% External & Utils
    subgraph "External Dependencies"
        direction TB
        HuggingFace["HuggingFace Hub"]:::external
        OptunaDB[(Optuna DB)]:::external
    end
    Models["Model Adapters"]:::annotation
    Operators["Reactive Operators (RxPY)"]:::annotation
    AudioUtils["Audio Utils"]:::annotation
    VAD["VAD Block"]:::annotation
    ArgDoc["Config & Arg Parsing"]:::annotation

    %% Optimizer
    Optimizer["Optimizer (Optuna)"]:::control

    %% Data Flows
    FileAudioSource -->|audio frames| StreamingInference
    MicrophoneAudioSource -->|audio frames| StreamingInference
    WebSocketAudioSource -->|audio frames| StreamingInference

    StreamingInference -->|frames→segments| SegmentationModel
    SegmentationModel -->|segments| EmbeddingModel
    EmbeddingModel -->|embeddings| IncrementalClustering
    IncrementalClustering -->|speaker labels| RTTMWriter
    IncrementalClustering -->|speaker labels| WebSocketSink
    IncrementalClustering -->|speaker labels| BenchmarkCollector

    %% CLI flows
    StreamCLI -->|invoke| StreamingInference
    ServeCLI -->|invoke| StreamingInference
    ClientCLI -->|invoke| WebSocketAudioSource
    TuneCLI -->|invoke| Optimizer
    BenchmarkCLI -->|invoke| BenchmarkCollector

    %% Optimizer and Benchmark
    Optimizer -->|runs| BenchmarkCollector
    Optimizer -->|writes| OptunaDB

    %% External integrations
    SegmentationModel -->|download models| HuggingFace
    EmbeddingModel -->|download models| HuggingFace
    BenchmarkCollector -->|logs| OptunaDB

    %% Annotations
    StreamingInference --- Operators
    SegmentationModel --- Models
    EmbeddingModel --- Models
    VAD --- SegmentationModel
    AudioUtils --- StreamingInference
    ArgDoc --- StreamCLI

    %% Click Events
    click FileAudioSource "https://github.com/juanmc2005/diart/blob/main/src/diart/sources.py"
    click MicrophoneAudioSource "https://github.com/juanmc2005/diart/blob/main/src/diart/sources.py"
    click WebSocketAudioSource "https://github.com/juanmc2005/diart/blob/main/src/diart/sources.py"
    click SegmentationModel "https://github.com/juanmc2005/diart/blob/main/src/diart/blocks/segmentation.py"
    click EmbeddingModel "https://github.com/juanmc2005/diart/blob/main/src/diart/blocks/embedding.py"
    click OverlapSegmentation "https://github.com/juanmc2005/diart/blob/main/src/diart/blocks/diarization.py"
    click Aggregation "https://github.com/juanmc2005/diart/blob/main/src/diart/blocks/aggregation.py"
    click IncrementalClustering "https://github.com/juanmc2005/diart/blob/main/src/diart/blocks/clustering.py"
    click StreamingInference "https://github.com/juanmc2005/diart/blob/main/src/diart/inference.py"
    click StreamCLI "https://github.com/juanmc2005/diart/blob/main/src/diart/console/stream.py"
    click TuneCLI "https://github.com/juanmc2005/diart/blob/main/src/diart/console/tune.py"
    click BenchmarkCLI "https://github.com/juanmc2005/diart/blob/main/src/diart/console/benchmark.py"
    click ServeCLI "https://github.com/juanmc2005/diart/blob/main/src/diart/console/serve.py"
    click ClientCLI "https://github.com/juanmc2005/diart/blob/main/src/diart/console/client.py"
    click Optimizer "https://github.com/juanmc2005/diart/blob/main/src/diart/optim.py"
    click RTTMWriter "https://github.com/juanmc2005/diart/blob/main/src/diart/sinks.py"
    click WebSocketSink "https://github.com/juanmc2005/diart/blob/main/src/diart/sinks.py"
    click BenchmarkCollector "https://github.com/juanmc2005/diart/blob/main/src/diart/inference.py"
    click Operators "https://github.com/juanmc2005/diart/blob/main/src/diart/operators.py"
    click Models "https://github.com/juanmc2005/diart/blob/main/src/diart/models.py"
    click AudioUtils "https://github.com/juanmc2005/diart/blob/main/src/diart/audio.py"
    click VAD "https://github.com/juanmc2005/diart/blob/main/src/diart/blocks/vad.py"
    click ArgDoc "https://github.com/juanmc2005/diart/blob/main/src/diart/argdoc.py"

    %% Styles
    classDef sources fill:#d1e8b2,stroke:#6b9a22
    classDef control fill:#f9d99a,stroke:#c07c1f
    classDef pipeline fill:#a0c4ff,stroke:#3b5bdb
    classDef sinks fill:#e4c1f9,stroke:#8a2be2
    classDef external fill:#cccccc,stroke:#888888,stroke-dasharray: 5 5
    classDef annotation fill:#ffffff,stroke:#000000,stroke-dasharray: 2 2, font-style:italic
```
