design.md

# RPGPortrait Design Document

## Project Overview
RPGPortrait is a decoupled, modern web application for tabletop RPG players to build detailed prompts and generate character portraits. It follows a **Next.js (Frontend)** and **FastAPI (Backend)** architecture, utilizing a premium "Obsidian & Ember" dark-aesthetic UI.

## UI Design
The interface is a responsive, single-page application (SPA) with a primary content area and a secondary configuration hub.

### Layout Structure
- **Navigation Tabs**:
    - **Identity**: Core character traits (Race, Class, Gender, Age).
    - **Appearance**: Visual details (Hair, Eyes, Build, Distinguishing Features).
    - **Equipment**: Gear and artifacts (Armor, Weapons, Accessories).
    - **Environment**: Scene settings (Background, Lighting, Mood).
    - **Render Style**: Artistic direction (Art Style, VFX, Aspect Ratio).
    - **Configuration**: System management (AI Engines, API Tokens, Local Models).
- **Portrait Studio (Center)**:
    - **Full-Resolution Masterpiece**: Interactive image display with lightbox.
    - **Refinement Suite**: Narrative enhancement and renaming features.
    - **Action Bar**: Synthesize and Randomize controls.
- **State Management (Sidebar)**:
    - **Save/Load**: JSON-based state export/import.
    - **Prompt Preview**: Real-time technical prompt construction.

## Prompt Assembly Logic
The system uses a modular 3-stage pipeline:
1. **Technical Segmenting**: Assembles dropdown values into a base prompt using `features.yaml`.
2. **AI Refinement**: Transmutes technical tokens into vivid descriptions using LLMs (Gemini, Ollama, or HF). Instructions are stored in `prompts.yaml`.
3. **Image Synthesis**:
    - **Cloud**: Google Gemini (Imagen) or Hugging Face (Direct API/Router).
    - **Local**: ComfyUI via WebSocket/REST with dynamic workflow injection.

## Persistence & State
- **Milk and Cookies**: All UI selections and engine configurations are persisted in `localStorage`.
- **Metadata**: Generated images embed the full character prompt and name in PNG metadata (`tEXt` chunks).

## Technical Stack
- **Frontend**: Next.js 15, Tailwind CSS v4 (Glassmorphism), Lucide Icons.
- **Backend**: FastAPI (Python 3.11+), Uvicorn.
- **AI Backend**:
    - **Gemini**: `google-genai` SDK.
    - **Ollama**: Local REST API exploration.
    - **Hugging Face**: `huggingface_hub` and direct Router requests.
    - **ComfyUI**: WebSocket bridge for status and history tracking.

## Project Architecture
- **`api.py`**: FastAPI server hosting the REST API and serving the static frontend in production.
- **`frontend/src/`**: Next.js source code, components, and Tailwind styles.
- **`modules/`**: Shared backend logic for integrations, prompt assembly, and config.
- **`features.yaml` / `prompts.yaml`**: Externalized data and instruction layers.

## Maintenance & Development
- **Dev Servers**: 
    - Frontend: `npm run dev` (Port 3000)
    - Backend: `python api.py` (Port 8000)
- **Deployment**: Configured for Hugging Face Spaces via Docker. Static export mode is used for high-performance delivery.