# 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:**
```bash
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`](api/CLAUDE.md) and [`/api/docs/`](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:**
```bash
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`](public_web/CLAUDE.md) and [`/public_web/docs/`](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:**
```bash
# Open in Godot Editor
godot --editor godot_client/project.godot

# Or run directly
godot godot_client/project.godot
```

**Documentation:** See [`/godot_client/CLAUDE.md`](godot_client/CLAUDE.md) and [`/godot_client/docs/`](godot_client/docs/)

---

## Documentation Index

### Project-Wide Documentation (`/docs`)
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture and tech stack
- **[ROADMAP.md](docs/ROADMAP.md)** - Development roadmap and phases
- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Deployment, testing, and operations
- **[WEB_VS_CLIENT_SYSTEMS.md](docs/WEB_VS_CLIENT_SYSTEMS.md)** - Feature distribution between web and Godot clients

### API Backend Documentation (`/api/docs`)
- **[API_REFERENCE.md](api/docs/API_REFERENCE.md)** - API endpoints and response formats
- **[DATA_MODELS.md](api/docs/DATA_MODELS.md)** - Character system, items, skills, effects
- **[GAME_SYSTEMS.md](api/docs/GAME_SYSTEMS.md)** - Combat mechanics, marketplace, NPCs
- **[QUEST_SYSTEM.md](api/docs/QUEST_SYSTEM.md)** - Quest mechanics and data structures
- **[STORY_PROGRESSION.md](api/docs/STORY_PROGRESSION.md)** - Story progression system
- **[MULTIPLAYER.md](api/docs/MULTIPLAYER.md)** - Multiplayer session backend logic
- **[API_TESTING.md](api/docs/API_TESTING.md)** - API testing guide
- **[APPWRITE_SETUP.md](api/docs/APPWRITE_SETUP.md)** - Database setup

### Web Frontend Documentation (`/public_web/docs`)
- **[TEMPLATES.md](public_web/docs/TEMPLATES.md)** - Template structure and conventions
- **[HTMX_PATTERNS.md](public_web/docs/HTMX_PATTERNS.md)** - HTMX integration patterns
- **[TESTING.md](public_web/docs/TESTING.md)** - Manual testing guide
- **[MULTIPLAYER.md](public_web/docs/MULTIPLAYER.md)** - Multiplayer UI implementation

### Godot Client Documentation (`/godot_client/docs`)
- **[ARCHITECTURE.md](godot_client/docs/ARCHITECTURE.md)** - Client architecture
- **[GETTING_STARTED.md](godot_client/docs/GETTING_STARTED.md)** - Setup and usage
- **[EXPORT.md](godot_client/docs/EXPORT.md)** - Platform export guide
- **[THEME_SETUP.md](godot_client/docs/THEME_SETUP.md)** - UI theming guide
- **[MULTIPLAYER.md](godot_client/docs/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:

```bash
# 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

```bash
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)

```bash
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)

```bash
# 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.:

```bash
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](docs/ROADMAP.md) for full development plan.

---

## Development Guidelines

Each component follows its own development guidelines:

- **API Backend:** See [`api/CLAUDE.md`](api/CLAUDE.md) for backend development standards
- **Web Frontend:** See [`public_web/CLAUDE.md`](public_web/CLAUDE.md) for frontend development standards
- **Godot Client:** See [`godot_client/CLAUDE.md`](godot_client/CLAUDE.md) for client development standards
- **Project-Wide:** See [`CLAUDE.md`](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
```bash
cd api
pytest
# See api/docs/API_TESTING.md
```

### Web Frontend
Manual testing preferred. See [`public_web/docs/TESTING.md`](public_web/docs/TESTING.md)

### Godot Client
Manual testing via Godot editor. See [`godot_client/docs/README.md`](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](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`](docs/).