Code_of_Conquest/CLAUDE.md

CLAUDE.md

Project Overview

"Code Of Conquest" is a web-based AI-powered Dungeons & Dragons style game where Claude acts as the Dungeon Master. Players create characters, explore worlds, engage in turn-based combat, and interact with an AI-driven narrative system.

Tech Stack: Flask + Jinja2 + HTMX + Appwrite + RQ + Redis + Anthropic/Replicate APIs Target Delivery: Progressive Web App (PWA)

---

Repository Structure

This repository contains three independent deployable components:

• /api - Flask REST API backend (all business logic, models, services)
• /public_web - Flask web frontend (HTML/HTMX UI, calls API)
• /godot_client - Godot game client (native cross-platform)

Documentation Index

Project-Wide:

• ARCHITECTURE.md - System architecture, tech stack details, component design
• ROADMAP.md - Development roadmap and phases
• DEPLOYMENT.md - Testing, deployment, monitoring, security
• WEB_VS_CLIENT_SYSTEMS.md - Feature distribution between web and Godot clients

API Backend:

• API_REFERENCE.md - API endpoints and response formats
• DATA_MODELS.md - Character system, items, skills, effects, sessions
• GAME_SYSTEMS.md - Combat mechanics, marketplace, NPCs
• QUEST_SYSTEM.md - Quest mechanics and data structures
• STORY_PROGRESSION.md - Story progression system
• MULTIPLAYER.md - Multiplayer session backend logic
• API_TESTING.md - API testing guide
• APPWRITE_SETUP.md - Database setup
• PHASE4_IMPLEMENTATION.md - Phase 4 detailed implementation tasks

Documentation Hierarchy: /docs/ROADMAP.md is the single source for project progress. Service-specific docs (/api/docs/, /public_web/docs/, /godot_client/docs/) contain implementation details.

Web Frontend:

• TEMPLATES.md - Template structure and conventions
• HTMX_PATTERNS.md - HTMX integration patterns
• TESTING.md - Manual testing guide
• MULTIPLAYER.md - Multiplayer UI implementation

Godot Client:

• ARCHITECTURE.md - Client architecture
• GETTING_STARTED.md - Setup and usage
• EXPORT.md - Platform export guide
• THEME_SETUP.md - UI theming guide
• MULTIPLAYER.md - Multiplayer client implementation
• scene_char_list.md - Character list scene implementation

---

Development Guidelines

Project Structure

Microservices Architecture:

The repository is organized into three independent components:

1. /api - REST API Backend

   • Source code in /api/app
   • All business logic, models, services
   • Modular organization:
     • /api/app/api/ - API endpoint blueprints
     • /api/app/models/ - Data models (dataclasses)
     • /api/app/services/ - Business logic & integrations
     • /api/app/utils/ - Utilities
     • /api/app/data/ - Game data (YAML)
   • Independent deployment with own requirements.txt, config/, tests/

2. /public_web - Web Frontend

   • Source code in /public_web/app
   • Lightweight view layer (makes HTTP calls to API)
   • Structure:
     • /public_web/app/views/ - View blueprints
     • /public_web/templates/ - Jinja2 templates
     • /public_web/static/ - CSS, JS, images
   • Independent deployment with own requirements.txt, config/

3. /godot_client - Game Client

   • Godot 4.5 project
   • Makes HTTP calls to API
   • Independent deployment (exports to Desktop/Mobile/Web)

Each component:

• Has its own virtual environment
• Deploys independently
• Shares no code (API is single source of truth)
• Typed config loaders (YAML-driven)

Coding Standards

Style & Structure

• Prefer longer, explicit code over compact one-liners
• Always include docstrings for functions/classes + inline comments
• Strongly prefer OOP-style code (classes over functional/nested functions)
• Strong typing throughout (dataclasses, TypedDict, Enums, type hints)
• Value future-proofing and expanded usage insights

Data Design

• Use dataclasses for internal data modeling
• Typed JSON structures
• Functions return fully typed objects (no loose dicts)
• Snapshot files in JSON or YAML
• Human-readable fields (e.g., scan_duration)

Templates & UI

• Don't mix large HTML/CSS blocks in Python code
• Prefer Jinja templates for HTML rendering
• Clean CSS, minimal inline clutter, readable template logic

Writing & Documentation

• Markdown documentation
• Clear section headers
• Roadmap/Phase/Feature-Session style documents
• Boilerplate templates first, then refinements

Logging

• Use structlog (pip package)
• Setup logging at app start: logger = logging.get_logger(__file__)

Preferred Pip Packages

• API/Web Server: Flask
• HTTP: Requests
• Logging: Structlog
• Scheduling: APScheduler

Error Handling

• Custom exception classes for domain-specific errors
• Consistent error response formats (JSON structure)
• Logging severity levels (ERROR vs WARNING)

Configuration

• Each component has environment-specific configs in its own /config/*.yaml
  • API: /api/config/development.yaml, /api/config/production.yaml
  • Web: /public_web/config/development.yaml, /public_web/config/production.yaml
• .env for secrets (never committed)
• Maintain .env.example in each component for documentation
• Typed config loaders using dataclasses
• Validation on startup

Containerization & Deployment

• Explicit Dockerfiles
• Production-friendly hardening (distroless/slim when meaningful)
• Clear build/push scripts that:
  • Use git branch as tag
  • Ask whether to tag :latest
  • Ask whether to push
  • Support private registries

API Design

• RESTful conventions
• Versioning strategy (/api/v1/...)
• Standardized response format:

{
  "app": "<APP NAME>",
  "version": "<APP VERSION>",
  "status": <HTTP STATUS CODE>,
  "timestamp": "<UTC ISO8601>",
  "request_id": "<optional request id>",
  "result": <data OR null>,
  "error": {
    "code": "<optional machine code>",
    "message": "<human message>",
    "details": {}
  },
  "meta": {}
}

Dependency Management

• Use requirements.txt and virtual environments (python3 -m venv venv)
• Use path venv for all virtual environments
• Pin versions to version ranges
• Activate venv before running code (unless in Docker)

Testing Standards

• Manual testing preferred for applications
• API Backend: Maintain api/docs/API_TESTING.md with endpoint examples, curl/httpie commands, expected responses
• Unit tests: Use pytest for API backend (api/tests/)
• Web Frontend: Manual testing checklist in public_web/README.md
• Godot Client: Manual testing via Godot editor

Git Standards

Branch Strategy:

• master - Production-ready code only
• dev - Main development branch, integration point
• beta - (Optional) Public pre-release testing

Workflow:

• Feature work branches off dev (e.g., feature/add-scheduler)
• Merge features back to dev for testing
• Promote dev → beta for public testing (when applicable)
• Promote beta (or dev) → master for production

Commit Messages:

• Use conventional commit format: feat:, fix:, docs:, refactor:, etc.
• Keep commits atomic and focused
• Write clear, descriptive messages

Tagging:

• Tag releases on master with semantic versioning (e.g., v1.2.3)
• Optionally tag beta releases (e.g., v1.2.3-beta.1)

---

Workflow Preference

I follow a pattern: brainstorm → design → code → revise

---

⚠️ CLAUDE WORKSPACE BELOW ⚠️

The sections above define development preferences and standards. Everything below is working context for Claude to track project-specific information, decisions, and progress.

---

Current Project Status

Status: Repository Reorganization Complete Last Updated: November 17, 2025 Document Version: 3.0

Recent Changes

Repository Reorganization (Nov 17, 2025):

• Split monolithic Flask app into microservices architecture
• Created three independent components: /api, /public_web, /godot_client
• Each component has separate dependencies, configs, and deployment
• API backend contains all business logic
• Web frontend and Godot client are thin clients that call API

Active Decisions Log

• Using Flask over FastAPI (team familiarity, RQ handles async)
• Using RQ over Celery (simpler setup, adequate for scale)
• Using Appwrite (reduces infrastructure overhead, built-in auth/realtime)
• Using Dataclasses over ORM (flexibility, no migrations, JSON storage)
• Turn-based combat (simpler AI prompts, better for multiplayer, classic D&D)
• Microservices architecture (independent deployment, API as single source of truth)

Known Technical Debt

Public Web Frontend Service Dependencies: RESOLVED (Nov 21, 2025)

• All views now use APIClient for HTTP requests to API backend
• Stub service modules removed
• Proper error handling with typed exceptions (APIError, APINotFoundError, etc.)
• Session cookies forwarded to API for authentication

Remaining Minor Items:

• Auth decorator doesn't re-validate expired API sessions (low priority)
• Origin/class validation fetches full lists instead of single-item lookups (optimization opportunity)

Next Steps

1. Refactor public_web views to use HTTP API calls ✅ Complete
2. Test both API and web frontend independently
3. Update Godot client to use new API structure (if needed)
4. Continue Phase 4 development (quests, story progression, multiplayer)

---

Notes for Claude Code

When implementing features:

1. Start with models - Define dataclasses first
2. Write tests - TDD approach for game logic
3. API then UI - Backend endpoints before frontend
4. Security first - Validate inputs, check permissions
5. Cost conscious - Monitor AI usage, implement limits
6. Keep it simple - Prefer straightforward solutions
7. Document as you go - Update documentation with decisions

Remember: Developer has strong security expertise (don't compromise security for convenience) and extensive infrastructure experience (focus on application logic).

• memorize our godot workflow for the frontend.