semblance/CLAUDE.md

CLAUDE.md

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

Commands

• Build: npm run build (use this for all testing and verification)
• Dev Build: npm run build:dev (development mode build)
• Lint: npm run lint
• Preview: npm run preview
• Backend: cd backend && python run.py

Note: This project supports both local development and production deployment. See Environment Configuration section below.

Backend Commands

• Start Backend: python run.py (from backend/ directory)
• Backend Server: Runs on port 5137 with Hypercorn ASGI server
• Database: MongoDB with PyMongo
• Authentication: Custom Quart-compatible JWT (not Flask-JWT-Extended)

Testing

Python Backend: 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; app = create_app()"  # Test app creation

Frontend: Run npm run build to verify TypeScript compilation

Architecture Overview

Real-Time Communication

The application uses Socket.IO for real-time WebSocket communication between frontend and backend:

• Backend: python-socketio with AsyncServer wrapped in ASGI app
• Frontend: socket.io-client managed via WebSocketContext
• WebSocket manager (websocket_manager_async.py) handles room-based messaging for focus group sessions

Autonomous Conversation System

Focus group sessions can run autonomously with AI-driven conversations:

• ai_runner_service.py - Manages background task execution for autonomous mode
• autonomous_conversation_controller.py - Orchestrates multi-persona conversations
• conversation_decision_service.py - Determines next speaker and conversation flow
• conversation_context_service.py - Maintains conversation state and history

LLM Integration

Multi-model support through llm_service.py:

• Google Gemini (gemini-3-pro-preview) - Default model
• OpenAI (gpt-4.1, gpt-5.2) - Alternative models
• Prompts are stored as markdown templates in /backend/prompts/

Code Style Guidelines

• Imports: Group imports by source (React, third-party, local)
• Types: Use TypeScript. Project allows nullable types (strictNullChecks: false)
• Components: Use functional components with hooks
• Naming: Use PascalCase for components, camelCase for variables/functions
• Formatting: Follow ESLint recommendations, focus on readability
• Error Handling: Use try/catch blocks with toast for user feedback
• CSS: Use Tailwind classes for styling, with component-specific CSS files when needed
• File Structure: Components in /src/components, pages in /src/pages, hooks in /src/hooks
• UI Components: Use shadcn-ui components from /src/components/ui
• State Management: React hooks for local state, context/props for sharing
• URL Construction: ALWAYS use import.meta.env.BASE_URL when constructing URLs for static assets, images, or links. This project uses base path /semblance/ in production. Example: ${import.meta.env.BASE_URL}image.png instead of /image.png

Project Stack

Frontend: Vite, React 18, TypeScript, Tailwind CSS, shadcn-ui Backend: Quart (async Flask), Hypercorn ASGI, PyMongo, python-socketio Key Libraries:

• UI: Radix UI components, Lucide React icons
• State: TanStack Query, React Hook Form with Zod validation
• Routing: React Router DOM
• AI/LLM: OpenAI, Google Generative AI (genai)
• Real-time: Socket.IO (client and server)
• Charts: Recharts
• Drag & Drop: DND Kit

API Configuration

• Frontend API Base: /semblance_back/api (configurable via VITE_API_BASE_URL)
• Backend Proxy: Vite dev server proxies /api to localhost:5137
• Production Base Path: /semblance/ (configured in vite.config.ts)
• Authentication: JWT tokens stored in localStorage

File Organization

• Backend Services: /backend/app/services/ - Business logic and AI integrations
• Backend Models: /backend/app/models/ - Data models (User, FocusGroup, Persona, Folder)
• Backend Routes: /backend/app/routes/ - API endpoints (auth, personas, focus-groups, ai-personas, folders, tasks)
• AI Prompts: /backend/prompts/ - LLM prompt templates (markdown files loaded by prompt_loader.py)
• Frontend Components:
  • /src/components/ui/ - Reusable shadcn-ui components
  • /src/components/focus-group-session/ - Focus group session UI (DiscussionPanel, ParticipantPanel, ThemesPanel, etc.)
  • /src/components/persona/ - Persona management components
• Types: /src/types/ - TypeScript type definitions
• Contexts: /src/contexts/ - React context providers (AuthContext, WebSocketContext, NavigationContext)

Environment Configuration

This application supports both local development and production deployment through environment-specific configuration files:

Environment Files

• .env.development: Local development configuration
• .env.production: Production server configuration
• .env: Active configuration (copy from appropriate environment file)

Development vs Production

The application automatically adapts based on environment variables:

Development Mode:

• Base path: / (root)
• API base: /api
• WebSocket path: /socket.io/
• MSAL redirect: http://localhost:5173/

Production Mode:

• Base path: /semblance/
• API base: https://optical-dev.oliver.solution/semblance_back/api
• WebSocket path: /semblance_back/socket.io/
• MSAL redirect: https://optical-dev.oliver.solution/semblance

Setup Instructions

1. For local development: Copy .env.development to .env
2. For production: Copy .env.production to .env
3. The build system will use the appropriate configuration

Technical Details

• Base Path: Configured in vite.config.ts based on NODE_ENV
• Backend Port: 5137 (Hypercorn ASGI server)
• Frontend Dev Port: 5173
• Temp Directories: Backend creates /backend/temp/ for file handling