echoes-of-the-ash/GEMINI.md

GEMINI.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 (This does not apply changes to the code)
• View Logs: docker compose logs -f [service_name] (e.g., echoes_of_the_ashes_api, echoes_of_the_ashes_pwa)

Frontend (PWA)

• Directory: pwa/
• Build and run: docker compose build echoes_of_the_ashes_pwa && docker compose up -d (Required for both code and env changes)

Backend (API)

• Directory: api/
• Dependencies: requirements.txt
• Build and run: docker compose build echoes_of_the_ashes_api && docker compose up -d (Required for both code and env changes)

Testing

• No automated testing
• Do not use the automated browser

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. Read VISUALS_GUIDE.md for styling guidelines.
• State: Zustand stores (src/stores/).
• Translation: i18next (src/i18n/).
• Reusable Components: src/components/common/ (e.g., Button.tsx, Modal.tsx, etc.)

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. Read VISUALS_GUIDE.md for styling guidelines.
• Docs: update QUICK_REFERENCE.md if simplified logic or architecture changes.