# cutedogspark/bluemagpie-tts-portal architecture

> Architecture diagram of the GitHub repository cutedogspark/bluemagpie-tts-portal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cutedogspark/bluemagpie-tts-portal
- Repository: https://github.com/cutedogspark/bluemagpie-tts-portal

## Overview

1. **Repository purpose**
   - This repo is a **serving layer + browser portal** around the BlueMagpie-TTS model, not the model implementation itself.
   - It is split into two independently deployable pieces: a **FastAPI inference service** and a **static front-end portal**.

2. **Top-level system boundary**
   - The user interacts with the **portal in the browser**.
   - The portal sends requests to `/api/*`, which are reverse-proxied to the **inference service** running on a GPU host.
   - The inference service is the only component that touches the TTS model, CUDA, and host-level GPU status.

3. **Inference service subsystem**
   - `inference/app/main.py` is the API entrypoint and likely defines the FastAPI app and routes.
   - `model_service.py` is the real model adapter, while `fake_model_service.py` provides a test double so the API can be exercised without a GPU or model weights.
   - `deps.py` likely wires dependency injection so the app can swap real vs fake services cleanly.

4. **TTS and voice-cloning flow**
   - The service exposes at least `/api/tts` and `/api/clone`.
   - `/api/tts` accepts text plus generation controls such as `cfg_value` and `inference_timesteps`, then returns synthesized audio.
   - `/api/clone` accepts multipart input including uploaded reference audio and transcript-related fields, then runs the cloning path and returns audio.

5. **Audio handling boundary**
   - `audio.py` is the dedicated audio utility layer for the backend.
   - It likely handles reading/writing waveform data, validating input audio, and converting model output into the response format expected by the portal.
   - This keeps file/audio processing separate from HTTP and model orchestration.

6. **Model lifecycle and runtime constraints**
   - The README makes clear that generation is **serialized**: one GPU job at a time.
   - Heavy imports are **lazy**, which suggests startup is kept lightweight until the model is first needed.
   - The model path is externalized through `BLUEMAGPIE_MODEL_DIR`, with optional download support from Hugging Face using `HF_TOKEN`.

7. **Operational endpoints**
   - The backend exposes `/healthz` for readiness, `/api/speakers` for built-in speaker selection, and `/api/gpu` for live GPU monitoring.
   - `/api/gpu` combines host GPU telemetry and service memory usage, giving the UI live visibility during synthesis.
   - This means the service is not just a pure inference API; it also acts as an operational control plane for the demo.

8. **Portal subsystem**
   - `portal/` is a **static single-page app** with no front-end framework.
   - `app.js`, `styles.css`, and `index.html` implement the interactive synthesis/cloning UI.
   - The portal includes a separate `slides.html`, which is a self-contained architecture/deck experience deployed as static content.

9. **Portal-to-backend data flow**
   - The browser sends same-origin requests to `/api/*`, relying on reverse proxying rather than direct cross-origin calls.
   - The UI supports speaker preview, history, microphone recording, and parameter adjustment, but all synthesis work remains server-side.
   - The front end therefore functions as a thin interaction layer over the HTTP API, not as a processing layer.

10. **Testing strategy**
   - Backend tests in `inference/tests/` validate the API, audio utilities, and smoke paths, with the fake model service avoiding GPU dependency.
   - Front-end behavior is covered by Playwright tests in `portal/tests/`.
   - This split mirrors the runtime boundary: backend correctness is validated separately from browser/UI behavior.

11. **Packaging and tooling**
   - The inference side uses Python packaging (`pyproject.toml`, `uv.lock`) and runs under FastAPI/Uvicorn.
   - The portal uses Node tooling (`package.json`, `package-lock.json`) with Playwright for browser automation.
   - The repo is therefore a two-stack system: Python for inference, static web + JS tooling for presentation.

12. **Deployment shape**
   - A practical deployment is: static portal served publicly, reverse proxy in front, and inference service bound privately on the GPU machine.
   - The model weights are local or downloaded separately; they are not part of the portal build.
   - The main architectural constraint is that the inference service must have access to CUDA/GPU resources, while the portal does not.

Main entry points: [`inference/app/main.py`](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/main.py) (API app), [`inference/app/model_service.py`](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/model_service.py) (Model service), [`inference/app/deps.py`](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/deps.py) (Deps), [`inference/tests/test_api.py`](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/tests/test_api.py) (API tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inference["Inference Service"]
  node_inference_app_main["API app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_inference_app_deps["Deps<br/>DI wiring<br/>[deps.py]"]
  node_inference_app_model_service["Model service<br/>TTS adapter<br/>[model_service.py]"]
  node_inference_app_fake_model_service["Fake service<br/>test double"]
  node_inference_app_audio["Audio utils<br/>audio boundary<br/>[audio.py]"]
  node_inference_scripts_download_model["Download model<br/>model bootstrap<br/>[download_model.py]"]
  node_inference_scripts_smoke_model["Smoke model<br/>runtime check<br/>[smoke_model.py]"]
end

subgraph group_portal["Browser Portal"]
  node_portal_index["Portal UI<br/>static SPA<br/>[index.html]"]
  node_portal_app_js["UI logic<br/>browser script<br/>[app.js]"]
  node_portal_styles["Styles<br/>css<br/>[styles.css]"]
  node_portal_slides["Slides<br/>static deck<br/>[slides.html]"]
end

subgraph group_tests["Tests"]
  node_inference_tests_api["API tests<br/>backend tests<br/>[test_api.py]"]
  node_inference_tests_audio["Audio tests<br/>backend tests<br/>[test_audio.py]"]
  node_inference_tests_smoke["Smoke tests<br/>backend tests<br/>[test_smoke.py]"]
  node_portal_tests["Portal tests<br/>browser tests"]
  node_inference_tests_conftest["Test setup<br/>pytest fixtures<br/>[conftest.py]"]
end

node_portal_app_js -->|"calls /api"| node_inference_app_main
node_portal_index -->|"loads"| node_portal_app_js
node_portal_index -->|"styles"| node_portal_styles
node_inference_app_main -->|"wires"| node_inference_app_deps
node_inference_app_main -->|"uses"| node_inference_app_model_service
node_inference_app_main -.->|"uses"| node_inference_app_fake_model_service
node_inference_app_main -->|"formats"| node_inference_app_audio
node_inference_app_deps -->|"selects"| node_inference_app_model_service
node_inference_app_deps -->|"selects"| node_inference_app_fake_model_service
node_inference_app_model_service -->|"encodes"| node_inference_app_audio
node_inference_scripts_download_model -->|"prepares"| node_inference_app_model_service
node_inference_scripts_smoke_model -->|"exercises"| node_inference_app_model_service
node_inference_tests_api -->|"covers"| node_inference_app_main
node_inference_tests_api -->|"stubs"| node_inference_app_fake_model_service
node_inference_tests_audio -->|"covers"| node_inference_app_audio
node_inference_tests_smoke -->|"covers"| node_inference_app_model_service
node_portal_tests -->|"covers"| node_portal_app_js
node_inference_tests_conftest -->|"supports"| node_inference_tests_api

click node_inference_app_main "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/main.py"
click node_inference_app_deps "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/deps.py"
click node_inference_app_model_service "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/model_service.py"
click node_inference_app_fake_model_service "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/fake_model_service.py"
click node_inference_app_audio "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/audio.py"
click node_inference_scripts_download_model "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/scripts/download_model.py"
click node_inference_scripts_smoke_model "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/scripts/smoke_model.py"
click node_portal_index "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/portal/index.html"
click node_portal_app_js "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/portal/app.js"
click node_portal_styles "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/portal/styles.css"
click node_portal_slides "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/portal/slides.html"
click node_inference_tests_api "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/tests/test_api.py"
click node_inference_tests_audio "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/tests/test_audio.py"
click node_inference_tests_smoke "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/tests/test_smoke.py"
click node_portal_tests "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/portal/tests/test_portal.spec.js"
click node_inference_tests_conftest "https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/tests/conftest.py"

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_inference_app_main,node_inference_app_deps,node_inference_app_model_service,node_inference_app_fake_model_service,node_inference_app_audio,node_inference_scripts_download_model,node_inference_scripts_smoke_model toneBlue
class node_portal_index,node_portal_app_js,node_portal_styles,node_portal_slides toneAmber
class node_inference_tests_api,node_inference_tests_audio,node_inference_tests_smoke,node_portal_tests,node_inference_tests_conftest toneMint
```

## Components

### Inference Service

FastAPI backend that hosts the TTS/voice-cloning API and GPU-bound model runtime

- [API app](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/main.py): FastAPI entrypoint · Creates the service, registers routes, and orchestrates request handling · `inference/app/main.py`
- [Deps](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/deps.py): DI wiring · Selects and wires real or fake services for the app · `inference/app/deps.py`
- [Model service](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/model_service.py): TTS adapter · Real adapter around the BlueMagpie-TTS model and GPU runtime · `inference/app/model_service.py`
- [Fake service](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/fake_model_service.py): test double · GPU-free stand-in used by tests and local API exercise · `inference/app/fake_model_service.py`
- [Audio utils](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/app/audio.py): audio boundary · Loads, validates, and formats waveform data for the API · `inference/app/audio.py`
- [Download model](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/scripts/download_model.py): model bootstrap · Fetches external model weights into the configured model directory · `inference/scripts/download_model.py`
- [Smoke model](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/scripts/smoke_model.py): runtime check · Exercises the model path outside the API for a quick sanity check · `inference/scripts/smoke_model.py`

### Browser Portal

Static client-side UI that talks to the backend through same-origin /api requests

- [Portal UI](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/portal/index.html): static SPA · Single-page browser interface for synthesis, cloning, and speaker interaction · `portal/index.html`
- [UI logic](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/portal/app.js): browser script · Handles requests, recording, previews, history, and parameter controls · `portal/app.js`
- [Styles](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/portal/styles.css): css · Presentation and layout for the static portal · `portal/styles.css`
- [Slides](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/portal/slides.html): static deck · Self-contained static slide experience bundled with the portal · `portal/slides.html`

### Tests

Backend API, audio, smoke, and browser coverage

- [API tests](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/tests/test_api.py): backend tests · Validates HTTP routes, responses, and service behavior · `inference/tests/test_api.py`
- [Audio tests](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/tests/test_audio.py): backend tests · Covers the dedicated audio utility boundary · `inference/tests/test_audio.py`
- [Smoke tests](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/tests/test_smoke.py): backend tests · Runs quick end-to-end checks against the model path · `inference/tests/test_smoke.py`
- [Portal tests](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/portal/tests/test_portal.spec.js): browser tests · Playwright coverage for browser behavior and UI flows · `portal/tests/test_portal.spec.js`
- [Test setup](https://github.com/cutedogspark/bluemagpie-tts-portal/blob/main/inference/tests/conftest.py): pytest fixtures · Shared backend test fixtures and environment setup · `inference/tests/conftest.py`

## Connections

- UI logic → API app: calls /api · Browser UI sends synthesis, cloning, speaker, and GPU requests through the reverse proxy
- Portal UI → UI logic: loads · The HTML shell loads the portal's client-side interaction logic
- Portal UI → Styles: styles · The static page is styled by the bundled CSS
- API app → Deps: wires · The API entrypoint selects the concrete service implementation through dependency injection
- API app → Model service: uses · Main request flow reaches the real model adapter for TTS and cloning
- API app → Fake service: uses · Tests or non-GPU runs can swap in the fake service
- API app → Audio utils: formats · Routes delegate waveform and response handling to the audio layer
- Deps → Model service: selects · Dependency wiring can provide the real GPU-backed adapter
- Deps → Fake service: selects · Dependency wiring can provide the fake implementation for testing
- Model service → Audio utils: encodes · Model outputs pass through audio conversion and validation before returning to clients
- Download model → Model service: prepares · Bootstraps the external weights used by the model adapter
- Smoke model → Model service: exercises · Runs a direct runtime sanity check against the model path
- API tests → API app: covers · API tests validate the FastAPI entrypoint and its routes
- API tests → Fake service: stubs · Backend API tests avoid GPU dependency by using the fake service
- Audio tests → Audio utils: covers · Audio tests validate the isolated waveform boundary
- Smoke tests → Model service: covers · Smoke tests exercise the real model integration path
- Portal tests → UI logic: covers · Playwright checks the browser behavior driven by the portal script
- Test setup → API tests: supports · Shared fixtures support backend test setup