echoes-of-the-ash/CLAUDE.md

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.