semblance-dev/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

• Dev Server: npm run dev (port 5173, proxies /api → localhost:5137)
• Build: npm run build (use this to verify TypeScript compilation)
• Dev Build: npm run build:dev (development mode build)
• Lint: npm run lint
• Backend: cd backend && python run.py (Hypercorn ASGI on port 5137)

Backend Testing

After modifying any Python files:

source backend/venv/bin/activate
python -c "import app.services.module_name"        # Test specific module
python -c "from app import create_app; create_app()"  # Test app creation

Architecture Overview

ASGI Stack (critical detail)

create_app() returns a socketio.ASGIApp wrapping a Quart app — not the Quart app itself. Accessing app.quart_app gives the inner Quart instance. This distinction matters whenever you write ASGI middleware or access app config directly.

Real-Time Communication

Socket.IO via python-socketio AsyncServer (ASGI mode). The WebSocketContextNew.tsx context manages the client connection. websocket_manager_async.py handles room-based messaging for focus group sessions. The WebSocket manager must call ws_mgr.set_main_loop(asyncio.get_running_loop()) at startup so that cross-thread emits from the AI Runner land on the right loop.

VITE_ENABLE_WEBSOCKET is hardcoded true in dev and false in production builds via vite.config.ts — it is not controlled by .env.

AI Runner + Threading

ai_runner_service.py is a singleton that owns a dedicated OS thread with a single asyncio event loop. All autonomous AI conversations run in this thread. This solves Motor (AsyncIOMotorClient) event-loop affinity: Motor clients in the AI runner are bound to that loop, while regular API routes use synchronous PyMongo. Never share Motor clients between the two contexts.

Autonomous Conversation Pipeline

1. ai_runner_service.py — spawns coroutines on the dedicated thread's event loop
2. autonomous_conversation_controller.py — orchestrates the full session
3. conversation_decision_service.py — picks the next speaker
4. conversation_context_service.py — maintains history/state
5. conversation_state_manager.py — in-memory state across turns

Task Manager

task_manager.py is a singleton tracking cancellable asyncio tasks (persona generation, discussion guides, etc.). Tasks are exposed via /api/tasks routes. A background sweeper cleans up completed/expired tasks. Frontend polling is handled by useTaskPolling.ts.

LLM Integration

llm_service.py creates fresh clients per call (avoids event-loop mismatch in ASGI). Default model: Google Gemini via google-genai. Alternative: OpenAI (AsyncOpenAI). Both require env vars GEMINI_API_KEY and OPENAI_API_KEY — startup fails if missing. Prompts are markdown templates in /backend/prompts/ loaded by prompt_loader.py.

Code Style

• TypeScript with strictNullChecks: false
• Functional components with hooks; local state via hooks, shared state via context/props
• @/ alias maps to src/
• URL construction: always use ${import.meta.env.BASE_URL}asset.png — production base is /semblance/
• Error handling: try/catch + sonner toast for user feedback

File Organization

backend/
  app/
    routes/          # Blueprints: auth, personas, focus-groups, ai-personas, focus-group-ai, folders, tasks
    services/        # Business logic: llm_service, ai_runner_service, task_manager, autonomous_*, conversation_*
    models/          # Data models: User, FocusGroup, Persona, Folder
    auth/            # Auth utilities (JWT helpers)
    prompts/         # LLM prompt markdown templates
    websocket_manager_async.py  # Room-based async WebSocket manager
    extensions.py    # socketio.AsyncServer singleton

src/
  pages/             # Route-level components (Dashboard, FocusGroups, FocusGroupSession, Login, SyntheticUsers)
  components/
    focus-group-session/  # Session UI panels (Discussion, Participant, Themes, etc.)
    persona/         # Persona management components
    ui/              # shadcn-ui primitives
  contexts/          # AuthContext, WebSocketContextNew, NavigationContext
  hooks/             # useTaskPolling, useWebSocket, usePersonaStorage, useDiscussionGuideGeneration, etc.
  types/             # TypeScript type definitions

Environment Configuration

Setting	Development	Production
Base path	/	/semblance/
API base	/api (proxied to 5137)	https://optical-dev.oliver.solutions/semblance_back/api
WebSocket path	/socket.io/	/semblance_back/socket.io/
MSAL redirect	http://localhost:5173/	https://optical-dev.oliver.solutions/semblance

Setup: copy .env.development or .env.production to .env. Backend requires backend/.env with SECRET_KEY, JWT_SECRET_KEY, GEMINI_API_KEY, OPENAI_API_KEY — startup will throw RuntimeError if any are missing or use weak defaults.

Knowledge Wiki

A cross-project knowledge base is maintained automatically from all Claude Code sessions.

• Index: /Users/ai_leed/Library/Mobile Documents/iCloud~md~obsidian/Documents/VadymSamoilenko/wiki/index.md
• Query: cd ~/.claude/memory-compiler && uv run python scripts/query.py "your question"