# 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