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.