Code of Conquest

An AI-powered Dungeons & Dragons style game where Claude acts as the Dungeon Master.

Status: Active Development Version: 0.2.0 Architecture: Microservices (API Backend + Web Frontend + Godot Client)

---

Overview

Code of Conquest is a multi-platform RPG game powered by AI. Players create characters, explore worlds, engage in turn-based combat, and experience dynamic narratives generated by Claude AI.

Available Clients:

• Web Frontend - Browser-based play via HTMX and Jinja2 templates
• Godot Client - Native desktop/mobile application

Both clients communicate with a centralized REST API backend that handles all game logic, AI integration, and data persistence.

---

Repository Structure

This repository contains three independent, deployable components:

1. API Backend (/api)

REST API that serves as the single source of truth for all game logic.

Technology: Flask + Appwrite + RQ + Redis + Anthropic/Replicate APIs

Responsibilities:

• All business logic and game mechanics
• Character, session, and combat management
• AI narrative generation
• Authentication and authorization
• Background job processing
• Database operations

Quick Start:

cd api
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # Configure your API keys
python wsgi.py  # → http://localhost:5000

Documentation: See /api/CLAUDE.md and /api/docs/

---

2. Web Frontend (/public_web)

Lightweight Flask web application that provides browser-based gameplay.

Technology: Flask + Jinja2 + HTMX + Appwrite Realtime

Responsibilities:

• UI/UX rendering (HTML templates)
• User interactions (HTMX for AJAX)
• Realtime updates (WebSocket subscriptions)
• HTTP API calls to backend

Quick Start:

cd public_web
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # Configure API URL
python wsgi.py  # → http://localhost:8000

Documentation: See /public_web/CLAUDE.md and /public_web/docs/

---

3. Godot Client (/godot_client)

Native cross-platform game client built with Godot Engine 4.5.

Technology: Godot 4.5 + GDScript

Responsibilities:

• Rich game UI with animations
• Local game rendering
• HTTP API calls to backend
• Realtime WebSocket subscriptions
• Cross-platform exports (Desktop, Mobile, Web)

Quick Start:

# Open in Godot Editor
godot --editor godot_client/project.godot

# Or run directly
godot godot_client/project.godot

Documentation: See /godot_client/CLAUDE.md and /godot_client/docs/

---

Documentation Index

Project-Wide Documentation (/docs)

• ARCHITECTURE.md - System architecture and tech stack
• ROADMAP.md - Development roadmap and phases
• DEPLOYMENT.md - Deployment, testing, and operations
• WEB_VS_CLIENT_SYSTEMS.md - Feature distribution between web and Godot clients

API Backend Documentation (/api/docs)

• API_REFERENCE.md - API endpoints and response formats
• DATA_MODELS.md - Character system, items, skills, effects
• 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

Web Frontend Documentation (/public_web/docs)

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

Godot Client Documentation (/godot_client/docs)

• 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

---

Prerequisites

All Components

• Git
• Docker & Docker Compose (for Redis and Appwrite)

API Backend & Web Frontend

• Python 3.11+
• pip
• virtualenv

Godot Client

• Godot 4.5+

---

Quick Start (Full Stack)

1. Start Shared Services

Both the API backend and web frontend require Redis and Appwrite:

# Start Redis
docker-compose up -d redis

# Start Appwrite (or use Appwrite Cloud)
# Follow api/docs/APPWRITE_SETUP.md for configuration

2. Start API Backend

cd api
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your credentials
python scripts/init_database.py  # Initialize Appwrite collections
python wsgi.py  # Runs on http://localhost:5000

3. Start Web Frontend (Optional)

cd public_web
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Configure API_BASE_URL=http://localhost:5000
python wsgi.py  # Runs on http://localhost:8000

4. Start Godot Client (Optional)

# Open in Godot Editor
godot --editor godot_client/project.godot

# Configure API endpoint in project settings
# Run the project from editor or export to platform

5. Start Background Workers (Optional)

For AI tasks, combat processing, etc.:

cd api
source venv/bin/activate
rq worker ai_tasks combat_tasks marketplace_tasks --url redis://localhost:6379

---

Architecture Overview

┌─────────────────────┐         ┌─────────────────────┐
│   Web Browser       │         │  Godot Client       │
│   (Public Web)      │         │  (Desktop/Mobile)   │
└──────────┬──────────┘         └──────────┬──────────┘
           │                               │
           │ HTTP (REST API)               │ HTTP (REST API)
           │ WebSocket (Realtime)          │ WebSocket (Realtime)
           │                               │
           └───────────────┬───────────────┘
                           │
                           ▼
                ┌──────────────────────┐
                │   API Backend        │
                │   (Flask REST API)   │
                │  - Business Logic    │
                │  - Game Mechanics    │
                │  - AI Integration    │
                │  - Auth & Sessions   │
                └──────────┬───────────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
           ▼               ▼               ▼
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │ Appwrite │    │  Redis   │    │ Claude AI│
    │ Database │    │  Queue   │    │ Replicate│
    └──────────┘    └──────────┘    └──────────┘

Key Principles:

• API Backend is the single source of truth for all game logic
• Web Frontend and Godot Client are thin clients (no business logic)
• All clients communicate with API via REST endpoints
• Realtime updates via Appwrite Realtime (WebSocket)
• Each component deploys independently

---

Tech Stack Summary

API Backend (/api)

• Flask 3.0+
• Python 3.11+
• Appwrite (database, auth, realtime)
• RQ (Redis Queue) for background jobs
• Anthropic Claude API
• Replicate API

Web Frontend (/public_web)

• Flask 3.0+ (view layer only)
• Jinja2 templates
• HTMX (AJAX interactions)
• Appwrite JavaScript SDK (realtime)
• Vanilla JavaScript

Godot Client (/godot_client)

• Godot Engine 4.5
• GDScript
• HTTP requests (via HTTPRequest node)
• WebSocket (via WebSocketPeer)

---

Current Development Phase

Phase 3: ✅ Complete - AI Integration & Story Progression

• AI-powered narrative generation
• Story progression system
• Quest system
• Combat AI

Phase 4: 🚧 In Progress - Quests, Story Progression, Multiplayer

• Quest offering and tracking
• Story arc progression
• Multiplayer sessions
• Godot client implementation

See docs/ROADMAP.md for full development plan.

---

Development Guidelines

Each component follows its own development guidelines:

• API Backend: See api/CLAUDE.md for backend development standards
• Web Frontend: See public_web/CLAUDE.md for frontend development standards
• Godot Client: See godot_client/CLAUDE.md for client development standards
• Project-Wide: See CLAUDE.md for overall project guidelines

Key Standards:

• Microservices architecture (no shared code)
• API is the single source of truth
• Strong typing throughout (dataclasses, type hints)
• Security first (authentication, validation, sanitization)
• Cost-conscious AI usage
• Comprehensive documentation

---

Testing

API Backend

cd api
pytest
# See api/docs/API_TESTING.md

Web Frontend

Manual testing preferred. See public_web/docs/TESTING.md

Godot Client

Manual testing via Godot editor. See godot_client/docs/README.md

---

Deployment

Each component deploys independently:

• API Backend: Docker container, Gunicorn, Nginx
• Web Frontend: Docker container, Gunicorn, Nginx
• Godot Client: Platform-specific exports (Windows, macOS, Linux, Android, iOS, Web)

See docs/DEPLOYMENT.md for detailed deployment instructions.

---

Contributing

This is a personal project. Contributions are not currently being accepted.

---

License

Proprietary. All rights reserved.

---

Contact

For questions or feedback, see project documentation in /docs.