# CLAUDE.md - API Backend

## Service Overview
**API Backend** for Code of Conquest - The single source of truth for all business logic, game mechanics, and data operations.

**Tech Stack:** Flask + Appwrite + RQ + Redis + Replicate API (Llama-3/Claude models)
**Port:** 5000 (development), 5000 (production internal)
**Location:** `/api`

---

## Architecture Role

This API backend is the **single source of truth** for all game logic:
- ✅ All business logic
- ✅ Data models and validation
- ✅ Database operations (Appwrite)
- ✅ Authentication & authorization
- ✅ Game mechanics calculations
- ✅ AI orchestration (all models via Replicate API)
- ✅ Background job processing (RQ)

**What this service does NOT do:**
- ❌ No UI rendering (that's `/public_web` and `/godot_client`)
- ❌ No direct user interaction (only via API endpoints)

---

## Documentation Index

**API Backend Documentation:**
- **[API_REFERENCE.md](docs/API_REFERENCE.md)** - API endpoints and response formats
- **[DATA_MODELS.md](docs/DATA_MODELS.md)** - Character system, items, skills, effects
- **[GAME_SYSTEMS.md](docs/GAME_SYSTEMS.md)** - Combat mechanics, marketplace, NPCs
- **[QUEST_SYSTEM.md](docs/QUEST_SYSTEM.md)** - Quest mechanics and data structures
- **[STORY_PROGRESSION.md](docs/STORY_PROGRESSION.md)** - Story progression system
- **[MULTIPLAYER.md](docs/MULTIPLAYER.md)** - Multiplayer session backend logic
- **[API_TESTING.md](docs/API_TESTING.md)** - API testing guide with examples
- **[APPWRITE_SETUP.md](docs/APPWRITE_SETUP.md)** - Database setup guide
- **[PHASE4_IMPLEMENTATION.md](docs/PHASE4_IMPLEMENTATION.md)** - Phase 4 detailed implementation tasks

**Project-Wide Documentation:**
- **[../docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md)** - System architecture overview
- **[../docs/ROADMAP.md](../docs/ROADMAP.md)** - Development roadmap and progress tracking
- **[../docs/DEPLOYMENT.md](../docs/DEPLOYMENT.md)** - Deployment guide
- **[../docs/WEB_VS_CLIENT_SYSTEMS.md](../docs/WEB_VS_CLIENT_SYSTEMS.md)** - Feature distribution between frontends

**Documentation Hierarchy:**
- `/docs/` = Project-wide roadmap, architecture, and cross-service documentation
- `/api/docs/` = API-specific implementation details (endpoints, data models, game systems)

> **Note:** For overall project progress, always check `/docs/ROADMAP.md`. Service-specific docs contain implementation details.

---

## Development Guidelines

### Project Structure

```
api/
├── app/                    # Application code
│   ├── api/               # API endpoint blueprints
│   ├── models/            # Data models (dataclasses)
│   ├── services/          # Business logic & integrations
│   ├── utils/             # Utilities
│   ├── tasks/             # Background jobs (RQ)
│   ├── ai/                # AI integration
│   ├── game_logic/        # Game mechanics
│   └── data/              # Game data (YAML)
├── config/                # Configuration files
├── tests/                 # Test suite
├── scripts/               # Utility scripts
└── docs/                  # API documentation
```

### Coding Standards

**Style & Structure**
- Prefer longer, explicit code over compact one-liners
- Always include docstrings for functions/classes + inline comments
- Strongly prefer OOP-style code (classes over functional/nested functions)
- Strong typing throughout (dataclasses, TypedDict, Enums, type hints)
- Value future-proofing and expanded usage insights

**Data Design**
- Use dataclasses for internal data modeling
- Typed JSON structures
- Functions return fully typed objects (no loose dicts)
- Snapshot files in JSON or YAML
- Human-readable fields (e.g., `scan_duration`)

**Logging**
- Use structlog (pip package)
- Setup logging at app start: `logger = structlog.get_logger(__file__)`

**Preferred Pip Packages**
- API/Web Server: Flask
- HTTP: Requests
- Logging: Structlog
- Job Queue: RQ
- Testing: Pytest

### API Design Standards

**RESTful Conventions:**
- Use proper HTTP methods (GET, POST, PUT, DELETE)
- Resource-based URLs: `/api/v1/characters`, not `/api/v1/get_character`
- Versioning: `/api/v1/...`

**Standardized Response Format:**
```json
{
  "app": "Code of Conquest API",
  "version": "0.1.0",
  "status": 200,
  "timestamp": "2025-01-15T10:30:00Z",
  "request_id": "optional-request-id",
  "result": {
    "data": "..."
  },
  "error": null,
  "meta": {}
}
```

**Error Responses:**
```json
{
  "app": "Code of Conquest API",
  "version": "0.1.0",
  "status": 400,
  "timestamp": "2025-01-15T10:30:00Z",
  "result": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid character name",
    "details": {
      "field": "name",
      "issue": "Name must be between 3 and 50 characters"
    }
  }
}
```

### Error Handling
- Custom exception classes for domain-specific errors
- Consistent error response formats (use `app.utils.response`)
- Logging severity levels (ERROR vs WARNING)
- Never expose internal errors to clients (sanitize stack traces)

### Security Standards

**Authentication & Authorization**
- Use Appwrite Auth for user management
- HTTP-only cookies for session storage
- Session validation on every protected API call
- User ID verification (users can only access their own data)
- Use `@require_auth` decorator for protected endpoints

**Input Validation**
- Validate ALL JSON payloads against schemas
- Sanitize user inputs (character names, chat messages)
- Prevent injection attacks (SQL, NoSQL, command injection)
- Use bleach for HTML sanitization

**Rate Limiting**
- AI endpoint limits based on subscription tier
- Use Flask-Limiter with Redis backend
- Configure limits in `config/*.yaml`

**API Security**
- CORS properly configured (only allow frontend domains)
- API keys stored in environment variables (never in code)
- Appwrite permissions set correctly on all collections
- HTTPS only in production

**Cost Control (AI)**
- Daily limits on AI calls per tier
- Max tokens per request type
- Cost logging for analytics and alerts
- Graceful degradation if limits exceeded

### Configuration
- Environment-specific configs in `/config/*.yaml`
  - `development.yaml` - Local dev settings
  - `production.yaml` - Production settings
- `.env` for secrets (never committed)
- Maintain `.env.example` for documentation
- Typed config loaders using dataclasses
- Validation on startup

### Testing Standards

**Unit Tests (Pytest):**
- Test all models, services, game logic
- Test files in `/tests`
- Run with: `pytest`
- Coverage: `pytest --cov=app tests/`

**Integration Tests:**
- Test API endpoints end-to-end
- Use test database/fixtures
- Example: `tests/test_api_characters_integration.py`

**API Testing:**
- Maintain `docs/API_TESTING.md` with curl/httpie examples
- Document expected responses
- Test all endpoints manually before commit

### Dependency Management
- Use `requirements.txt` in `/api` directory
- Use virtual environment: `python3 -m venv venv`
- Pin versions to version ranges
- Activate venv before running: `source venv/bin/activate`

### Background Jobs (RQ)

**Queue Types:**
- `ai_tasks` - AI narrative generation
- `combat_tasks` - Combat processing
- `marketplace_tasks` - Auction cleanup, periodic tasks

**Job Implementation:**
- Define jobs in `app/tasks/`
- Use `@job` decorator from RQ
- Jobs should be idempotent (safe to retry)
- Log job start, completion, errors

**Running Workers:**
```bash
rq worker ai_tasks combat_tasks marketplace_tasks --url redis://localhost:6379
```

---

## Workflow for API Development

When implementing new API features:

1. **Start with models** - Define dataclasses in `app/models/`
2. **Write tests** - TDD approach (test first, then implement)
3. **Implement service** - Business logic in `app/services/`
4. **Create endpoint** - API blueprint in `app/api/`
5. **Test manually** - Use curl/httpie, update `docs/API_TESTING.md`
6. **Security review** - Check auth, validation, rate limiting
7. **Document** - Update `docs/API_REFERENCE.md`

**Example Flow:**
```bash
# 1. Create model
# app/models/quest.py - Define Quest dataclass

# 2. Write test
# tests/test_quest.py - Test quest creation, validation

# 3. Implement service
# app/services/quest_service.py - Quest CRUD operations

# 4. Create endpoint
# app/api/quests.py - REST endpoints

# 5. Test
curl -X POST http://localhost:5000/api/v1/quests \
  -H "Content-Type: application/json" \
  -d '{"title": "Find the Ancient Relic"}'

# 6. Document
# Update docs/API_REFERENCE.md and docs/API_TESTING.md
```

---

## Running the API Backend

### Development

**Prerequisites:**
- Python 3.11+
- Redis running (via Docker Compose)
- Appwrite instance configured

**Setup:**
```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
```

**Initialize Database:**
```bash
python scripts/init_database.py
```

**Run Development Server:**
```bash
# Terminal 1: Redis
docker-compose up

# Terminal 2: API Server
source venv/bin/activate
export FLASK_ENV=development
python wsgi.py  # → http://localhost:5000

# Terminal 3: RQ Worker (optional)
source venv/bin/activate
rq worker ai_tasks --url redis://localhost:6379
```

### Production

**Run with Gunicorn:**
```bash
gunicorn --bind 0.0.0.0:5000 --workers 4 wsgi:app
```

**Environment Variables:**
```
FLASK_ENV=production
APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
APPWRITE_PROJECT_ID=...
APPWRITE_API_KEY=...
APPWRITE_DATABASE_ID=...
ANTHROPIC_API_KEY=...
REPLICATE_API_TOKEN=...
REDIS_URL=redis://redis:6379
SECRET_KEY=...
```

---

## Git Standards

**Commit Messages:**
- Use conventional commit format: `feat:`, `fix:`, `docs:`, `refactor:`, etc.
- Examples:
  - `feat(api): add quest endpoints`
  - `fix(models): character stat calculation bug`
  - `docs(api): update API_REFERENCE with quest endpoints`

**Branch Strategy:**
- Branch off `dev` for features
- Merge back to `dev` for testing
- Promote to `master` for production

---

## Notes for Claude Code

When working on the API backend:

1. **Business logic lives here** - This is the single source of truth
2. **No UI code** - Don't create templates or frontend code in this service
3. **Security first** - Validate inputs, check permissions, sanitize outputs
4. **Cost conscious** - Monitor AI usage, implement limits
5. **Test thoroughly** - Use pytest, write integration tests
6. **Document as you go** - Update API_REFERENCE.md and API_TESTING.md
7. **Think about frontends** - Design endpoints that work for both web and Godot clients

**Remember:**
- Developer has strong security expertise (don't compromise security for convenience)
- Developer has extensive infrastructure experience (focus on application logic)
- This API serves multiple frontends (web and Godot) - keep it generic