# techjarves/uncensored-local-studio architecture

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

- Interactive diagram: https://gitdiagram.com/techjarves/uncensored-local-studio
- Repository: https://github.com/techjarves/uncensored-local-studio

## Overview

1. **Overall shape**
   - This repo is a **local AI studio**: a browser-based React UI backed by a set of **native, offline model runtimes**.
   - The architectural boundary is clear: the **frontend is only a control surface**, while inference happens in separate local backend processes.

2. **Launch and platform entrypoints**
   - The user starts the app through **`windows.bat`**, **`linux.sh`**, or **`mac.sh`**.
   - Those scripts hand off to the setup/orchestration layer under **`scripts/`**, which installs or locates backends, starts services, and opens the local UI.

3. **Frontend subsystem**
   - **`app/frontend/`** is a Vite + React application.
   - Major UI components are split by capability: **image generation**, **text chat**, **speech transcription**, **text-to-speech**, **model management**, **settings**, **sidebar/navigation**, and **status monitoring**.
   - **`src/services/api.js`** is the main client-side boundary to the local server; the UI does not talk directly to the model runtimes.

4. **Local orchestration server**
   - **`scripts/server/serve.cjs`** is the central orchestrator.
   - It serves the web UI, coordinates backend startup/shutdown, and bridges the frontend to local model services.
   - This layer is also responsible for runtime decisions like port selection and backend availability, making it the process boundary between browser UI and native engines.

5. **Workspace separation**
   - The app intentionally separates **image generation** and **text/LLM** usage into different workspaces to avoid exhausting RAM/VRAM.
   - That means the system is not just “multiple features in one UI”; it is a **workspace-based runtime manager** that switches among mutually exclusive heavyweight engines.

6. **Image generation path**
   - Image generation is backed by **stable-diffusion.cpp** binaries selected for the platform and accelerator.
   - Models are stored in **`app/models/`**, and generated images are written to **`app/outputs/`** alongside metadata JSON, so outputs are treated as durable artifacts with prompt provenance.
   - The model manager can also populate this model store.

7. **Text chat / LLM path**
   - Text chat uses a **llama.cpp-based server backend**.
   - GGUF models live in **`app/llm-models/`** and are loaded locally by the backend rather than through a remote API.
   - The UI’s chat component communicates through the local orchestration layer, not directly with the model binary.

8. **Speech and audio workers**
   - Speech-to-text is handled by **worker processes** under **`scripts/workers/`**, including a Python-based CoreML/OpenVINO worker and the Whisper-related runtime setup.
   - Text-to-speech uses a separate **Kokoro worker** (`tts-kokoro-worker.mjs`), again keeping audio generation isolated from the main UI process.
   - This worker split suggests asynchronous job handling for transcription and synthesis rather than synchronous in-process execution.

9. **Model discovery, download, and import**
   - **`scripts/search/`** and **`scripts/config/llm-backends.json`** support model lookup and backend selection.
   - The README indicates model acquisition is offline-friendly but can also pull from Hugging Face-style URLs through the model manager.
   - This creates a dedicated “model supply chain” boundary: UI selects or imports models, the search/config layer resolves candidates, and files are placed into the correct local model directories.

10. **Setup, reset, and build tooling**
   - **`scripts/setup/`** contains platform-specific installers for CUDA, ROCm, Vulkan, OpenVINO NPU, Whisper, and TTS runtimes.
   - **`scripts/build/`** supports source builds of native backends when bundled binaries are not usable.
   - **`scripts/reset/`** is a repair path that clears caches and transient build state without deleting user models or outputs, so persistent artifacts are intentionally separated from repairable runtime state.

11. **Hardware-accelerated backend strategy**
   - The runtime is designed around **multiple accelerator targets**: CUDA, ROCm, Vulkan, Metal, CPU, and OpenVINO NPU.
   - This materially affects architecture because the backend choice is not static; the setup layer installs different binaries and workers depending on platform and hardware capability.

12. **Key storage boundaries**
   - User-provided or downloaded models are kept under **`app/models/`**, **`app/llm-models/`**, **`app/speech-models/`**, and **`app/tts-models/`**.
   - Generated artifacts go to **`app/outputs/`**.
   - Runtime binaries and platform-specific backend payloads are managed separately by the setup scripts, so the repo distinguishes clearly between **user content**, **generated output**, and **executables/runtime dependencies**.

Main entry points: [`app/frontend/src/App.jsx`](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/App.jsx) (Studio shell), [`scripts/server/serve.cjs`](https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/server/serve.cjs) (Orchestrator), [`scripts/setup/setup.sh`](https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/setup/setup.sh) (Setup), [`app/frontend/src/services/api.js`](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/services/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_windows_bat["Windows launch<br/>launcher<br/>[windows.bat]"]
  node_linux_sh["Linux launch<br/>launcher<br/>[linux.sh]"]
  node_mac_sh["Mac launch<br/>launcher<br/>[mac.sh]"]
end

subgraph group_ui["Frontend UI"]
  node_main_jsx["App entry<br/>frontend entry<br/>[main.jsx]"]
  node_app_jsx["Studio shell<br/>react app<br/>[App.jsx]"]
  node_sidebar["Sidebar<br/>navigation<br/>[Sidebar.jsx]"]
  node_statusbar["Status bar<br/>monitoring<br/>[TopStatusBar.jsx]"]
  node_chat["Text chat<br/>llm ui<br/>[TextChat.jsx]"]
  node_generator["Image gen<br/>image ui<br/>[Generator.jsx]"]
  node_transcriber["Speech input<br/>audio ui"]
  node_tts["Text to speech<br/>audio ui<br/>[TextToSpeech.jsx]"]
  node_models["Model manager<br/>model ui<br/>[ModelManager.jsx]"]
  node_settings["Settings<br/>preferences<br/>[Settings.jsx]"]
  node_api_js["API client<br/>frontend boundary<br/>[api.js]"]
end

subgraph group_orchestration["Local runtime"]
  node_serve_cjs["Orchestrator<br/>server<br/>[serve.cjs]"]
  node_setup_sh["Setup<br/>bootstrap<br/>[setup.sh]"]
  node_build_source["Build source"]
  node_reset_sh["Reset<br/>repair<br/>[reset.sh]"]
  node_search_core["Model search<br/>discovery<br/>[core.js]"]
  node_llm_backends["Backend config<br/>[llm-backends.json]"]
end

subgraph group_workers["Workers"]
  node_coreml_worker["CoreML worker<br/>speech worker<br/>[coreml_server.py]"]
  node_openvino_worker["OpenVINO worker<br/>speech worker"]
  node_tts_worker["Kokoro TTS<br/>tts worker"]
end

subgraph group_storage["Local storage"]
  node_model_store[("Model stores<br/>storage")]
  node_outputs[("Outputs<br/>artifact store")]
end

node_windows_bat -->|"starts"| node_serve_cjs
node_linux_sh -->|"starts"| node_serve_cjs
node_mac_sh -->|"starts"| node_serve_cjs
node_serve_cjs -->|"boots"| node_setup_sh
node_serve_cjs -->|"repairs"| node_reset_sh
node_serve_cjs -->|"serves"| node_main_jsx
node_main_jsx -->|"mounts"| node_app_jsx
node_app_jsx -->|"uses"| node_sidebar
node_app_jsx -->|"uses"| node_statusbar
node_app_jsx -->|"uses"| node_chat
node_app_jsx -->|"uses"| node_generator
node_app_jsx -->|"uses"| node_transcriber
node_app_jsx -->|"uses"| node_tts
node_app_jsx -->|"uses"| node_models
node_app_jsx -->|"uses"| node_settings
node_chat -->|"calls"| node_api_js
node_generator -->|"calls"| node_api_js
node_transcriber -->|"calls"| node_api_js
node_tts -->|"calls"| node_api_js
node_models -->|"discovers"| node_search_core
node_search_core -->|"reads"| node_llm_backends
node_setup_sh -->|"falls back to"| node_build_source
node_setup_sh -->|"installs"| node_coreml_worker
node_setup_sh -->|"installs"| node_openvino_worker
node_setup_sh -->|"installs"| node_tts_worker
node_serve_cjs -->|"spawns"| node_coreml_worker
node_serve_cjs -->|"spawns"| node_openvino_worker
node_serve_cjs -->|"spawns"| node_tts_worker
node_generator -->|"writes"| node_outputs
node_models -->|"populates"| node_model_store

click node_windows_bat "https://github.com/techjarves/uncensored-local-studio/blob/main/windows.bat"
click node_linux_sh "https://github.com/techjarves/uncensored-local-studio/blob/main/linux.sh"
click node_mac_sh "https://github.com/techjarves/uncensored-local-studio/blob/main/mac.sh"
click node_serve_cjs "https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/server/serve.cjs"
click node_setup_sh "https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/setup/setup.sh"
click node_build_source "https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/build/build_from_source.sh"
click node_reset_sh "https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/reset/reset.sh"
click node_search_core "https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/search/core.js"
click node_llm_backends "https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/config/llm-backends.json"
click node_main_jsx "https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/main.jsx"
click node_app_jsx "https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/App.jsx"
click node_sidebar "https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/Sidebar.jsx"
click node_statusbar "https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/TopStatusBar.jsx"
click node_chat "https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/TextChat.jsx"
click node_generator "https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/Generator.jsx"
click node_transcriber "https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/SpeechTranscriber.jsx"
click node_tts "https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/TextToSpeech.jsx"
click node_models "https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/ModelManager.jsx"
click node_settings "https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/Settings.jsx"
click node_api_js "https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/services/api.js"
click node_coreml_worker "https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/workers/coreml_server.py"
click node_openvino_worker "https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/workers/openvino_npu_worker.py"
click node_tts_worker "https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/workers/tts-kokoro-worker.mjs"

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_windows_bat,node_linux_sh,node_mac_sh toneBlue
class node_main_jsx,node_app_jsx,node_sidebar,node_statusbar,node_chat,node_generator,node_transcriber,node_tts,node_models,node_settings,node_api_js toneAmber
class node_serve_cjs,node_setup_sh,node_build_source,node_reset_sh,node_search_core,node_llm_backends toneMint
class node_coreml_worker,node_openvino_worker,node_tts_worker toneRose
class node_model_store,node_outputs toneIndigo
```

## Components

### Entry points

OS-specific launch scripts that hand off to orchestration

- [Windows launch](https://github.com/techjarves/uncensored-local-studio/blob/main/windows.bat): launcher · Windows entry script · `windows.bat`
- [Linux launch](https://github.com/techjarves/uncensored-local-studio/blob/main/linux.sh): launcher · Linux entry script · `linux.sh`
- [Mac launch](https://github.com/techjarves/uncensored-local-studio/blob/main/mac.sh): launcher · macOS entry script · `mac.sh`

### Frontend UI

React control surface for chat, generation, audio, and settings

- [App entry](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/main.jsx): frontend entry · React bootstrap and app mounting · `app/frontend/src/main.jsx`
- [Studio shell](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/App.jsx): react app · Top-level UI composition and workspace switching · `app/frontend/src/App.jsx`
- [Sidebar](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/Sidebar.jsx): navigation · Workspace and navigation controls · `app/frontend/src/components/Sidebar.jsx`
- [Status bar](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/TopStatusBar.jsx): monitoring · Runtime and backend status display · `app/frontend/src/components/TopStatusBar.jsx`
- [Text chat](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/TextChat.jsx): llm ui · Local chat workspace · `app/frontend/src/components/TextChat.jsx`
- [Image gen](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/Generator.jsx): image ui · Image generation workspace · `app/frontend/src/components/Generator.jsx`
- [Speech input](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/SpeechTranscriber.jsx): audio ui · Speech-to-text workspace · `app/frontend/src/components/SpeechTranscriber.jsx`
- [Text to speech](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/TextToSpeech.jsx): audio ui · Speech synthesis workspace · `app/frontend/src/components/TextToSpeech.jsx`
- [Model manager](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/ModelManager.jsx): model ui · Downloads, imports, and model placement · `app/frontend/src/components/ModelManager.jsx`
- [Settings](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/components/Settings.jsx): preferences · Runtime and workspace configuration · `app/frontend/src/components/Settings.jsx`
- [API client](https://github.com/techjarves/uncensored-local-studio/blob/main/app/frontend/src/services/api.js): frontend boundary · Browser-side bridge to the local server · `app/frontend/src/services/api.js`

### Local runtime

Server, search, setup, reset, and backend process coordination

- [Orchestrator](https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/server/serve.cjs): server · Serves UI and coordinates local backends · `scripts/server/serve.cjs`
- [Setup](https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/setup/setup.sh): bootstrap · Platform/runtime installation and backend selection · `scripts/setup/setup.sh`
- [Build source](https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/build/build_from_source.sh): build · Source build path for native backends · `scripts/build/build_from_source.sh`
- [Reset](https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/reset/reset.sh): repair · Clears transient state without removing user content · `scripts/reset/reset.sh`
- [Model search](https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/search/core.js): discovery · Model lookup and candidate resolution · `scripts/search/core.js`
- [Backend config](https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/config/llm-backends.json): config · LLM backend selection and metadata · `scripts/config/llm-backends.json`

### Workers

Isolated speech and TTS runtime processes

- [CoreML worker](https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/workers/coreml_server.py): speech worker · Python speech backend for Apple/NPU-style paths · `scripts/workers/coreml_server.py`
- [OpenVINO worker](https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/workers/openvino_npu_worker.py): speech worker · Speech runtime worker for NPU acceleration · `scripts/workers/openvino_npu_worker.py`
- [Kokoro TTS](https://github.com/techjarves/uncensored-local-studio/blob/main/scripts/workers/tts-kokoro-worker.mjs): tts worker · Dedicated text-to-speech worker process · `scripts/workers/tts-kokoro-worker.mjs`

### Local storage

Persistent model and output boundaries

- **Model stores**: storage · Local model directories for image, LLM, speech, and TTS assets
- **Outputs**: artifact store · Generated images and metadata artifacts

## Connections

- Windows launch → Orchestrator: starts · Windows launcher hands off to the orchestration server
- Linux launch → Orchestrator: starts · Linux launcher hands off to the orchestration server
- Mac launch → Orchestrator: starts · macOS launcher hands off to the orchestration server
- Orchestrator → Setup: boots · Server invokes setup and backend discovery
- Orchestrator → Reset: repairs · Server can trigger reset/cleanup workflows
- Orchestrator → App entry: serves · Server exposes the frontend application
- App entry → Studio shell: mounts · React bootstrap mounts the studio shell
- Studio shell → Sidebar: uses · Shell composes navigation
- Studio shell → Status bar: uses · Shell composes runtime status display
- Studio shell → Text chat: uses · Shell composes the chat workspace
- Studio shell → Image gen: uses · Shell composes the image workspace
- Studio shell → Speech input: uses · Shell composes the transcription workspace
- Studio shell → Text to speech: uses · Shell composes the synthesis workspace
- Studio shell → Model manager: uses · Shell composes model management
- Studio shell → Settings: uses · Shell composes settings controls
- Text chat → API client: calls · Chat reaches local services through the API client
- Image gen → API client: calls · Image generation flows through the local API boundary
- Speech input → API client: calls · Speech transcription flows through the local API boundary
- Text to speech → API client: calls · TTS flows through the local API boundary
- Model manager → Model search: discovers · Model manager resolves candidates through search helpers
- Model search → Backend config: reads · Search uses backend configuration to rank or target runtimes
- Setup → Build source: falls back to · Setup can route to source builds when binaries are unavailable
- Setup → CoreML worker: installs · Setup provisions speech-related platform workers
- Setup → OpenVINO worker: installs · Setup provisions NPU-oriented speech workers
- Setup → Kokoro TTS: installs · Setup provisions the TTS worker runtime
- Orchestrator → CoreML worker: spawns · Orchestrator manages speech worker processes
- Orchestrator → OpenVINO worker: spawns · Orchestrator manages speech worker processes
- Orchestrator → Kokoro TTS: spawns · Orchestrator manages audio synthesis workers
- Image gen → Outputs: writes · Generated images and metadata are persisted as artifacts
- Model manager → Model stores: populates · Model manager downloads or imports into local stores
