# 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 is hosted on a server. Always use `npm run build` instead of `npm run dev` for testing changes.

## 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**: JWT tokens via 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

## 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**: Flask 2.2.3, Hypercorn, PyMongo, JWT Extended
**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
- 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)
- **Backend Routes**: `/backend/app/routes/` - API endpoints
- **AI Prompts**: `/backend/prompts/` - LLM prompt templates
- **Frontend Components**: 
  - `/src/components/ui/` - Reusable shadcn-ui components
  - `/src/components/focus-group-session/` - Focus group specific components
  - `/src/components/persona/` - Persona management components
- **Types**: `/src/types/` - TypeScript type definitions
- **Contexts**: `/src/contexts/` - React context providers

## Environment
- **Base Path**: Uses `/semblance/` in production (configured in vite.config.ts)
- **Backend Port**: 5137 (Hypercorn ASGI server)
- **Frontend Dev Port**: 5173
- **Temp Directories**: Backend creates `/backend/temp/` for file handling