Code_of_Conquest/api

Code of Conquest - API Backend

Flask-based REST API backend for Code of Conquest, an AI-powered D&D-style game.

Overview

This is the API backend component of Code of Conquest. It provides:

• RESTful API endpoints for game functionality
• Business logic and game mechanics
• Database operations (Appwrite)
• AI integration (Claude, Replicate)
• Background job processing (RQ + Redis)
• Authentication and authorization

Architecture

Tech Stack:

• Framework: Flask 3.x
• Database: Appwrite (NoSQL)
• Job Queue: RQ (Redis Queue)
• Cache: Redis
• AI: Anthropic Claude, Replicate
• Logging: Structlog
• WSGI Server: Gunicorn

Key Components:

• /app/api - API endpoint blueprints
• /app/models - Data models (dataclasses)
• /app/services - Business logic and external integrations
• /app/utils - Helper functions
• /app/tasks - Background job handlers
• /app/data - Game data (YAML files)

Setup

Prerequisites

• Python 3.11+
• Redis server
• Appwrite instance (cloud or self-hosted)

Installation

1. Create virtual environment:

python3 -m venv venv
source venv/bin/activate

2. Install dependencies:

pip install -r requirements.txt

3. Configure environment:

cp .env.example .env
# Edit .env with your credentials

4. Initialize database:

python scripts/init_database.py

Running Locally

Development mode:

# Make sure Redis is running
docker-compose up -d

# Activate virtual environment
source venv/bin/activate

# Set environment
export FLASK_ENV=development

# Run development server
python wsgi.py

The API will be available at http://localhost:5000

Production mode:

gunicorn --bind 0.0.0.0:5000 --workers 4 wsgi:app

Configuration

Environment-specific configs are in /config:

• development.yaml - Local development settings
• production.yaml - Production settings

Key settings:

• Server: Port, workers
• Redis: Connection settings
• RQ: Queue configuration
• AI: Model settings, rate limits
• Auth: Session, password requirements
• CORS: Allowed origins

API Documentation

See API_REFERENCE.md for complete endpoint documentation.

Base URL

• Development: http://localhost:5000
• Production: https://api.codeofconquest.com

Authentication

Uses Appwrite session-based authentication with HTTP-only cookies.

Response Format

All endpoints return standardized JSON responses:

{
  "app": "Code of Conquest",
  "version": "0.1.0",
  "status": 200,
  "timestamp": "2025-01-15T10:30:00Z",
  "result": {...},
  "error": null
}

Testing

Run tests with pytest:

# Activate virtual environment
source venv/bin/activate

# Run all tests
pytest

# Run with coverage
pytest --cov=app tests/

# Run specific test file
pytest tests/test_character.py

Background Jobs

The API uses RQ for background processing:

Start RQ worker:

rq worker ai_tasks combat_tasks marketplace_tasks --url redis://localhost:6379

Monitor jobs:

rq info --url redis://localhost:6379

Directory Structure

api/
├── app/                    # Application code
│   ├── api/               # API endpoint blueprints
│   ├── models/            # Data models
│   ├── services/          # Business logic
│   ├── utils/             # Utilities
│   ├── tasks/             # Background jobs
│   ├── ai/                # AI integration
│   ├── game_logic/        # Game mechanics
│   └── data/              # Game data (YAML)
├── config/                # Configuration files
├── tests/                 # Test suite
├── scripts/               # Utility scripts
├── logs/                  # Application logs
├── docs/                  # API documentation
├── requirements.txt       # Python dependencies
├── wsgi.py               # WSGI entry point
├── docker-compose.yml    # Redis service
└── .env.example          # Environment template

Development

See CLAUDE.md in the project root for:

• Coding standards
• Development workflow
• Project structure guidelines
• Git conventions

Deployment

See DEPLOYMENT.md for production deployment instructions.

Related Components

• Public Web: /public_web - Traditional web frontend
• Godot Client: /godot_client - Native game client

Both frontends consume this API backend.

License

Proprietary - All rights reserved