# narcotic-sh/senko architecture

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

- Interactive diagram: https://gitdiagram.com/narcotic-sh/senko
- Repository: https://github.com/narcotic-sh/senko

## Overview

##### Project type and purpose
- Senko is a high-performance speaker diarization pipeline written in Python, with a C++ submodule for feature extraction.
- It implements a four-stage data-processing pipeline: VAD → Fbank feature extraction → speaker embedding inference → clustering → output formatting.

##### File structure
- Top level:
- `senko/` – the core Python package containing orchestrator (`diarizer.py`), modules (`camplusplus.py`, `cluster/`, `fbank_extractor/`), and utilities.
- `models/` – pre-trained model artifacts and configs.
- `examples/`, `evaluation/`, `tracing/` – scripts for demonstration, benchmarking, and tracing/optimizations.
- `pyproject.toml`, `CMakeLists.txt` – build/config specifications for Python packaging and C++ fbank extraction.
- Inside `senko/fbank_extractor/`: a CMake-based C++ library for mel-filterbank extraction.
- Inside `senko/cluster/`: two implementations (CPU and GPU via RAPIDS cuML), with YAML configs under `conf/`.

##### README for insights
- Confirms the four-stage pipeline and external dependencies (Pyannote or Silero for VAD, PyTorch for embeddings, RAPIDS for GPU clustering).
- Describes use cases, performance targets, and guidance on GPU vs CPU execution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    CLI["CLI/API Usage<br>(examples/diarize.py)"]:::python
    DIAR["Diarizer API Class<br>(senko/diarizer.py)"]:::python
    InputLoader["Input Loader"]:::python
    VAD["VAD Module<br>(Pyannote/Silero)"]:::python
    FBANK["Fbank Extractor<br>(C++)"]:::cxx
    EMB["Embedding Generator<br>(CAM++ PyTorch)<br>(CPU/GPU/MPS)"]:::python
    CL_CPU["Clustering (CPU)"]:::python
    CL_GPU["Clustering (GPU CuML)"]:::gpu
    POST["Post-processor & Formatter"]:::python

    STORE["Models & Config Store"]:::external
    SPEC_CONF["spectral.yaml"]:::external
    UMAP_CONF["umap_hdbscan.yaml"]:::external
    UTILS["Utilities<br>(senko/utils.py)"]:::python
    PATHS["Paths & Resource Locators<br>(senko/paths.py)"]:::python

    subgraph "Evaluation & Tracing" 
        direction TB
        EVAL["Evaluation Scripts"]:::python
        TRAC["Tracing & Optimization Scripts"]:::python
    end

    %% Data Flow
    CLI -->|invokes| DIAR
    DIAR -->|loads WAV file| InputLoader
    InputLoader -->|audio stream| VAD
    VAD -->|VAD masks| FBANK
    FBANK -->|mel-spectrogram matrix| EMB
    EMB -->|embeddings tensor| CL_CPU
    EMB -->|embeddings tensor| CL_GPU
    CL_CPU -->|assignments| POST
    CL_GPU -->|assignments| POST
    POST -->|JSON/RTTM outputs| DIAR

    %% Resources
    STORE -->|VAD models| VAD
    STORE -->|embedding model| EMB
    STORE -->|cluster configs| CL_CPU
    STORE -->|cluster configs| CL_GPU
    SPEC_CONF -->|spectral config| CL_CPU
    UMAP_CONF -->|UMAP+HDBSCAN config| CL_GPU
    UTILS -->|helper functions| DIAR
    PATHS -->|resource locators| DIAR

    %% Side scripts
    DIAR --> EVAL
    DIAR --> TRAC

    %% Click Events
    click CLI "https://github.com/narcotic-sh/senko/blob/main/examples/diarize.py"
    click DIAR "https://github.com/narcotic-sh/senko/blob/main/senko/diarizer.py"
    click InputLoader "https://github.com/narcotic-sh/senko/blob/main/senko/diarizer.py"
    click VAD "https://github.com/narcotic-sh/senko/blob/main/senko/diarizer.py"
    click FBANK "https://github.com/narcotic-sh/senko/tree/main/senko/fbank_extractor/"
    click EMB "https://github.com/narcotic-sh/senko/blob/main/senko/camplusplus.py"
    click CL_CPU "https://github.com/narcotic-sh/senko/blob/main/senko/cluster/cluster_cpu.py"
    click CL_GPU "https://github.com/narcotic-sh/senko/blob/main/senko/cluster/cluster_gpu.py"
    click SPEC_CONF "https://github.com/narcotic-sh/senko/blob/main/senko/cluster/conf/spectral.yaml"
    click UMAP_CONF "https://github.com/narcotic-sh/senko/blob/main/senko/cluster/conf/umap_hdbscan.yaml"
    click POST "https://github.com/narcotic-sh/senko/blob/main/senko/diarizer.py"
    click STORE "https://github.com/narcotic-sh/senko/tree/main/models/"
    click UTILS "https://github.com/narcotic-sh/senko/blob/main/senko/utils.py"
    click PATHS "https://github.com/narcotic-sh/senko/blob/main/senko/paths.py"
    click EVAL "https://github.com/narcotic-sh/senko/tree/main/evaluation/"
    click TRAC "https://github.com/narcotic-sh/senko/tree/main/tracing/"

    %% Styles
    classDef python fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef cxx fill:#98FB98,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef gpu fill:#DDA0DD,stroke:#333,stroke-width:1px
```
