# farshed/sage architecture

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

- Interactive diagram: https://gitdiagram.com/farshed/sage
- Repository: https://github.com/farshed/sage

## Overview

##### Project Type and Purpose
- Sage is a full-stack self-hosted application that leverages state‐of‐the‐art open-source speech processing models.
- It supports speech-to-text (using Whisper) and text-to-speech (via Kokoro modules) for conversing with large language models.
- The project supports multiple LLM providers (Ollama, OpenAI, Anthropic, and more) with configuration provided via a .env file.
- It can run either as a Docker container or natively, with separate pipelines in Rust (Kokoro and Whisper components) and JavaScript/TypeScript (the application server and frontend UI).

##### Analysis of the File Structure
- At the top level, files like index.ts, package.json, tsconfig.json, and public/ indicate a JavaScript/TypeScript application that serves a web interface.
- The public directory hosts assets for the browser (e.g., ui.html, wav-worker.js), representing the frontend.
- The Kokoro directory contains Rust code (with Cargo files and a src folder) divided into submodules:
– src/onn: Likely dealing with ONNX-based speech processing/model inference.
– src/tts: Modules for text-to-speech components (tokenization, normalization, phonemizer, vocab, etc.).
– src/utils: Utility functions (file I/O and WAV processing) supporting Kokoro’s functionalities.
- The Whisper directory is another Rust project (with its own Cargo files) designated for speech-to-text conversion.
- Dockerfile and other deployment scripts (setup-unix.sh, setup-win.bat) indicate built-in support for containerization and native deployments.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global Entities
    U("User"):::external

    %% Presentation Layer
    subgraph "Presentation Layer"
        FE("Frontend UI (public/ui.html, wav-worker.js)"):::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BA("Backend API (index.ts, package.json, tsconfig.json) - reads .env"):::backend
    end

    %% Processing Engines
    subgraph "Processing Engines"
        STT("Whisper STT (Rust)"):::rust
        LLM("LLM Providers (Ollama,OpenAI,Anthropic,etc.)"):::external
        subgraph "Kokoro Engine"
            ONNX("ONNX-based Processing (kokoro/src/onn)"):::rust
            TTS("Text-to-Speech (kokoro/src/tts)"):::rust
            UTIL("Utility Functions (kokoro/src/utils)"):::rust
        end
    end

    %% Deployment Layer
    D("Docker/Deployment (Dockerfile & scripts)"):::deployment

    %% Connections
    U -->|"sends_speech_input"| FE
    FE -->|"forwards_data"| BA
    BA -->|"sends_audio_data"| STT
    STT -->|"returns_transcription"| BA
    BA -->|"sends_text"| LLM
    LLM -->|"returns_response"| BA
    BA -->|"triggers_inference"| ONNX
    ONNX -->|"returns_inference"| BA
    BA -->|"requests_tts"| TTS
    TTS -->|"delivers_audio"| FE

    %% Deployment connection (illustrative)
    BA -.->|"deployed_via"| D

    %% Click Events
    click FE "https://github.com/farshed/sage/tree/main/public/"
    click BA "https://github.com/farshed/sage/blob/main/index.ts"
    click STT "https://github.com/farshed/sage/blob/main/whisper/src/main.rs"
    click ONNX "https://github.com/farshed/sage/tree/main/kokoro/src/onn/"
    click TTS "https://github.com/farshed/sage/tree/main/kokoro/src/tts/"
    click UTIL "https://github.com/farshed/sage/tree/main/kokoro/src/utils/"
    click D "https://github.com/farshed/sage/tree/main/Dockerfile"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef backend fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef rust fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef deployment fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
```
