first commit
This commit is contained in:
366
api/CLAUDE.md
Normal file
366
api/CLAUDE.md
Normal file
@@ -0,0 +1,366 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user