SimpleOpenSoftware · 0xrushi · Jan 5, 2026 · Jan 5, 2026 · Jan 5, 2026 · Feb 24, 2026
diff --git a/.env.template b/.env.template
@@ -218,4 +218,4 @@ WEBUI_MEMORY_REQUEST=128Mi
 SPEAKER_CPU_LIMIT=2000m
 SPEAKER_MEMORY_LIMIT=4Gi
 SPEAKER_CPU_REQUEST=500m
-SPEAKER_MEMORY_REQUEST=2Gi
+SPEAKER_MEMORY_REQUEST=2Gi
diff --git a/.github/workflows/advanced-docker-compose-build.yml b/.github/workflows/advanced-docker-compose-build.yml
@@ -140,22 +140,22 @@ jobs:
           set -euo pipefail
           docker compose version
           OWNER_LC=$(echo "$OWNER" | tr '[:upper:]' '[:lower:]')
-          
+
           # CUDA variants from pyproject.toml
           CUDA_VARIANTS=("cpu" "cu121" "cu126" "cu128")
-          
+
           # Base services (no CUDA variants, no profiles)
           base_service_specs=(
             "chronicle-backend|advanced-chronicle-backend|docker-compose.yml|."
             "workers|advanced-workers|docker-compose.yml|."
             "webui|advanced-webui|docker-compose.yml|."
             "openmemory-mcp|openmemory-mcp|../../extras/openmemory-mcp/docker-compose.yml|../../extras/openmemory-mcp"
           )
-          
+
           # Build and push base services
           for spec in "${base_service_specs[@]}"; do
             IFS='|' read -r svc svc_repo compose_file project_dir <<< "$spec"
-            
+
             echo "::group::Building and pushing $svc_repo"
             if [ "$compose_file" = "docker-compose.yml" ] && [ "$project_dir" = "." ]; then
               docker compose build --pull "$svc"
@@ -173,37 +173,37 @@ jobs:
               echo "::endgroup::"
               continue
             fi
-            
+
             # Tag and push with version
             target_image="$REGISTRY/$OWNER_LC/$svc_repo:$VERSION"
             latest_image="$REGISTRY/$OWNER_LC/$svc_repo:latest"
             echo "Tagging $img_id as $target_image"
             docker tag "$img_id" "$target_image"
             echo "Tagging $img_id as $latest_image"
             docker tag "$img_id" "$latest_image"
-            
+
             echo "Pushing $target_image"
             docker push "$target_image"
             echo "Pushing $latest_image"
             docker push "$latest_image"
-            
+
             # Clean up local tags
             docker image rm -f "$target_image" || true
             docker image rm -f "$latest_image" || true
             echo "::endgroup::"
-            
+
             # Aggressive cleanup to save space
             docker system prune -af || true
           done
-          
+
           # Build and push parakeet-asr with CUDA variants (cu121, cu126, cu128)
           echo "::group::Building and pushing parakeet-asr CUDA variants"
           cd ../../extras/asr-services
           for cuda_variant in cu121 cu126 cu128; do
             echo "Building parakeet-asr-${cuda_variant}"
             export PYTORCH_CUDA_VERSION="${cuda_variant}"
             docker compose build parakeet-asr
-            
+
             img_id=$(docker compose images -q parakeet-asr | head -n1)
             if [ -n "${img_id:-}" ]; then
               target_image="$REGISTRY/$OWNER_LC/parakeet-asr-${cuda_variant}:$VERSION"
@@ -212,23 +212,23 @@ jobs:
               docker tag "$img_id" "$target_image"
               echo "Tagging $img_id as $latest_image"
               docker tag "$img_id" "$latest_image"
-              
+
               echo "Pushing $target_image"
               docker push "$target_image"
               echo "Pushing $latest_image"
               docker push "$latest_image"
-              
+
               # Clean up local tags
               docker image rm -f "$target_image" || true
               docker image rm -f "$latest_image" || true
             fi
-            
+
             # Aggressive cleanup to save space
             docker system prune -af || true
           done
           cd - > /dev/null
           echo "::endgroup::"
-          
+
           # Build and push speaker-recognition with all CUDA variants (including CPU)
           # Note: speaker-service has profiles, but we can build it directly by setting PYTORCH_CUDA_VERSION
           echo "::group::Building and pushing speaker-recognition variants"
@@ -238,7 +238,7 @@ jobs:
             export PYTORCH_CUDA_VERSION="${cuda_variant}"
             # Build speaker-service directly (profiles only affect 'up', not 'build')
             docker compose build speaker-service
-            
+
             img_id=$(docker compose images -q speaker-service | head -n1)
             if [ -n "${img_id:-}" ]; then
               target_image="$REGISTRY/$OWNER_LC/speaker-recognition-${cuda_variant}:$VERSION"
@@ -247,23 +247,23 @@ jobs:
               docker tag "$img_id" "$target_image"
               echo "Tagging $img_id as $latest_image"
               docker tag "$img_id" "$latest_image"
-              
+
               echo "Pushing $target_image"
               docker push "$target_image"
               echo "Pushing $latest_image"
               docker push "$latest_image"
-              
+
               # Clean up local tags
               docker image rm -f "$target_image" || true
               docker image rm -f "$latest_image" || true
             fi
-            
+
             # Aggressive cleanup to save space
             docker system prune -af || true
           done
           cd - > /dev/null
           echo "::endgroup::"
-          
+
           # Summary
           echo "::group::Build Summary"
           echo "Built and pushed images with version tag: ${VERSION}"

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -613,4 +613,4 @@ The uv package manager is used for all python projects. Wherever you'd call `pyt
 - Only use `--no-cache` when explicitly needed (e.g., if cached layers are causing issues or when troubleshooting build problems)
 - Docker's build cache is efficient and saves significant time during development
 
-- Remember that whenever there's a python command, you should use uv run python3 instead
+- Remember that whenever there's a python command, you should use uv run python3 instead
diff --git a/Docs/init-system.md b/Docs/init-system.md
@@ -3,7 +3,7 @@
 ## Quick Links
 
 - **👉 [Start Here: Quick Start Guide](../quickstart.md)** - Main setup path for new users
-- **📚 [Full Documentation](../CLAUDE.md)** - Comprehensive reference  
+- **📚 [Full Documentation](../CLAUDE.md)** - Comprehensive reference
 - **🏗️ [Architecture Details](overview.md)** - Technical deep dive
 
 ---
@@ -59,12 +59,12 @@ Each service can be configured independently:
 cd backends/advanced
 uv run --with-requirements setup-requirements.txt python init.py
 
-# Speaker Recognition only  
+# Speaker Recognition only
 cd extras/speaker-recognition
 ./setup.sh
 
 # ASR Services only
-cd extras/asr-services  
+cd extras/asr-services
 ./setup.sh
 
 # OpenMemory MCP only
@@ -80,21 +80,21 @@ cd extras/openmemory-mcp
 - **Generates**: Complete `.env` file with all required configuration
 - **Default ports**: Backend (8000), WebUI (5173)
 
-### Speaker Recognition  
+### Speaker Recognition
 - **Prompts for**: Hugging Face token, compute mode (cpu/gpu)
 - **Service port**: 8085
 - **WebUI port**: 5173
 - **Requires**: HF_TOKEN for pyannote models
 
 ### ASR Services
-- **Starts**: Parakeet ASR service via Docker Compose  
+- **Starts**: Parakeet ASR service via Docker Compose
 - **Service port**: 8767
 - **Purpose**: Offline speech-to-text processing
 - **No configuration required**
 
 ### OpenMemory MCP
 - **Starts**: External OpenMemory MCP server
-- **Service port**: 8765  
+- **Service port**: 8765
 - **WebUI**: Available at http://localhost:8765
 - **Purpose**: Cross-client memory compatibility
 
@@ -112,10 +112,10 @@ Note (Linux): If `host.docker.internal` is unavailable, add `extra_hosts: - "hos
 
 ## Key Benefits
 
-✅ **No Unnecessary Building** - Services are only started when you explicitly request them  
-✅ **Resource Efficient** - Parakeet ASR won't start if you're using cloud transcription  
-✅ **Clean Separation** - Configuration vs service management are separate concerns  
-✅ **Unified Control** - Single command to start/stop all services  
+✅ **No Unnecessary Building** - Services are only started when you explicitly request them
+✅ **Resource Efficient** - Parakeet ASR won't start if you're using cloud transcription
+✅ **Clean Separation** - Configuration vs service management are separate concerns
+✅ **Unified Control** - Single command to start/stop all services
 ✅ **Selective Starting** - Choose which services to run based on your current needs
 
 ## Ports & Access
@@ -215,7 +215,7 @@ You can also manage services individually:
 # Advanced Backend
 cd backends/advanced && docker compose up --build -d
 
-# Speaker Recognition  
+# Speaker Recognition
 cd extras/speaker-recognition && docker compose up --build -d
 
 # ASR Services (only if using offline transcription)
@@ -225,6 +225,59 @@ cd extras/asr-services && docker compose up --build -d
 cd extras/openmemory-mcp && docker compose up --build -d
 ```
 
+## Startup Flow (Mermaid) diagram
+
+Chronicle has two layers:
+- **Setup** (`wizard.sh` / `wizard.py`) writes config (`.env`, `config/config.yml`, optional SSL/nginx config).
+- **Run** (`start.sh` / `services.py`) starts the configured services via `docker compose`.
+
+```mermaid
+flowchart TD
+  A[wizard.sh] --> B[uv run --with-requirements setup-requirements.txt wizard.py]
+  B --> C{Select services}
+  C --> D[backends/advanced/init.py\nwrites backends/advanced/.env + config/config.yml]
+  C --> E[extras/speaker-recognition/init.py\nwrites extras/speaker-recognition/.env\noptionally ssl/* + nginx.conf]
+  C --> F[extras/asr-services/init.py\nwrites extras/asr-services/.env]
+  C --> G[extras/openmemory-mcp/setup.sh]
+
+  A2[start.sh] --> B2[uv run --with-requirements setup-requirements.txt python services.py start ...]
+  B2 --> H{For each service:\n.env exists?}
+  H -->|yes| I[services.py runs docker compose\nin each service directory]
+  H -->|no| J[Skip (not configured)]
+```
+
+### How `services.py` picks Speaker Recognition variants
+
+`services.py` reads `extras/speaker-recognition/.env` and decides:
+- `COMPUTE_MODE=cpu|gpu|strixhalo` → choose compose profile
+- `REACT_UI_HTTPS=true|false` → include `nginx` (HTTPS) vs run only API+UI (HTTP)
+
+```mermaid
+flowchart TD
+  S[start.sh] --> P[services.py]
+  P --> R[Read extras/speaker-recognition/.env]
+  R --> M{COMPUTE_MODE}
+  M -->|cpu| C1[docker compose --profile cpu up ...]
+  M -->|gpu| C2[docker compose --profile gpu up ...]
+  M -->|strixhalo| C3[docker compose --profile strixhalo up ...]
+  R --> H{REACT_UI_HTTPS}
+  H -->|true| N1[Start profile default set:\nAPI + web-ui + nginx]
+  H -->|false| N2[Start only:\nAPI + web-ui (no nginx)]
+```
+
+### CPU + NVIDIA share the same `Dockerfile` + `pyproject.toml`
+
+Speaker recognition uses a single dependency definition with per-accelerator “extras”:
+- `extras/speaker-recognition/pyproject.toml` defines extras like `cpu`, `cu121`, `cu126`, `cu128`, `strixhalo`.
+- `extras/speaker-recognition/Dockerfile` takes `ARG PYTORCH_CUDA_VERSION` and runs:
+  - `uv sync --extra ${PYTORCH_CUDA_VERSION}`
+  - `uv run --extra ${PYTORCH_CUDA_VERSION} ...`
+- `extras/speaker-recognition/docker-compose.yml` sets that build arg per profile:
+  - CPU profile defaults to `PYTORCH_CUDA_VERSION=cpu`
+  - GPU profile defaults to `PYTORCH_CUDA_VERSION=cu126` and reserves NVIDIA GPUs
+
+AMD/ROCm (Strix Halo) uses the same `pyproject.toml` interface (the `strixhalo` extra), but a different build recipe (`extras/speaker-recognition/Dockerfile.strixhalo`) and ROCm device mappings, because the base image provides the torch stack.
+
 ## Configuration Files
 
 ### Generated Files
@@ -250,7 +303,7 @@ cd extras/openmemory-mcp && docker compose up --build -d
 # Backend health
 curl http://localhost:8000/health
 
-# Speaker Recognition health  
+# Speaker Recognition health
 curl http://localhost:8085/health
 
 # ASR service health
@@ -267,4 +320,4 @@ cd backends/advanced && docker compose logs chronicle-backend
 
 # Speaker Recognition logs
 cd extras/speaker-recognition && docker compose logs speaker-service
-```
+```