# metil-holoai/holotable-middleware architecture

> Architecture diagram of the GitHub repository metil-holoai/holotable-middleware, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/metil-holoai/holotable-middleware
- Repository: https://github.com/metil-holoai/holotable-middleware

## Overview

##### Project type and purpose
- This is a Go-based middleware service (“HoloTable-Middleware”) that sits between various input sources (text, microphone, speech-to-text), a set of AI content-generation workflows (GIF, image, video, 3D, intent detection, etc.), a database, and an external Unity application.
- It exposes REST and WebSocket endpoints for real-time or on-demand content requests, orchestrates prompts and workflows defined in YAML, and handles storage and retrieval of generated assets.

##### File structure
- Top-level directories:
- cmd/holoai: the entrypoint (main.go)
- config: all YAML workflow definitions and general configuration
- internal: core code, subdivided into:
– callers: orchestration of content extraction, generation, storage, prompt loading
– config: environment loading and struct definitions
– database: persistence layer
– endpoints: HTTP REST API and WebSocket server
– listeners: adapters for text, microphone, Vosk speech recognition
– unityserver: export logic and structs for Unity integration
– utils: error checking and shutdown handling
- Go.mod/go.sum define dependencies.
- .github/workflows contains CI build test definition.

##### Extract insights from README
- Minimal top-level README just points to “Run the Middleware” and “Add a Workflow” docs, confirming that the core functionality is dynamic workflow orchestration.

##### Elements
- Adapters (listeners, endpoints)
- Core logic (callers)
- Infrastructure (database, external services)
- YAML config files alongside the configuration loader component

##### Final advice
- Be as detailed as possible: break out each listener type, each caller sub-component, and each external model if it helps clarity.
- This approach ensures any new engineer or stakeholder immediately understands how input enters the system, how workflows are executed, and how results are delivered or stored.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Adapters
    subgraph "Input Adapters"
        direction TB
        TextListener["TextListener"]:::adapter
        MicrophoneListener["MicrophoneListener"]:::adapter
        VoskListener["VoskListener"]:::adapter
    end

    %% Configuration Loader
    subgraph "Configuration Loader"
        direction TB
        EnvLoader["Env Loader"]:::config
        YAMLLoader["YAML Workflow Loader"]:::config
        Workflows["Workflow Definitions"]:::config
    end

    %% Core Orchestrator
    subgraph "Core Orchestrator"
        direction TB
        LoadPrompt["LoadPrompt"]:::core
        LoadPromptHelper["LoadPromptHelper"]:::core
        ContentExtraction["ContentExtraction"]:::core
        ContentGeneration["ContentGeneration"]:::core
        ContentStorage["ContentStorage"]:::core
    end

    %% External AI Services
    AdditionalModels["External AI Services<br/>(AdditionalModels)"]:::external

    %% Persistence Layer
    Database["Database"]:::infra

    %% API Layer
    subgraph "API Layer"
        direction TB
        RESTAPI["REST API"]:::api
        WebSocket["WebSocket"]:::api
    end

    %% Unity Integration
    subgraph "Unity Integration"
        direction TB
        UnityServer["UnityServer"]:::unity
        Exporter["Export Logic"]:::unity
        AssetStruct["AssetStruct"]:::unity
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Logger["Logger"]:::util
        ErrorHandler["Error Handler"]:::util
        Shutdown["Graceful Shutdown"]:::util
    end

    %% Data Flows
    TextListener -->|input| LoadPrompt
    MicrophoneListener -->|input| LoadPrompt
    VoskListener -->|input| LoadPrompt

    EnvLoader --> LoadPrompt
    YAMLLoader --> LoadPrompt
    Workflows --> LoadPrompt

    LoadPrompt --> LoadPromptHelper
    LoadPromptHelper --> ContentExtraction
    ContentExtraction --> ContentGeneration
    ContentGeneration --> ContentStorage

    ContentGeneration -->|calls| AdditionalModels
    ContentStorage -->|writes| Database

    ContentStorage -->|response| RESTAPI
    ContentStorage -->|stream| WebSocket

    Database -->|assets| UnityServer
    UnityServer --> Exporter
    Exporter --> AssetStruct

    Logger --> LoadPrompt
    Logger --> RESTAPI
    Logger --> UnityServer

    ErrorHandler --> LoadPrompt
    ErrorHandler --> ContentGeneration

    Shutdown --> RESTAPI
    Shutdown --> WebSocket
    Shutdown --> UnityServer

    %% Click Events
    click TextListener "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/listeners/text.go"
    click MicrophoneListener "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/listeners/microphone.go"
    click VoskListener "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/listeners/vosk.go"
    click EnvLoader "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/config/env.go"
    click YAMLLoader "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/config/loader.go"
    click Workflows "https://github.com/metil-holoai/holotable-middleware/tree/main/config/"
    click LoadPrompt "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/callers/loadprompt.go"
    click LoadPromptHelper "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/callers/loadprompt_helper.go"
    click ContentExtraction "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/callers/contentextraction.go"
    click ContentGeneration "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/callers/contentgen.go"
    click ContentStorage "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/callers/contentstorage.go"
    click AdditionalModels "https://github.com/metil-holoai/holotable-middleware/tree/main/config/additional_models/"
    click Database "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/database/database.go"
    click RESTAPI "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/endpoints/restapi/restapi.go"
    click WebSocket "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/endpoints/websocket/websocket.go"
    click UnityServer "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/unityserver/unityserver.go"
    click Exporter "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/unityserver/export.go"
    click AssetStruct "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/unityserver/assetstruct/asset_struct.go"
    click Logger "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/config/logger.go"
    click ErrorHandler "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/utils/checkforerror.go"
    click Shutdown "https://github.com/metil-holoai/holotable-middleware/blob/main/internal/utils/waitforinterrupt.go"

    %% Styles
    classDef adapter fill:#D6E9C6,stroke:#3C763D,color:#3C763D;
    classDef config fill:#FCF8E3,stroke:#8A6D3B,color:#8A6D3B;
    classDef core fill:#D9EDF7,stroke:#31708F,color:#31708F;
    classDef external fill:#F2DEDE,stroke:#A94442,color:#A94442;
    classDef infra fill:#E7E7E7,stroke:#666666,color:#333333;
    classDef api fill:#DFF0D8,stroke:#3C763D,color:#3C763D;
    classDef unity fill:#EBDEF0,stroke:#8E44AD,color:#512E5F;
    classDef util fill:#FEF2E4,stroke:#B7950B,color:#7D6608;
```
