# mawwalker/stt-server architecture

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

- Interactive diagram: https://gitdiagram.com/mawwalker/stt-server
- Repository: https://github.com/mawwalker/stt-server

## Overview

##### Project Type and Purpose
- This is a C++ WebSocket-based streaming ASR (Automatic Speech Recognition) server.
- It exposes two endpoints (`/sttRealtime` for streaming, `/oneshot` for one-shot recognition), manages WebSocket connections, runs voice‐activity detection (VAD), and invokes the sherpa-onnx inference engine on pre-loaded ONNX models.
- It is primarily a backend service (open-source tool) packaged for local or Docker deployment.

##### File Structure Analysis
- Top-level: `main.cpp` (entry), build scripts (`build.sh`, `Makefile`, `CMakeLists.txt`), Docker files, `.env` support.
- `include/` & `src/`: Core components:
- asr_engine.* — model loading & inference orchestration
- oneshot_asr_session.* & asr_session.* — session state machine for streaming vs one-shot
- websocket_server.* & connection_manager — WebSocket acceptor and per-client routing
- model_pool.* — a pool of loaded ASR/VAD models
- logger.* — unified logging
- Deployment/config: `docker-compose.yml`, `Dockerfile`, `.env.example`
- Utilities: `install_sherpa_onnx*.sh`, `setup_env.sh`, `sherpa_config.sh`

##### Key Insights from README
- Unified configuration: `.env` file drives both local and Docker behavior.
- Processing flow: WebSocket connect → ASRSession → VAD → partial/final inference → send JSON.

a. Main Components to Include
- WebSocket Clients (Python, JS, etc.)
- WebSocket ASR Server
- Connection Manager
- Session Factory (ASRSession for streaming, OneShotASRSession)
- Logger
- ASREngine / ModelPool
- sherpa-onnx Inference Engine
- Silero VAD Engine
- Asset Store (ONNX Model files on disk)
b. Relationships & Data Flows
1. Client opens WS → WebSocket Server (Listener)
2. Server creates an ASRSession instance via Connection Manager
3. ASRSession receives PCM audio frames → forwards to VAD in ASREngine
4. VAD marks speech segments → ASREngine invokes sherpa-onnx recognizer
5. Partial/final results → ASRSession packages JSON → sends back over WS
6. ModelPool holds pre-loaded ONNX models for reuse across sessions
c. Architectural Patterns & Principles
- Modular separation: Networking (WebSocket) vs Session logic vs Inference vs I/O
- Resource pooling: `ModelPool` to avoid repeated model loads
- Single responsibility: Each class (Engine, Session, Server, Logger) has a clear domain
- Configuration abstraction: `.env` + `server_config` handle environment detection
d. Technologies & Frameworks
- C++17, WebSocket++ or asio for networking
- sherpa-onnx C++ API for ASR
- Silero VAD ONNX model
- CMake, Makefile, Docker

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Clients["WebSocket Clients"] 

    %% Configuration & Utilities
    subgraph "Configuration & Utilities"
        ServerConfig["ServerConfig"]:::config
        Logger["Logger"]:::utility
    end

    %% Networking Layer
    subgraph "Networking Layer"
        WSServer["WebSocket Server"]:::networking
        ConnectionManager["Connection Manager"]:::networking
    end

    %% Session Logic Layer
    subgraph "Session Logic Layer"
        ASRSession["ASRSession (Streaming)"]:::session
        OneShotSession["OneShotASRSession (One-shot)"]:::session
    end

    %% Inference Layer
    subgraph "Inference Layer"
        VADEngine["Silero VAD Engine"]:::inference
        ASREngine["ASREngine"]:::inference
        ModelPool["ModelPool"]:::inference
    end

    %% Storage Layer
    subgraph "Storage Layer"
        ModelFiles["Model Files (ONNX)"]:::storage
    end

    %% Main & Deployment
    MainCPP["main.cpp"]:::entry
    BuildScripts["Build & Deployment Scripts"]:::scripts

    %% Data Flows
    Clients -->|"opens WS"| WSServer
    WSServer -->|manages| ConnectionManager
    ConnectionManager -->|"creates session"| ASRSession
    ConnectionManager -->|"creates session"| OneShotSession
    ASRSession -->|"audio frames"| VADEngine
    OneShotSession -->|"audio frames"| VADEngine
    VADEngine -->|"speech segments"| ASREngine
    ASREngine -->|"fetch models"| ModelPool
    ModelPool -->|"loads ONNX"| ModelFiles
    ASRSession -->|"JSON results"| Clients
    OneShotSession -->|"JSON results"| Clients

    %% Config & Logger Associations
    ServerConfig --> WSServer
    ServerConfig --> ConnectionManager
    ServerConfig --> ASRSession
    ServerConfig --> OneShotSession
    ServerConfig --> ASREngine
    Logger --- WSServer
    Logger --- ConnectionManager
    Logger --- ASRSession
    Logger --- OneShotSession
    Logger --- ASREngine

    %% Initialization & Scripts
    MainCPP --> WSServer
    MainCPP --> ServerConfig
    MainCPP --> Logger
    BuildScripts --> MainCPP
    BuildScripts --> ServerConfig

    %% Click Events
    click WSServer "https://github.com/mawwalker/stt-server/blob/master/include/websocket_server.h"
    click ConnectionManager "https://github.com/mawwalker/stt-server/blob/master/include/connection_manager.h"
    click ASRSession "https://github.com/mawwalker/stt-server/blob/master/include/asr_session.h"
    click OneShotSession "https://github.com/mawwalker/stt-server/blob/master/include/oneshot_asr_session.h"
    click ASREngine "https://github.com/mawwalker/stt-server/blob/master/include/asr_engine.h"
    click ModelPool "https://github.com/mawwalker/stt-server/blob/master/include/model_pool.h"
    click Logger "https://github.com/mawwalker/stt-server/blob/master/include/logger.h"
    click ServerConfig "https://github.com/mawwalker/stt-server/blob/master/include/server_config.h"
    click MainCPP "https://github.com/mawwalker/stt-server/blob/master/main.cpp"
    click BuildScripts "https://github.com/mawwalker/stt-server/blob/master/CMakeLists.txt"

    %% Styles
    classDef networking fill:#D1E8FF,stroke:#000
    classDef session fill:#DFFFD1,stroke:#000
    classDef inference fill:#FFE2A3,stroke:#000
    classDef storage fill:#E0E0E0,stroke:#000
    classDef config fill:#F0D1FF,stroke:#000
    classDef utility fill:#F5F5F5,stroke:#000
    classDef entry fill:#FFEBE8,stroke:#000
    classDef scripts fill:#E8F8FF,stroke:#000
    class Clients external
```
