first commit
This commit is contained in:
284
CLAUDE.md
Normal file
284
CLAUDE.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# CLAUDE.md
|
||||
|
||||
## Project Overview
|
||||
"Code Of Conquest" is a web-based AI-powered Dungeons & Dragons style game where Claude acts as the Dungeon Master. Players create characters, explore worlds, engage in turn-based combat, and interact with an AI-driven narrative system.
|
||||
|
||||
**Tech Stack:** Flask + Jinja2 + HTMX + Appwrite + RQ + Redis + Anthropic/Replicate APIs
|
||||
**Target Delivery:** Progressive Web App (PWA)
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
This repository contains three independent deployable components:
|
||||
|
||||
- **[/api](api/)** - Flask REST API backend (all business logic, models, services)
|
||||
- **[/public_web](public_web/)** - Flask web frontend (HTML/HTMX UI, calls API)
|
||||
- **[/godot_client](godot_client/)** - Godot game client (native cross-platform)
|
||||
|
||||
## Documentation Index
|
||||
|
||||
**Project-Wide:**
|
||||
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture, tech stack details, component design
|
||||
- **[ROADMAP.md](docs/ROADMAP.md)** - Development roadmap and phases
|
||||
- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Testing, deployment, monitoring, security
|
||||
- **[WEB_VS_CLIENT_SYSTEMS.md](docs/WEB_VS_CLIENT_SYSTEMS.md)** - Feature distribution between web and Godot clients
|
||||
|
||||
**API Backend:**
|
||||
- **[API_REFERENCE.md](api/docs/API_REFERENCE.md)** - API endpoints and response formats
|
||||
- **[DATA_MODELS.md](api/docs/DATA_MODELS.md)** - Character system, items, skills, effects, sessions
|
||||
- **[GAME_SYSTEMS.md](api/docs/GAME_SYSTEMS.md)** - Combat mechanics, marketplace, NPCs
|
||||
- **[QUEST_SYSTEM.md](api/docs/QUEST_SYSTEM.md)** - Quest mechanics and data structures
|
||||
- **[STORY_PROGRESSION.md](api/docs/STORY_PROGRESSION.md)** - Story progression system
|
||||
- **[MULTIPLAYER.md](api/docs/MULTIPLAYER.md)** - Multiplayer session backend logic
|
||||
- **[API_TESTING.md](api/docs/API_TESTING.md)** - API testing guide
|
||||
- **[APPWRITE_SETUP.md](api/docs/APPWRITE_SETUP.md)** - Database setup
|
||||
- **[PHASE4_IMPLEMENTATION.md](api/docs/PHASE4_IMPLEMENTATION.md)** - Phase 4 detailed implementation tasks
|
||||
|
||||
> **Documentation Hierarchy:** `/docs/ROADMAP.md` is the single source for project progress. Service-specific docs (`/api/docs/`, `/public_web/docs/`, `/godot_client/docs/`) contain implementation details.
|
||||
|
||||
**Web Frontend:**
|
||||
- **[TEMPLATES.md](public_web/docs/TEMPLATES.md)** - Template structure and conventions
|
||||
- **[HTMX_PATTERNS.md](public_web/docs/HTMX_PATTERNS.md)** - HTMX integration patterns
|
||||
- **[TESTING.md](public_web/docs/TESTING.md)** - Manual testing guide
|
||||
- **[MULTIPLAYER.md](public_web/docs/MULTIPLAYER.md)** - Multiplayer UI implementation
|
||||
|
||||
**Godot Client:**
|
||||
- **[ARCHITECTURE.md](godot_client/docs/ARCHITECTURE.md)** - Client architecture
|
||||
- **[GETTING_STARTED.md](godot_client/docs/GETTING_STARTED.md)** - Setup and usage
|
||||
- **[EXPORT.md](godot_client/docs/EXPORT.md)** - Platform export guide
|
||||
- **[THEME_SETUP.md](godot_client/docs/THEME_SETUP.md)** - UI theming guide
|
||||
- **[MULTIPLAYER.md](godot_client/docs/MULTIPLAYER.md)** - Multiplayer client implementation
|
||||
- **[scene_char_list.md](godot_client/docs/scene_char_list.md)** - Character list scene implementation
|
||||
|
||||
---
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Project Structure
|
||||
|
||||
**Microservices Architecture:**
|
||||
|
||||
The repository is organized into three independent components:
|
||||
|
||||
1. **`/api`** - REST API Backend
|
||||
- Source code in `/api/app`
|
||||
- All business logic, models, services
|
||||
- Modular organization:
|
||||
- `/api/app/api/` - API endpoint blueprints
|
||||
- `/api/app/models/` - Data models (dataclasses)
|
||||
- `/api/app/services/` - Business logic & integrations
|
||||
- `/api/app/utils/` - Utilities
|
||||
- `/api/app/data/` - Game data (YAML)
|
||||
- Independent deployment with own `requirements.txt`, `config/`, `tests/`
|
||||
|
||||
2. **`/public_web`** - Web Frontend
|
||||
- Source code in `/public_web/app`
|
||||
- Lightweight view layer (makes HTTP calls to API)
|
||||
- Structure:
|
||||
- `/public_web/app/views/` - View blueprints
|
||||
- `/public_web/templates/` - Jinja2 templates
|
||||
- `/public_web/static/` - CSS, JS, images
|
||||
- Independent deployment with own `requirements.txt`, `config/`
|
||||
|
||||
3. **`/godot_client`** - Game Client
|
||||
- Godot 4.5 project
|
||||
- Makes HTTP calls to API
|
||||
- Independent deployment (exports to Desktop/Mobile/Web)
|
||||
|
||||
**Each component:**
|
||||
- Has its own virtual environment
|
||||
- Deploys independently
|
||||
- Shares no code (API is single source of truth)
|
||||
- Typed config loaders (YAML-driven)
|
||||
|
||||
### 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`)
|
||||
|
||||
**Templates & UI**
|
||||
- Don't mix large HTML/CSS blocks in Python code
|
||||
- Prefer Jinja templates for HTML rendering
|
||||
- Clean CSS, minimal inline clutter, readable template logic
|
||||
|
||||
**Writing & Documentation**
|
||||
- Markdown documentation
|
||||
- Clear section headers
|
||||
- Roadmap/Phase/Feature-Session style documents
|
||||
- Boilerplate templates first, then refinements
|
||||
|
||||
**Logging**
|
||||
- Use structlog (pip package)
|
||||
- Setup logging at app start: `logger = logging.get_logger(__file__)`
|
||||
|
||||
**Preferred Pip Packages**
|
||||
- API/Web Server: Flask
|
||||
- HTTP: Requests
|
||||
- Logging: Structlog
|
||||
- Scheduling: APScheduler
|
||||
|
||||
### Error Handling
|
||||
- Custom exception classes for domain-specific errors
|
||||
- Consistent error response formats (JSON structure)
|
||||
- Logging severity levels (ERROR vs WARNING)
|
||||
|
||||
### Configuration
|
||||
- Each component has environment-specific configs in its own `/config/*.yaml`
|
||||
- API: `/api/config/development.yaml`, `/api/config/production.yaml`
|
||||
- Web: `/public_web/config/development.yaml`, `/public_web/config/production.yaml`
|
||||
- `.env` for secrets (never committed)
|
||||
- Maintain `.env.example` in each component for documentation
|
||||
- Typed config loaders using dataclasses
|
||||
- Validation on startup
|
||||
|
||||
### Containerization & Deployment
|
||||
- Explicit Dockerfiles
|
||||
- Production-friendly hardening (distroless/slim when meaningful)
|
||||
- Clear build/push scripts that:
|
||||
- Use git branch as tag
|
||||
- Ask whether to tag `:latest`
|
||||
- Ask whether to push
|
||||
- Support private registries
|
||||
|
||||
### API Design
|
||||
- RESTful conventions
|
||||
- Versioning strategy (`/api/v1/...`)
|
||||
- Standardized response format:
|
||||
|
||||
```json
|
||||
{
|
||||
"app": "<APP NAME>",
|
||||
"version": "<APP VERSION>",
|
||||
"status": <HTTP STATUS CODE>,
|
||||
"timestamp": "<UTC ISO8601>",
|
||||
"request_id": "<optional request id>",
|
||||
"result": <data OR null>,
|
||||
"error": {
|
||||
"code": "<optional machine code>",
|
||||
"message": "<human message>",
|
||||
"details": {}
|
||||
},
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
|
||||
### Dependency Management
|
||||
- Use `requirements.txt` and virtual environments (`python3 -m venv venv`)
|
||||
- Use path `venv` for all virtual environments
|
||||
- Pin versions to version ranges
|
||||
- Activate venv before running code (unless in Docker)
|
||||
|
||||
### Testing Standards
|
||||
- Manual testing preferred for applications
|
||||
- **API Backend:** Maintain `api/docs/API_TESTING.md` with endpoint examples, curl/httpie commands, expected responses
|
||||
- **Unit tests:** Use pytest for API backend (`api/tests/`)
|
||||
- **Web Frontend:** Manual testing checklist in `public_web/README.md`
|
||||
- **Godot Client:** Manual testing via Godot editor
|
||||
|
||||
### Git Standards
|
||||
|
||||
**Branch Strategy:**
|
||||
- `master` - Production-ready code only
|
||||
- `dev` - Main development branch, integration point
|
||||
- `beta` - (Optional) Public pre-release testing
|
||||
|
||||
**Workflow:**
|
||||
- Feature work branches off `dev` (e.g., `feature/add-scheduler`)
|
||||
- Merge features back to `dev` for testing
|
||||
- Promote `dev` → `beta` for public testing (when applicable)
|
||||
- Promote `beta` (or `dev`) → `master` for production
|
||||
|
||||
**Commit Messages:**
|
||||
- Use conventional commit format: `feat:`, `fix:`, `docs:`, `refactor:`, etc.
|
||||
- Keep commits atomic and focused
|
||||
- Write clear, descriptive messages
|
||||
|
||||
**Tagging:**
|
||||
- Tag releases on `master` with semantic versioning (e.g., `v1.2.3`)
|
||||
- Optionally tag beta releases (e.g., `v1.2.3-beta.1`)
|
||||
|
||||
---
|
||||
|
||||
## Workflow Preference
|
||||
I follow a pattern: **brainstorm → design → code → revise**
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ CLAUDE WORKSPACE BELOW ⚠️
|
||||
|
||||
**The sections above define development preferences and standards.**
|
||||
**Everything below is working context for Claude to track project-specific information, decisions, and progress.**
|
||||
|
||||
---
|
||||
|
||||
## Current Project Status
|
||||
|
||||
**Status:** Repository Reorganization Complete
|
||||
**Last Updated:** November 17, 2025
|
||||
**Document Version:** 3.0
|
||||
|
||||
### Recent Changes
|
||||
|
||||
**Repository Reorganization (Nov 17, 2025):**
|
||||
- Split monolithic Flask app into microservices architecture
|
||||
- Created three independent components: `/api`, `/public_web`, `/godot_client`
|
||||
- Each component has separate dependencies, configs, and deployment
|
||||
- API backend contains all business logic
|
||||
- Web frontend and Godot client are thin clients that call API
|
||||
|
||||
### Active Decisions Log
|
||||
|
||||
- Using Flask over FastAPI (team familiarity, RQ handles async)
|
||||
- Using RQ over Celery (simpler setup, adequate for scale)
|
||||
- Using Appwrite (reduces infrastructure overhead, built-in auth/realtime)
|
||||
- Using Dataclasses over ORM (flexibility, no migrations, JSON storage)
|
||||
- Turn-based combat (simpler AI prompts, better for multiplayer, classic D&D)
|
||||
- **Microservices architecture** (independent deployment, API as single source of truth)
|
||||
|
||||
### Known Technical Debt
|
||||
|
||||
~~**Public Web Frontend Service Dependencies:** RESOLVED (Nov 21, 2025)~~
|
||||
- All views now use `APIClient` for HTTP requests to API backend
|
||||
- Stub service modules removed
|
||||
- Proper error handling with typed exceptions (`APIError`, `APINotFoundError`, etc.)
|
||||
- Session cookies forwarded to API for authentication
|
||||
|
||||
**Remaining Minor Items:**
|
||||
- Auth decorator doesn't re-validate expired API sessions (low priority)
|
||||
- Origin/class validation fetches full lists instead of single-item lookups (optimization opportunity)
|
||||
|
||||
### Next Steps
|
||||
|
||||
1. ~~Refactor `public_web` views to use HTTP API calls~~ ✅ Complete
|
||||
2. Test both API and web frontend independently
|
||||
3. Update Godot client to use new API structure (if needed)
|
||||
4. Continue Phase 4 development (quests, story progression, multiplayer)
|
||||
|
||||
---
|
||||
|
||||
## Notes for Claude Code
|
||||
|
||||
When implementing features:
|
||||
|
||||
1. **Start with models** - Define dataclasses first
|
||||
2. **Write tests** - TDD approach for game logic
|
||||
3. **API then UI** - Backend endpoints before frontend
|
||||
4. **Security first** - Validate inputs, check permissions
|
||||
5. **Cost conscious** - Monitor AI usage, implement limits
|
||||
6. **Keep it simple** - Prefer straightforward solutions
|
||||
7. **Document as you go** - Update documentation with decisions
|
||||
|
||||
**Remember:** Developer has strong security expertise (don't compromise security for convenience) and extensive infrastructure experience (focus on application logic).
|
||||
- memorize our godot workflow for the frontend.
|
||||
Reference in New Issue
Block a user