How techjarves/uncensored-local-studio works
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.jsx Studio shell · serve.cjs Orchestrator · setup.sh Setup · api.js API client
Components 25
Entry points
OS-specific launch scripts that hand off to orchestration
- Windows launch · Windows entry script
windows.bat - Linux launch · Linux entry script
linux.sh - Mac launch · macOS entry script
mac.sh
Frontend UI
React control surface for chat, generation, audio, and settings
- App entry · React bootstrap and app mounting
app/frontend/src/main.jsx - Studio shell · Top-level UI composition and workspace switching
app/frontend/src/App.jsx - Sidebar · Workspace and navigation controls
app/frontend/src/components/Sidebar.jsx - Status bar · Runtime and backend status display
app/frontend/src/components/TopStatusBar.jsx - Text chat · Local chat workspace
app/frontend/src/components/TextChat.jsx - Image gen · Image generation workspace
app/frontend/src/components/Generator.jsx - Speech input · Speech-to-text workspace
app/frontend/src/components/SpeechTranscriber.jsx - Text to speech · Speech synthesis workspace
app/frontend/src/components/TextToSpeech.jsx - Model manager · Downloads, imports, and model placement
app/frontend/src/components/ModelManager.jsx - Settings · Runtime and workspace configuration
app/frontend/src/components/Settings.jsx - API client · Browser-side bridge to the local server
app/frontend/src/services/api.js
Local runtime
Server, search, setup, reset, and backend process coordination
- Orchestrator · Serves UI and coordinates local backends
scripts/server/serve.cjs - Setup · Platform/runtime installation and backend selection
scripts/setup/setup.sh - Build source · Source build path for native backends
scripts/build/build_from_source.sh - Reset · Clears transient state without removing user content
scripts/reset/reset.sh - Model search · Model lookup and candidate resolution
scripts/search/core.js - Backend config · LLM backend selection and metadata
scripts/config/llm-backends.json
Workers
Isolated speech and TTS runtime processes
- CoreML worker · Python speech backend for Apple/NPU-style paths
scripts/workers/coreml_server.py - OpenVINO worker · Speech runtime worker for NPU acceleration
scripts/workers/openvino_npu_worker.py - Kokoro TTS · Dedicated text-to-speech worker process
scripts/workers/tts-kokoro-worker.mjs
Local storage
Persistent model and output boundaries
- Model stores · Local model directories for image, LLM, speech, and TTS assets
- Outputs · Generated images and metadata artifacts
Connections 30
- 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