205 lines
4.5 KiB
Markdown
205 lines
4.5 KiB
Markdown
# 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
|