superDreamFront/CLAUDE.md

CLAUDE.md

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

Project Overview

SuperDream is a full-stack web application with a Python/FastAPI backend and a React/TypeScript/Vite frontend. The backend serves a REST API and also serves the built frontend as a SPA in production.

Development Commands

Backend

pip install -r requirements.txt    # Install Python dependencies
python run.py                      # Start backend dev server (port 18000, auto-reload)

Frontend

cd frontend
npm install                        # Install frontend dependencies
npm run dev                        # Start Vite dev server (port 3000, proxies /api to backend)
npm run build                      # TypeScript check + production build to frontend/dist/

Docker

docker-compose up                  # Build and run full stack (maps port 18000:8000)

Architecture

Backend (/app)

• Entry point: run.py → starts uvicorn with app.main:app
• App factory: app/main.py → create_app() builds the FastAPI instance
• Config: app/config/settings.py — Pydantic BaseSettings with SD_ env prefix, loads from .env
• API routes: app/api/v1/ — versioned REST endpoints (health, example CRUD)
• Services: app/services/ — business logic layer (currently in-memory storage)
• Data models: app/datamodels/schemas.py — Pydantic request/response schemas
• Models: app/models/ — placeholder for ORM models

Frontend (/frontend/src)

• React 19 + TypeScript (strict mode) + Vite
• Path alias: @ → frontend/src/
• Components: components/ — Header, StatusBar
• Services: services/ — HTTP client wrapper and API service modules
• Hooks: hooks/ — useFetch for data fetching with loading/error states
• Styling: Tailwind CSS via CDN, dark theme by default with custom SuperDream color palette

Request Flow

In development, the frontend Vite dev server (port 3000) proxies /api and /data/files to the backend (port 18000). In production, FastAPI serves the built frontend from frontend/dist/, mounting /assets and falling back to index.html for SPA routing.

Configuration

All backend settings use the SD_ environment variable prefix (e.g., SD_PORT, SD_DB_TYPE). Copy .env.example to .env to configure. Database mode is either "file" or "mysql".