first commit

2025-11-24 23:10:55 -06:00
commit 8315fa51c9
279 changed files with 74600 additions and 0 deletions
--- a/api/README.md
+++ b/api/README.md
@@ -0,0 +1,204 @@
+# 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