# 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:
```bash
python3 -m venv venv
source venv/bin/activate
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Configure environment:
```bash
cp .env.example .env
# Edit .env with your credentials
```

4. Initialize database:
```bash
python scripts/init_database.py
```

### Running Locally

**Development mode:**
```bash
# 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:**
```bash
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](docs/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:
```json
{
  "app": "Code of Conquest",
  "version": "0.1.0",
  "status": 200,
  "timestamp": "2025-01-15T10:30:00Z",
  "result": {...},
  "error": null
}
```

## Testing

Run tests with pytest:
```bash
# 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:**
```bash
rq worker ai_tasks combat_tasks marketplace_tasks --url redis://localhost:6379
```

**Monitor jobs:**
```bash
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](../CLAUDE.md) in the project root for:
- Coding standards
- Development workflow
- Project structure guidelines
- Git conventions

## Deployment

See [DEPLOYMENT.md](../docs/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