221 lines
5.1 KiB
Markdown
221 lines
5.1 KiB
Markdown
# 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
|