57 lines
2.4 KiB
Markdown
57 lines
2.4 KiB
Markdown
# 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"`. |