# meshag-ai/meshag architecture

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

- Interactive diagram: https://gitdiagram.com/meshag-ai/meshag
- Repository: https://github.com/meshag-ai/meshag

## Overview

##### Project type and purpose
- This is a Rust-based, event-driven, distributed microservices application called **MeshAG**.
- Its goal is to orchestrate AI agents (STT, LLM, TTS) in real-time conversational scenarios over WebRTC, using NATS JetStream for messaging and a Redis-compatible Valkey store for configuration.

##### File structure
- Top-level workspace with multiple Cargo crates under `/crates` and `/services`.
- `crates/connectors`: Connector traits and provider implementations (OpenAI, Deepgram, ElevenLabs, Twilio, Daily.co, etc.)
- `crates/orchestrator`: Core pipeline router and configuration logic
- `crates/service-common`: Shared HTTP server setup, request handlers, types
- `crates/shared`: Cross-service utilities, queue abstractions
- `/services`: Four independent binaries, each in its own Rust project:
- `stt-service` (port 8081)
- `llm-service` (port 8082)
- `tts-service` (port 8083)
- `transport-service` (port 8084)
- Docker directory holds Dockerfiles per service and `docker-compose.yml` for local infra (NATS, Valkey, metrics).

##### README for additional insights
- Client App ↔ Transport Service ↔ Daily.co API
- Transport → Valkey → NATS JetStream → [STT, LLM, TTS] → back through pipeline.
- Key technologies: NATS JetStream, Valkey (Redis), Daily.co (WebRTC), pluggable connectors.

##### Detailed capture of essential elements
- Service ports, protocol (HTTP, WebSocket, Pub/Sub), config store TTL cleanup, pipeline routing logic.
- “pipeline flow” ordering: transport → stt → llm → tts → transport.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Client["Client App<br>(Web/Mobile)"]:::external

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Daily["Daily.co WebRTC API"]:::external
        Valkey["Valkey Store<br>(Redis)"]:::external
        NATS["NATS JetStream"]:::external
        DockerCompose["docker-compose.yml"]:::infrastructure
        DockerTransport["Dockerfile.transport-service"]:::infrastructure
        DockerSTT["Dockerfile.stt-service"]:::infrastructure
        DockerLLM["Dockerfile.llm-service"]:::infrastructure
        DockerTTS["Dockerfile.tts-service"]:::infrastructure
    end

    %% Internal Services
    subgraph "Services"
        direction TB
        Transport["Transport Service<br>(8084)"]:::internal
        STT["STT Service<br>(8081)"]:::internal
        LLM["LLM Service<br>(8082)"]:::internal
        TTS["TTS Service<br>(8083)"]:::internal
    end

    %% Code Modules
    subgraph "Code Modules"
        direction TB
        Connectors["Connector Traits & Providers"]:::code
        Orchestrator["Orchestrator Router & Config"]:::code
        ValkeyCfg["Valkey Config Integration"]:::code
        ServiceCommon["Service Common<br>Server & Handlers"]:::code
        SharedQueue["Queue Abstractions (NATS)"]:::code
        SharedLib["Shared Utility Lib"]:::code
    end

    %% Data Flows
    Client -->|"openWebRTCsession"| Transport
    Transport -->|"WebRTC traffic"| Daily
    Transport -->|"write/readSessionConfig"| Valkey
    Transport -->|"publishstart-session"| NATS

    NATS -->|"audioEvents"| STT
    STT -->|"publishText"| NATS
    NATS -->|"textRequests"| LLM
    LLM -->|"textResponses"| NATS
    NATS -->|"ttsRequests"| TTS
    TTS -->|"audioResponses"| NATS

    NATS -->|"finalAudio"| Transport
    Transport -->|"forwardAudio"| Client

    %% Click Events
    click Transport "https://github.com/meshag-ai/meshag/blob/main/services/transport-service/src/main.rs"
    click STT "https://github.com/meshag-ai/meshag/blob/main/services/stt-service/src/main.rs"
    click LLM "https://github.com/meshag-ai/meshag/blob/main/services/llm-service/src/main.rs"
    click TTS "https://github.com/meshag-ai/meshag/blob/main/services/tts-service/src/main.rs"
    click Connectors "https://github.com/meshag-ai/meshag/blob/main/crates/connectors/src/lib.rs"
    click Orchestrator "https://github.com/meshag-ai/meshag/blob/main/crates/orchestrator/src/router.rs"
    click Orchestrator "https://github.com/meshag-ai/meshag/blob/main/crates/orchestrator/src/config.rs"
    click ValkeyCfg "https://github.com/meshag-ai/meshag/blob/main/crates/orchestrator/src/valkey_config.rs"
    click ServiceCommon "https://github.com/meshag-ai/meshag/blob/main/crates/service-common/src/server.rs"
    click ServiceCommon "https://github.com/meshag-ai/meshag/blob/main/crates/service-common/src/handlers.rs"
    click ServiceCommon "https://github.com/meshag-ai/meshag/blob/main/crates/service-common/src/types.rs"
    click SharedQueue "https://github.com/meshag-ai/meshag/blob/main/crates/shared/src/queue.rs"
    click SharedLib "https://github.com/meshag-ai/meshag/blob/main/crates/shared/src/lib.rs"
    click DockerCompose "https://github.com/meshag-ai/meshag/blob/main/docker/docker-compose.yml"
    click DockerTransport "https://github.com/meshag-ai/meshag/blob/main/docker/Dockerfile.transport-service"
    click DockerSTT "https://github.com/meshag-ai/meshag/blob/main/docker/Dockerfile.stt-service"
    click DockerLLM "https://github.com/meshag-ai/meshag/blob/main/docker/Dockerfile.llm-service"
    click DockerTTS "https://github.com/meshag-ai/meshag/blob/main/docker/Dockerfile.tts-service"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef infrastructure fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef code fill:#D3D3D3,stroke:#333,stroke-width:1px
```
