semblance_backup/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:
```bash
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://ai-sandbox.oliver.solutions/semblance_back/api`
- WebSocket path: `/semblance_back/socket.io/`
- MSAL redirect: `https://ai-sandbox.oliver.solutions/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