Oliver/semblance-dev
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
semblance-dev/CLAUDE.md

4.6 KiB
Raw Blame History

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: 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 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