first commit

2025-11-24 23:10:55 -06:00
commit 8315fa51c9
279 changed files with 74600 additions and 0 deletions
--- a/public_web/README.md
+++ b/public_web/README.md
@@ -0,0 +1,220 @@
+# Code of Conquest - Public Web Frontend
+
+Traditional web frontend for Code of Conquest, providing HTML/HTMX UI for browser-based gameplay.
+
+## Overview
+
+This is the **public web frontend** component of Code of Conquest. It provides:
+
+- HTML-based UI using Jinja2 templates
+- Interactive forms with HTMX
+- Character creation wizard
+- Session-based authentication
+- Responsive design
+
+**Architecture:** Lightweight view layer that makes HTTP requests to the API backend for all business logic.
+
+## Tech Stack
+
+- **Framework:** Flask 3.x
+- **Templates:** Jinja2
+- **Interactivity:** HTMX
+- **Styling:** Vanilla CSS
+- **API Client:** Python requests library
+- **Logging:** Structlog
+- **WSGI Server:** Gunicorn
+
+## Setup
+
+### Prerequisites
+- Python 3.11+
+- Running API backend (see `/api`)
+
+### 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 settings
+```
+
+### Running Locally
+
+**Development mode:**
+```bash
+# Activate virtual environment
+source venv/bin/activate
+
+# Set environment
+export FLASK_ENV=development
+
+# Run development server
+python wsgi.py
+```
+
+The web UI will be available at `http://localhost:5001`
+
+**Production mode:**
+```bash
+gunicorn --bind 0.0.0.0:8080 --workers 4 wsgi:app
+```
+
+## Configuration
+
+Environment-specific configs are in `/config`:
+- `development.yaml` - Local development settings
+- `production.yaml` - Production settings
+
+Key settings:
+- **Server:** Port (5001 dev, 8080 prod), workers
+- **API:** Backend URL, timeout
+- **Session:** Cookie settings, lifetime
+- **UI:** Theme, pagination
+
+## Project Structure
+
+```
+public_web/
+├── app/                   # Application code
+│   ├── views/            # View blueprints (Flask routes)
+│   └── utils/            # Utilities (logging, auth helpers, API client)
+├── templates/            # Jinja2 HTML templates
+│   ├── auth/            # Authentication pages
+│   ├── character/       # Character pages
+│   ├── errors/          # Error pages (404, 500)
+│   └── base.html        # Base template
+├── static/              # CSS, JS, images
+│   └── css/            # Stylesheets
+├── docs/                # Service-specific documentation
+├── config/              # Configuration files
+├── logs/                # Application logs
+├── requirements.txt     # Python dependencies
+├── wsgi.py             # WSGI entry point
+└── .env.example        # Environment template
+```
+
+## Features
+
+### Authentication
+- Login / Register
+- Password reset
+- Email verification
+- Session management
+
+### Character Management
+- Character creation wizard (4 steps)
+  1. Origin selection
+  2. Class selection
+  3. Customization
+  4. Confirmation
+- Character list view
+- Character detail page
+
+### UI/UX
+- Dark theme
+- Responsive design
+- HTMX-powered interactivity
+- Form validation
+- Loading states
+
+## Development
+
+### Adding New Pages
+
+1. Create template in `/templates`:
+```html
+{% extends "base.html" %}
+{% block content %}
+  <!-- Your content -->
+{% endblock %}
+```
+
+2. Create view in `/app/views`:
+```python
+@blueprint.route('/your-route')
+def your_view():
+    return render_template('your_template.html')
+```
+
+3. Register blueprint in `/app/__init__.py`
+
+### Making API Calls
+
+All views use the `APIClient` class to communicate with the API backend:
+
+```python
+from app.utils.api_client import get_api_client, APIError
+
+api_client = get_api_client()
+
+# GET request
+try:
+    response = api_client.get("/api/v1/characters")
+    characters = response.get('result', {}).get('characters', [])
+except APIError as e:
+    flash(f'Error: {e.message}', 'error')
+
+# POST request
+response = api_client.post("/api/v1/characters", data={
+    'name': 'Hero',
+    'class_id': 'warrior',
+    'origin_id': 'noble'
+})
+```
+
+The API client handles:
+- Session cookie forwarding
+- Error handling with typed exceptions (`APIError`, `APINotFoundError`, `APITimeoutError`)
+- JSON serialization/deserialization
+- SSL verification and timeouts from config
+
+## Testing
+
+Currently, the public web frontend relies on manual testing. Use the API for automated testing.
+
+**Manual testing checklist:**
+- [ ] Login flow
+- [ ] Registration flow
+- [ ] Character creation wizard (all 4 steps)
+- [ ] Character list and detail views
+- [ ] Logout
+- [ ] Error handling
+
+## Deployment
+
+See [DEPLOYMENT.md](../docs/DEPLOYMENT.md) for production deployment instructions.
+
+### Environment Variables
+
+Required environment variables:
+- `FLASK_ENV` - development or production
+- `SECRET_KEY` - Flask session secret (generate random string)
+- `API_BASE_URL` - (Optional) API backend URL
+
+## Related Components
+
+- **API Backend:** `/api` - REST API that this frontend calls
+- **Godot Client:** `/godot_client` - Alternative native game client
+
+## Development Guidelines
+
+See [CLAUDE.md](../CLAUDE.md) in the project root for:
+- Coding standards
+- Template best practices
+- Git conventions
+- Project workflow
+
+## License
+
+Proprietary - All rights reserved