# blue-ink-studio/volcano-engine-tts-ui architecture

> Architecture diagram of the GitHub repository blue-ink-studio/volcano-engine-tts-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blue-ink-studio/volcano-engine-tts-ui
- Repository: https://github.com/blue-ink-studio/volcano-engine-tts-ui

## Overview

This is a single-binary Go service that exposes Volcano TTS v3 through an OpenAI-compatible speech API, with guided installation and an admin UI backed by SQLite. The principal workflow is client request → HTTP routing and middleware → speech controller → voice/configuration resolution → Volcano streaming synthesis → audio response. Separate branches cover first-run setup, ongoing voice/settings management, and health/Prometheus observability. The README documents format conversion and these capabilities; sampled TTS/controller source was incomplete, so implementation-level links for those stages are limited to documented relationships.

Main entry points: [`router/router.go`](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/router/router.go) (HTTP Router), [`controller/tts.go`](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/controller/tts.go) (Speech Endpoint), [`store/db.go`](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/store/db.go) (SQLite Store), [`main.go`](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/main.go) (Server Startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["HTTP Runtime"]
  node_main["Server Startup<br/>[main.go]"]
  node_router["HTTP Router<br/>[router.go]"]
  node_middleware["Request Middleware"]
end

subgraph group_tts["Speech Synthesis"]
  node_speech["Speech Endpoint<br/>[tts.go]"]
  node_settings["Runtime Settings"]
  node_voices["Voice Catalog<br/>[voices.go]"]
  node_volcano["Volcano Client"]
end

subgraph group_management["Setup &amp; Admin"]
  node_setup_ui["Setup Workflow<br/>[setup.go]"]
  node_admin_ui["Admin APIs<br/>[admin.go]"]
  node_settings_api["Settings APIs<br/>[settings.go]"]
  node_installer["Install Detection<br/>[bootstrap.go]"]
end

subgraph group_state["Persistent State"]
  node_store[("SQLite Store<br/>[db.go]")]
  node_store_setup["Schema Setup<br/>[setup.go]"]
end

subgraph group_observability["Observability"]
  node_health["Health Endpoint"]
  node_metrics["Metrics Endpoint<br/>[metrics.go]"]
  node_telemetry["Metric Registry<br/>[registry.go]"]
end

node_client(("API Client"))
node_volcano_api(("Volcano TTS v3"))
node_prometheus(("Metrics Scraper"))

node_main -->|"detects mode"| node_installer
node_main -->|"loads config"| node_settings
node_main -->|"starts server"| node_router
node_main -->|"initializes"| node_metrics
node_router -->|"applies"| node_middleware
node_router -->|"dispatches"| node_speech
node_router -->|"dispatches"| node_setup_ui
node_router -->|"dispatches"| node_admin_ui
node_router -->|"dispatches"| node_settings_api
node_router -->|"dispatches"| node_health
node_router -->|"serves"| node_metrics
node_client -->|"requests"| node_router
node_speech -->|"resolves config"| node_settings
node_speech -->|"resolves voice"| node_voices
node_speech -->|"requests synthesis"| node_volcano
node_volcano -->|"streams request"| node_volcano_api
node_volcano_api -->|"returns audio"| node_volcano
node_speech -->|"returns audio"| node_client
node_setup_ui -->|"persists installation"| node_store
node_admin_ui -->|"manages voices"| node_store
node_settings_api -->|"updates settings"| node_store
node_settings_api -->|"reloads runtime"| node_settings
node_installer -->|"opens database"| node_store
node_store_setup -->|"initializes schema"| node_store
node_metrics -->|"exports metrics"| node_telemetry
node_prometheus -->|"scrapes"| node_router

click node_main "https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/main.go"
click node_router "https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/router/router.go"
click node_middleware "https://github.com/blue-ink-studio/volcano-engine-tts-ui/tree/main/middleware"
click node_speech "https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/controller/tts.go"
click node_settings "https://github.com/blue-ink-studio/volcano-engine-tts-ui/tree/main/setting"
click node_voices "https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/store/voices.go"
click node_volcano "https://github.com/blue-ink-studio/volcano-engine-tts-ui/tree/main/adapter/volcano"
click node_setup_ui "https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/controller/setup.go"
click node_admin_ui "https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/controller/admin.go"
click node_settings_api "https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/controller/settings.go"
click node_installer "https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/installer/bootstrap.go"
click node_store "https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/store/db.go"
click node_store_setup "https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/store/setup.go"
click node_health "https://github.com/blue-ink-studio/volcano-engine-tts-ui/tree/main/controller"
click node_metrics "https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/metrics/metrics.go"
click node_telemetry "https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/telemetry/registry.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_router,node_middleware,node_client toneBlue
class node_speech,node_settings,node_voices,node_volcano toneAmber
class node_setup_ui,node_admin_ui,node_settings_api,node_installer toneMint
class node_store,node_store_setup toneRose
class node_health,node_metrics,node_telemetry,node_volcano_api,node_prometheus toneIndigo
```

## Components

### HTTP Runtime

- [Server Startup](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/main.go): `main.go`
- [HTTP Router](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/router/router.go): `router/router.go`
- [Request Middleware](https://github.com/blue-ink-studio/volcano-engine-tts-ui/tree/main/middleware): `middleware`

### Speech Synthesis

- [Speech Endpoint](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/controller/tts.go): `controller/tts.go`
- [Runtime Settings](https://github.com/blue-ink-studio/volcano-engine-tts-ui/tree/main/setting): `setting`
- [Voice Catalog](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/store/voices.go): `store/voices.go`
- [Volcano Client](https://github.com/blue-ink-studio/volcano-engine-tts-ui/tree/main/adapter/volcano): `adapter/volcano`

### Setup & Admin

- [Setup Workflow](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/controller/setup.go): `controller/setup.go`
- [Admin APIs](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/controller/admin.go): `controller/admin.go`
- [Settings APIs](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/controller/settings.go): `controller/settings.go`
- [Install Detection](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/installer/bootstrap.go): `installer/bootstrap.go`

### Persistent State

- [SQLite Store](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/store/db.go): `store/db.go`
- [Schema Setup](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/store/setup.go): `store/setup.go`

### Observability

- [Health Endpoint](https://github.com/blue-ink-studio/volcano-engine-tts-ui/tree/main/controller): `controller`
- [Metrics Endpoint](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/metrics/metrics.go): `metrics/metrics.go`
- [Metric Registry](https://github.com/blue-ink-studio/volcano-engine-tts-ui/blob/main/telemetry/registry.go): `telemetry/registry.go`

### Other components

- **API Client**
- **Volcano TTS v3**
- **Metrics Scraper**

## Connections

- Server Startup → Install Detection: detects mode
- Server Startup → Runtime Settings: loads config
- Server Startup → HTTP Router: starts server
- Server Startup → Metrics Endpoint: initializes
- HTTP Router → Request Middleware: applies
- HTTP Router → Speech Endpoint: dispatches
- HTTP Router → Setup Workflow: dispatches
- HTTP Router → Admin APIs: dispatches
- HTTP Router → Settings APIs: dispatches
- HTTP Router → Health Endpoint: dispatches
- HTTP Router → Metrics Endpoint: serves
- API Client → HTTP Router: requests
- Speech Endpoint → Runtime Settings: resolves config
- Speech Endpoint → Voice Catalog: resolves voice
- Speech Endpoint → Volcano Client: requests synthesis
- Volcano Client → Volcano TTS v3: streams request
- Volcano TTS v3 → Volcano Client: returns audio
- Speech Endpoint → API Client: returns audio
- Setup Workflow → SQLite Store: persists installation
- Admin APIs → SQLite Store: manages voices
- Settings APIs → SQLite Store: updates settings
- Settings APIs → Runtime Settings: reloads runtime
- Install Detection → SQLite Store: opens database
- Schema Setup → SQLite Store: initializes schema
- Metrics Endpoint → Metric Registry: exports metrics
- Metrics Scraper → HTTP Router: scrapes