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:

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

3.6 KiB Raw Blame History