Workspace Quick-Start Cheat Sheet 🚀 #

Welcome to the /home/dev server container! This cheatsheet is a high-level, idiot-proof, and ultra-condensed reference map for all active projects, services, port allocations, and dev workflows.

🔌 1. Global Port Allocation Map #

📂 2. Absolute Path Directory Map #

• /home/dev/audio/mixbox/ 🎛️ — DJ automation & beatgrid editor (FastAPI, NiceGUI, React/OpenDAW).
• /home/dev/audio/audioflux/ 📊 — MIR signal analyzer Gradio UI (Pure NumPy/SciPy math, no librosa).
• /home/dev/audio/broadcast/ 📻 — Radio streaming orchestration (Icecast & Liquidsoap configs).
• /home/dev/audio/nicegui/ 🖥️ — Frontend demo elements & component modifications.
• /home/dev/hugdown/ ⚡ — Hybrid static-client site (GIMA React hydration on GOMA Hugo static views).
• /home/dev/py/flow/ 🤖 — Visual pipeline node connector & chatbot design environment (Langflow).
• /home/dev/py/groqgradio/ ⚡ — Systemd-deployed Gradio UIs hooked up to Groq APIs.
• /home/dev/py/gradiomulti/ 🧪 — Multi-service OpenAI Gradio playground via OpenRouter.
• /home/dev/py/mugen/ 🎬 — Music Video Creator CLI (Rhythm beats matching video edit).
• /home/dev/py/mugen-webui/ 🎞️ — MUGEN editor web control center interface.
• /home/dev/active/ 🕹️ — Project sandbox containing ai-town, storymatrix, and express lobbies (fun, funday).

💻 3. Command Central by Project #

🎛️ MixBox (/home/dev/audio/mixbox/) #

# Sync package deps via uv
uv sync

# Auto-format and lint code
uv run ruff check . --fix

# Run unit tests (skip slow mix generations)
uv run pytest -m "not rotation"

# Run Quality Gate regression tests (Micro or Afro baseline)
uv run python scripts/rotation_quality_gate.py micro
uv run python scripts/rotation_quality_gate.py afro

# Launch editor UI (Port 55644)
uv run python -m mixbox.gui

📊 AudioFlux Showcase (/home/dev/audio/audioflux/) #

# Activate Venv & start all 3 Gradio apps in the background
source .venv/bin/activate
python app/main.py &
python app/unified_main.py &
python mir_playground_standalone.py &

# Kill Gradio apps
pkill -f "main.py\|unified_main.py\|mir_playground_standalone.py"

# Run comprehensive signal engine checks
python -c "exec(open('test_comprehensive.py').read())"

⚡ Hugdown / GIGO (/home/dev/hugdown/) #

# Start GOMA (Hugo) and GIMA (React) concurrently
./gigo-start.sh

# Terminate dev environments
./gigo-stop.sh

# Build React client, copy bundles, and generate static Hugo site
./build-all.sh

# Execute integration tests
node test-e2e.js

🤖 Langflow (/home/dev/py/flow/) #

# Start visual builder backend (Port 55577)
poetry run langflow run --host 0.0.0.0 --port 55577

⚡ Groq Gradio Services (/home/dev/py/groqgradio/) #

# Manage Gradio services via systemd
systemctl --user start groq-minimal.service
systemctl --user start groq-streamlined.service
systemctl --user start groq-main.service
systemctl --user start groq-langflow.service

# Stream service logs
journalctl --user -u groq-minimal -f

🧪 Jamjams Chat Lab (/home/dev/py/gradiomulti/) #

# Launch OpenAI OpenRouter Gradio interface (Port 55442)
python app.py

🎞️ MUGEN WebUI (/home/dev/py/mugen-webui/) #

# Launch rhythm video generator control UI
python webui.py

🕹️ Active Sandbox #

• ai-town: cd /home/dev/active/ai-town && npm run dev
• funday: cd /home/dev/active/funday && ./start-funday.sh

🛠️ 4. Essential Coding Conventions #

🐍 Python #

1. Audio Fallbacks: Use load_audio from audio_core. It targets librosa first and gracefully falls back to pydub-ng.
2. Audioflux Constraints: Direct imports of librosa or audioflux in /home/dev/audio/audioflux/ are strictly FORBIDDEN. Use local signal math inside app/utils/audio_utils.py.
3. Pydantic: Declare runtime parameters inside Pydantic structures (packages/dj-engine/src/mixbox/config/models.py).

📦 Node / Vite / Static Site #

1. CDN Hydration: In Hugdown static views, import React and ReactDOM from https://esm.sh/ inside the HTML layout to avoid dependency bloating.
2. JWT Credentials: Secure custom endpoints via JWT_SECRET_KEY on HS256 algorithm.

🔬 5. Testing & Verification #

• Pytest Suite: Execute unit tests using pytest markers (slow, integration, rotation, perf, viz).
• Telemetry Verification: Tracing logs use @langfuse/otel (with a visibility poll timeout of 4000 ms). Never extract get API methods without binding context (traceApi.get(traceId)) to avoid losing this reference context.