ptarrant/Code_of_Conquest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7c0e257540d1b4f03a5933f86c87ac9a4eb4be5d
Code_of_Conquest/README.md
Phillip Tarrant 8315fa51c9 first commit
2025-11-24 23:10:55 -06:00

364 lines
11 KiB
Markdown
Raw Blame History

# 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/).
Reference in New Issue View Git Blame Copy Permalink