# CLAUDE.md - Echoes of the Ash

## Project Overview
- **Type**: Dark Fantasy RPG Adventure
- **Stack**: Monorepo with Python/FastAPI backend and React/Vite/TypeScript frontend.
- **Infrastructure**: Docker Compose (Postgres, Redis, Traefik).
- **Primary Target**: Web (PWA + API). Electron is secondary.

## Commands

### Development & Deployment
- **Start (Dev)**: `docker compose up -d`
- **Apply Changes**: `docker compose build && docker compose up -d` (Required for both code and env changes)
- **Restart API**: `docker compose restart echoes_of_the_ashes_api`
- **View Logs**: `docker compose logs -f [service_name]` (e.g., `echoes_of_the_ashes_api`, `echoes_of_the_ashes_pwa`)

### Frontend (PWA)
- **Directory**: `pwa/`
- **Install**: `npm install`
- **Dev Server**: `npm run dev`
- **Build**: `npm run build`
- **Lint**: `npm run lint`

### Backend (API)
- **Directory**: `api/`
- **Dependencies**: `requirements.txt`
- **Manual Run**: `uvicorn main:app --reload` (Local only, relies on env vars)

### Testing
- **Directory**: `tests/`
- **Status**: Temporary/Manual scripts.
- **Run**: `python tests/test_api.py` (Run locally or inside container depending on env access)

## Architecture & Code Structure

### Backend (`api/`)
- **Entry**: `main.py`
- **Routers**: `routers/` (Modular endpoints: `game_routes.py`, `combat.py`, `auth.py`, etc.)
- **Core**: `core/` (Config, Security, WebSockets)
- **Services**: `services/` (Models, Helpers)
- **Pattern**: 
    - Use `routers` for new features.
    - Register routers in `main.py` (auto-registration logic exists but explicit is clearer).
    - Pydantic models in `services/models.py`.

### Frontend (`pwa/`)
- **Entry**: `src/main.tsx`
- **Styling**: Standard CSS files per component (e.g., `components/Game.css`). No Tailwind/Modules.
- **State**: Zustand stores (`src/stores/`).
- **Translation**: i18next (`src/i18n/`).

## Style Guidelines
- **Python**: PEP8 standard. No strict linter enforced.
- **TypeScript**: Standard ESLint rules from Vite template.
- **CSS**: Plain CSS. Keep component styles in dedicated files.
- **Docs**: update `QUICK_REFERENCE.md` if simplified logic or architecture changes.