# 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
```bash
pip install -r requirements.txt    # Install Python dependencies
python run.py                      # Start backend dev server (port 18000, auto-reload)
```

### Frontend
```bash
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
```bash
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"`.