# lynchpin1634/middleapi architecture

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

- Interactive diagram: https://gitdiagram.com/lynchpin1634/middleapi
- Repository: https://github.com/lynchpin1634/middleapi

## Overview

MiddleAPI adapts OpenAI-compatible chat clients and GPT-SoVITS: chat requests are proxied to an AI API, whose response text can trigger TTS, while direct speech requests generate or reuse cached audio. Administrators use the Web UI to manage configuration and audio cleanup. The graph preserves the documented audio-list capability, though the sampled backend excerpt shows its page route but not a corresponding list-data endpoint. Connections for sampled code cite its caller; documented UI relationships cite the README.

Main entry points: [`MiddleAPI.py`](https://github.com/lynchpin1634/middleapi/blob/main/MiddleAPI.py) (FastAPI routes), [`utils/ProxyService.py`](https://github.com/lynchpin1634/middleapi/blob/main/utils/ProxyService.py) (Chat proxy), [`utils/GradioUtils.py`](https://github.com/lynchpin1634/middleapi/blob/main/utils/GradioUtils.py) (Gradio client), [`utils/ConfigUtils.py`](https://github.com/lynchpin1634/middleapi/blob/main/utils/ConfigUtils.py) (Config access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_home["Home and pages<br/>[index.html]"]
  node_settings["Settings page<br/>[settings.html]"]
  node_audio_pages["Audio pages<br/>[audiolist.html]"]
  node_cleanup_page["Cleanup page<br/>[cleanup.html]"]
  node_static_files["Static assets"]
end

subgraph group_api["API orchestration"]
  node_fastapi["FastAPI routes<br/>[MiddleAPI.py]"]
  node_request_models["Request models<br/>[PydanticUtils.py]"]
  node_config_api["Config endpoints<br/>[MiddleAPI.py]"]
  node_audio_management["Audio listing and cleanup<br/>[MiddleAPI.py]"]
end

subgraph group_speech["Speech and proxy"]
  node_tts["TTS generation<br/>[MiddleAPI.py]"]
  node_proxy["Chat proxy<br/>[ProxyService.py]"]
  node_gradio["Gradio client<br/>[GradioUtils.py]"]
end

subgraph group_state["Configuration and audio state"]
  node_config_tools["Config access<br/>[ConfigUtils.py]"]
  node_config_file[("YAML configuration<br/>[config.yaml]")]
  node_audio_cache[("Audio cache")]
end

subgraph group_shared["Shared utilities"]
  node_responses["Response handling<br/>[ResponseUtils.py]"]
  node_text_utils["Text cleanup<br/>[TextUtils.py]"]
  node_logging["Logging<br/>[LogUtils.py]"]
end

node_admin(("Administrator"))
node_client(("OpenWebUI client"))
node_ai_api["Compatible AI API"]
node_gpt_sovits["GPT-SoVITS service"]

node_admin -->|"opens"| node_home
node_home -->|"uses UI routes"| node_fastapi
node_settings -->|"manages settings"| node_config_api
node_audio_pages -->|"views audio"| node_audio_management
node_cleanup_page -->|"requests cleanup"| node_audio_management
node_fastapi -->|"mounts"| node_static_files
node_client -->|"sends speech requests"| node_fastapi
node_fastapi -->|"validates with"| node_request_models
node_fastapi -->|"handles errors with"| node_responses
node_fastapi -->|"routes speech to"| node_tts
node_tts -->|"reads and writes"| node_audio_cache
node_tts -->|"requests inference"| node_gradio
node_gradio -->|"reads parameters"| node_config_tools
node_gradio -->|"cleans and maps text"| node_text_utils
node_gradio -->|"calls inference"| node_gpt_sovits
node_fastapi -->|"delegates chat"| node_proxy
node_proxy -->|"forwards request"| node_ai_api
node_proxy -->|"calls speech endpoint"| node_fastapi
node_fastapi -->|"routes config operations"| node_config_api
node_config_api -->|"reads and writes"| node_config_tools
node_config_tools -->|"loads and saves"| node_config_file
node_fastapi -->|"routes audio operations"| node_audio_management
node_audio_management -->|"cleans files"| node_audio_cache
node_config_tools -->|"logs failures"| node_logging
node_proxy -->|"logs proxy events"| node_logging

click node_home "https://github.com/lynchpin1634/middleapi/blob/main/www/index.html"
click node_settings "https://github.com/lynchpin1634/middleapi/blob/main/www/settings.html"
click node_audio_pages "https://github.com/lynchpin1634/middleapi/blob/main/www/audiolist.html"
click node_cleanup_page "https://github.com/lynchpin1634/middleapi/blob/main/www/cleanup.html"
click node_static_files "https://github.com/lynchpin1634/middleapi/tree/main/www/files"
click node_fastapi "https://github.com/lynchpin1634/middleapi/blob/main/MiddleAPI.py"
click node_request_models "https://github.com/lynchpin1634/middleapi/blob/main/utils/PydanticUtils.py"
click node_responses "https://github.com/lynchpin1634/middleapi/blob/main/utils/ResponseUtils.py"
click node_tts "https://github.com/lynchpin1634/middleapi/blob/main/MiddleAPI.py"
click node_proxy "https://github.com/lynchpin1634/middleapi/blob/main/utils/ProxyService.py"
click node_gradio "https://github.com/lynchpin1634/middleapi/blob/main/utils/GradioUtils.py"
click node_text_utils "https://github.com/lynchpin1634/middleapi/blob/main/utils/TextUtils.py"
click node_config_api "https://github.com/lynchpin1634/middleapi/blob/main/MiddleAPI.py"
click node_config_tools "https://github.com/lynchpin1634/middleapi/blob/main/utils/ConfigUtils.py"
click node_config_file "https://github.com/lynchpin1634/middleapi/blob/main/config/config.yaml"
click node_audio_management "https://github.com/lynchpin1634/middleapi/blob/main/MiddleAPI.py"
click node_logging "https://github.com/lynchpin1634/middleapi/blob/main/utils/LogUtils.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_home,node_settings,node_audio_pages,node_cleanup_page,node_static_files,node_client toneBlue
class node_fastapi,node_request_models,node_config_api,node_audio_management toneAmber
class node_tts,node_proxy,node_gradio,node_ai_api toneMint
class node_config_tools,node_config_file,node_audio_cache toneRose
class node_responses,node_text_utils,node_logging,node_admin,node_gpt_sovits toneIndigo
```

## Components

### Web interface

- [Home and pages](https://github.com/lynchpin1634/middleapi/blob/main/www/index.html): `www/index.html`
- [Settings page](https://github.com/lynchpin1634/middleapi/blob/main/www/settings.html): `www/settings.html`
- [Audio pages](https://github.com/lynchpin1634/middleapi/blob/main/www/audiolist.html): `www/audiolist.html`
- [Cleanup page](https://github.com/lynchpin1634/middleapi/blob/main/www/cleanup.html): `www/cleanup.html`
- [Static assets](https://github.com/lynchpin1634/middleapi/tree/main/www/files): `www/files`

### API orchestration

- [FastAPI routes](https://github.com/lynchpin1634/middleapi/blob/main/MiddleAPI.py): `MiddleAPI.py`
- [Request models](https://github.com/lynchpin1634/middleapi/blob/main/utils/PydanticUtils.py): `utils/PydanticUtils.py`
- [Config endpoints](https://github.com/lynchpin1634/middleapi/blob/main/MiddleAPI.py): `MiddleAPI.py`
- [Audio listing and cleanup](https://github.com/lynchpin1634/middleapi/blob/main/MiddleAPI.py): `MiddleAPI.py`

### Speech and proxy

- [TTS generation](https://github.com/lynchpin1634/middleapi/blob/main/MiddleAPI.py): `MiddleAPI.py`
- [Chat proxy](https://github.com/lynchpin1634/middleapi/blob/main/utils/ProxyService.py): `utils/ProxyService.py`
- [Gradio client](https://github.com/lynchpin1634/middleapi/blob/main/utils/GradioUtils.py): `utils/GradioUtils.py`

### Configuration and audio state

- [Config access](https://github.com/lynchpin1634/middleapi/blob/main/utils/ConfigUtils.py): `utils/ConfigUtils.py`
- [YAML configuration](https://github.com/lynchpin1634/middleapi/blob/main/config/config.yaml): `config/config.yaml`
- **Audio cache**

### Shared utilities

- [Response handling](https://github.com/lynchpin1634/middleapi/blob/main/utils/ResponseUtils.py): `utils/ResponseUtils.py`
- [Text cleanup](https://github.com/lynchpin1634/middleapi/blob/main/utils/TextUtils.py): `utils/TextUtils.py`
- [Logging](https://github.com/lynchpin1634/middleapi/blob/main/utils/LogUtils.py): `utils/LogUtils.py`

### Other components

- **Administrator**
- **OpenWebUI client**
- **Compatible AI API**
- **GPT-SoVITS service**

## Connections

- Administrator → Home and pages: opens (evidence: `README.md`)
- Home and pages → FastAPI routes: uses UI routes (evidence: `README.md`)
- Settings page → Config endpoints: manages settings (evidence: `README.md`)
- Audio pages → Audio listing and cleanup: views audio (evidence: `README.md`)
- Cleanup page → Audio listing and cleanup: requests cleanup (evidence: `README.md`)
- FastAPI routes → Static assets: mounts (evidence: `MiddleAPI.py`)
- OpenWebUI client → FastAPI routes: sends speech requests (evidence: `README.md`)
- FastAPI routes → Request models: validates with (evidence: `MiddleAPI.py`)
- FastAPI routes → Response handling: handles errors with (evidence: `MiddleAPI.py`)
- FastAPI routes → TTS generation: routes speech to (evidence: `MiddleAPI.py`)
- TTS generation → Audio cache: reads and writes (evidence: `MiddleAPI.py`)
- TTS generation → Gradio client: requests inference (evidence: `MiddleAPI.py`)
- Gradio client → Config access: reads parameters (evidence: `utils/GradioUtils.py`)
- Gradio client → Text cleanup: cleans and maps text (evidence: `utils/GradioUtils.py`)
- Gradio client → GPT-SoVITS service: calls inference (evidence: `README.md`)
- FastAPI routes → Chat proxy: delegates chat (evidence: `MiddleAPI.py`)
- Chat proxy → Compatible AI API: forwards request (evidence: `utils/ProxyService.py`)
- Chat proxy → FastAPI routes: calls speech endpoint (evidence: `utils/ProxyService.py`)
- FastAPI routes → Config endpoints: routes config operations (evidence: `MiddleAPI.py`)
- Config endpoints → Config access: reads and writes (evidence: `MiddleAPI.py`)
- Config access → YAML configuration: loads and saves (evidence: `utils/ConfigUtils.py`)
- FastAPI routes → Audio listing and cleanup: routes audio operations (evidence: `MiddleAPI.py`)
- Audio listing and cleanup → Audio cache: cleans files (evidence: `MiddleAPI.py`)
- Config access → Logging: logs failures (evidence: `utils/ConfigUtils.py`)
- Chat proxy → Logging: logs proxy events (evidence: `utils/ProxyService.py`)