# phyce/narration-studio architecture

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

- Interactive diagram: https://gitdiagram.com/phyce/narration-studio
- Repository: https://github.com/phyce/narration-studio

## Overview

Narration Studio is a desktop text-to-speech application with a Vue interface and Go runtime, plus an HTTP mode for serving TTS requests. The main workflow is selecting an engine/model/voice, composing or previewing script text, generating speech, and playing or saving audio; profiles configure reusable voice settings. The graph includes the documented local/API engines and server capability. Some subsystem wiring is inferred only from the README and tree, so uncertain links are omitted; unsampled features are represented by their existing directories.

Main entry points: [`app/tts/engine/engine.go`](https://github.com/phyce/narration-studio/blob/main/app/tts/engine/engine.go) (Engine interface), [`app/tts/tts.go`](https://github.com/phyce/narration-studio/blob/main/app/tts/tts.go) (TTS workflow), [`app.go`](https://github.com/phyce/narration-studio/blob/main/app.go) (Application API), [`app/tts/modelManager/modelManager.go`](https://github.com/phyce/narration-studio/blob/main/app/tts/modelManager/modelManager.go) (Engine registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Desktop interface"]
  node_ui["Vue pages<br/>[App.vue]"]
  node_ui_bridge["Wails bindings<br/>[App.js]"]
end

subgraph group_runtime["Application runtime"]
  node_app["Application API<br/>[app.go]"]
  node_config["Configuration<br/>[config.go]"]
end

subgraph group_speech["Speech generation"]
  node_profiles["Profile manager<br/>[profile_manager.go]"]
  node_profile_store[("Profile files<br/>[storage.go]")]
  node_tts["TTS workflow<br/>[tts.go]"]
  node_model_manager["Engine registry<br/>[modelManager.go]"]
  node_engine_contract["Engine interface<br/>[engine.go]"]
  node_piper["Piper engine<br/>[piper.go]"]
  node_mssapi["Microsoft engines<br/>[msssapi4.go]"]
  node_elevenlabs["ElevenLabs engine<br/>[elevenlabs.go]"]
  node_openai["OpenAI engine<br/>[openai.go]"]
  node_google["Google engine<br/>[google.go]"]
  node_gemini["Gemini engine<br/>[gemini.go]"]
  node_audio["Audio playback<br/>[audio.go]"]
end

subgraph group_service["HTTP service"]
  node_http_service["HTTP server<br/>[http.go]"]
  node_tts_handlers["TTS handlers<br/>[tts_handlers.go]"]
  node_routes["HTTP routes<br/>[routes.go]"]
  node_engine_routes["Engine routes<br/>[engines.go]"]
end

node_user(("Desktop user"))
node_http_client(("HTTP client"))
node_providers{{"Remote TTS APIs"}}

node_user -->|"uses"| node_ui
node_ui -->|"calls"| node_ui_bridge
node_ui_bridge -->|"invokes"| node_app
node_app -->|"requests speech"| node_tts
node_app -->|"reads settings"| node_config
node_app -->|"manages profiles"| node_profiles
node_profiles -->|"reads/writes"| node_profile_store
node_tts -->|"uses settings"| node_profiles
node_tts -->|"selects engine"| node_model_manager
node_model_manager -->|"reads toggles"| node_config
node_model_manager -->|"manages instances"| node_engine_contract
node_engine_contract -->|"implemented by"| node_piper
node_engine_contract -->|"implemented by"| node_mssapi
node_engine_contract -->|"implemented by"| node_elevenlabs
node_engine_contract -->|"implemented by"| node_openai
node_engine_contract -->|"implemented by"| node_google
node_engine_contract -->|"implemented by"| node_gemini
node_tts -->|"plays output"| node_audio
node_http_client -->|"sends requests"| node_http_service
node_http_service -->|"dispatches"| node_routes
node_routes -->|"routes metadata"| node_engine_routes
node_routes -->|"routes speech"| node_tts_handlers
node_tts_handlers -->|"requests speech"| node_tts
node_engine_routes -->|"queries engines"| node_model_manager
node_elevenlabs -.->|"calls API"| node_providers
node_openai -.->|"calls API"| node_providers
node_google -.->|"calls API"| node_providers
node_gemini -.->|"calls API"| node_providers

click node_ui "https://github.com/phyce/narration-studio/blob/main/frontend/src/App.vue"
click node_ui_bridge "https://github.com/phyce/narration-studio/blob/main/frontend/wailsjs/go/main/App.js"
click node_app "https://github.com/phyce/narration-studio/blob/main/app.go"
click node_config "https://github.com/phyce/narration-studio/blob/main/app/config/config.go"
click node_profiles "https://github.com/phyce/narration-studio/blob/main/app/tts/profile/profile_manager.go"
click node_profile_store "https://github.com/phyce/narration-studio/blob/main/app/tts/profile/storage.go"
click node_tts "https://github.com/phyce/narration-studio/blob/main/app/tts/tts.go"
click node_model_manager "https://github.com/phyce/narration-studio/blob/main/app/tts/modelManager/modelManager.go"
click node_engine_contract "https://github.com/phyce/narration-studio/blob/main/app/tts/engine/engine.go"
click node_piper "https://github.com/phyce/narration-studio/blob/main/app/tts/engine/piper/piper.go"
click node_mssapi "https://github.com/phyce/narration-studio/blob/main/app/tts/engine/mssapi4/msssapi4.go"
click node_elevenlabs "https://github.com/phyce/narration-studio/blob/main/app/tts/engine/elevenlabs/elevenlabs.go"
click node_openai "https://github.com/phyce/narration-studio/blob/main/app/tts/engine/openai/openai.go"
click node_google "https://github.com/phyce/narration-studio/blob/main/app/tts/engine/google/google.go"
click node_gemini "https://github.com/phyce/narration-studio/blob/main/app/tts/engine/gemini/gemini.go"
click node_audio "https://github.com/phyce/narration-studio/blob/main/app/common/audio/audio.go"
click node_http_service "https://github.com/phyce/narration-studio/blob/main/app/server/http/http.go"
click node_tts_handlers "https://github.com/phyce/narration-studio/blob/main/app/server/http/tts_handlers.go"
click node_routes "https://github.com/phyce/narration-studio/blob/main/app/server/http/routes.go"
click node_engine_routes "https://github.com/phyce/narration-studio/blob/main/app/server/http/routes/engines/engines.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_ui,node_ui_bridge,node_user,node_http_client toneBlue
class node_app,node_config toneAmber
class node_profiles,node_profile_store,node_tts,node_model_manager,node_engine_contract,node_piper,node_mssapi,node_elevenlabs,node_openai,node_google,node_gemini,node_audio,node_providers toneMint
class node_http_service,node_tts_handlers,node_routes,node_engine_routes toneRose
```

## Components

### Desktop interface

- [Vue pages](https://github.com/phyce/narration-studio/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [Wails bindings](https://github.com/phyce/narration-studio/blob/main/frontend/wailsjs/go/main/App.js): `frontend/wailsjs/go/main/App.js`

### Application runtime

- [Application API](https://github.com/phyce/narration-studio/blob/main/app.go): `app.go`
- [Configuration](https://github.com/phyce/narration-studio/blob/main/app/config/config.go): `app/config/config.go`

### Speech generation

- [Profile manager](https://github.com/phyce/narration-studio/blob/main/app/tts/profile/profile_manager.go): `app/tts/profile/profile_manager.go`
- [Profile files](https://github.com/phyce/narration-studio/blob/main/app/tts/profile/storage.go): `app/tts/profile/storage.go`
- [TTS workflow](https://github.com/phyce/narration-studio/blob/main/app/tts/tts.go): `app/tts/tts.go`
- [Engine registry](https://github.com/phyce/narration-studio/blob/main/app/tts/modelManager/modelManager.go): `app/tts/modelManager/modelManager.go`
- [Engine interface](https://github.com/phyce/narration-studio/blob/main/app/tts/engine/engine.go): `app/tts/engine/engine.go`
- [Piper engine](https://github.com/phyce/narration-studio/blob/main/app/tts/engine/piper/piper.go): `app/tts/engine/piper/piper.go`
- [Microsoft engines](https://github.com/phyce/narration-studio/blob/main/app/tts/engine/mssapi4/msssapi4.go): `app/tts/engine/mssapi4/msssapi4.go`
- [ElevenLabs engine](https://github.com/phyce/narration-studio/blob/main/app/tts/engine/elevenlabs/elevenlabs.go): `app/tts/engine/elevenlabs/elevenlabs.go`
- [OpenAI engine](https://github.com/phyce/narration-studio/blob/main/app/tts/engine/openai/openai.go): `app/tts/engine/openai/openai.go`
- [Google engine](https://github.com/phyce/narration-studio/blob/main/app/tts/engine/google/google.go): `app/tts/engine/google/google.go`
- [Gemini engine](https://github.com/phyce/narration-studio/blob/main/app/tts/engine/gemini/gemini.go): `app/tts/engine/gemini/gemini.go`
- [Audio playback](https://github.com/phyce/narration-studio/blob/main/app/common/audio/audio.go): `app/common/audio/audio.go`

### HTTP service

- [HTTP server](https://github.com/phyce/narration-studio/blob/main/app/server/http/http.go): `app/server/http/http.go`
- [TTS handlers](https://github.com/phyce/narration-studio/blob/main/app/server/http/tts_handlers.go): `app/server/http/tts_handlers.go`
- [HTTP routes](https://github.com/phyce/narration-studio/blob/main/app/server/http/routes.go): `app/server/http/routes.go`
- [Engine routes](https://github.com/phyce/narration-studio/blob/main/app/server/http/routes/engines/engines.go): `app/server/http/routes/engines/engines.go`

### Other components

- **Desktop user**
- **HTTP client**
- **Remote TTS APIs**

## Connections

- Desktop user → Vue pages: uses
- Vue pages → Wails bindings: calls
- Wails bindings → Application API: invokes
- Application API → TTS workflow: requests speech
- Application API → Configuration: reads settings
- Application API → Profile manager: manages profiles
- Profile manager → Profile files: reads/writes
- TTS workflow → Profile manager: uses settings
- TTS workflow → Engine registry: selects engine
- Engine registry → Configuration: reads toggles
- Engine registry → Engine interface: manages instances
- Engine interface → Piper engine: implemented by
- Engine interface → Microsoft engines: implemented by
- Engine interface → ElevenLabs engine: implemented by
- Engine interface → OpenAI engine: implemented by
- Engine interface → Google engine: implemented by
- Engine interface → Gemini engine: implemented by
- TTS workflow → Audio playback: plays output
- HTTP client → HTTP server: sends requests
- HTTP server → HTTP routes: dispatches
- HTTP routes → Engine routes: routes metadata
- HTTP routes → TTS handlers: routes speech
- TTS handlers → TTS workflow: requests speech
- Engine routes → Engine registry: queries engines
- ElevenLabs engine → Remote TTS APIs: calls API
- OpenAI engine → Remote TTS APIs: calls API
- Google engine → Remote TTS APIs: calls API
- Gemini engine → Remote TTS APIs: calls API