character-browser/DEVELOPMENT_GUIDE.md

Feature Development Guide: Gallery Pages & Character Integration

This guide outlines the architectural patterns and best practices developed during the implementation of the Actions, Outfits, and Styles galleries. Use this as a blueprint for adding similar features (e.g., "Scenes", "Props", "Effects").

1. Data Model & Persistence

• Database Model: Add a new class in models.py. Include default_fields (JSON) to support persistent prompt selections.
• JSON Sync: Implement a sync_[feature]() function in app.py to keep the SQLite database in sync with the data/[feature]/*.json files.
• Slugs: Use URL-safe slugs generated from the ID for clean routing.

2. Quadruple LoRA Chaining

Our workflow supports chaining up to four distinct LoRAs from specific directories:

1. Character: Illustrious/Looks/ (Node 16)
2. Outfit: Illustrious/Clothing/ (Node 17)
3. Action: Illustrious/Poses/ (Node 18)
4. Style: Illustrious/Styles/ (Node 19)

Implementation Detail: In _prepare_workflow, LoRAs must be chained sequentially. If a previous LoRA is missing, the next one must "reach back" to the Checkpoint (Node 4) or the last valid node in the chain to maintain the model/CLIP connection. Node 19 is the terminal LoRA loader before terminal consumers (KSampler, Detailers).

3. Style Prompt Construction

Artistic styles follow specific formatting rules in the build_prompt engine:

• Artist Attribution: Artist names are prefixed with "by " (e.g., "by Sabu").
• Artistic Styles: Raw descriptive style tags (e.g., "watercolor painting") are appended to the prompt.
• Priority: Style tags are applied after identity and wardrobe tags but before trigger words.

4. Adetailer Routing

To improve generation quality, route specific JSON sub-fields to targeted Adetailers:

• Face Detailer (Node 14): Receives character_name, expression, and action-specific head/eyes tags.
• Hand Detailer (Node 15): Receives priority hand tags (Wardrobe Gloves > Wardrobe Hands > Identity Hands) and action-specific arms/hands tags.

5. Character-Integrated Previews

The "Killer Feature" is previewing a standalone item (like an Action, Outfit, or Style) on a specific character.

Logic Flow:

1. Merge Data: Copy character.data.
2. Override/Merge: Replace character defaults with feature-specific tags (e.g., Action pose overrides Character pose).
3. Context Injection: Append character-specific styles (e.g., [primary_color] simple background) to the main prompt.
4. Auto-Selection: When a character is selected, ensure their essential identity and active wardrobe fields are automatically included in the prompt.

6. UI/UX Patterns

• Selection Boxes: Use checkboxes next to field labels to allow users to toggle specific tags.
• Default Selection: Implement a "Save as Default Selection" button that persists the current checkbox state to the database.
• Session State: Store the last selected character and field preferences in the Flask session to provide a seamless experience.
• AJAX Generation: Use the WebSocket + Polling hybrid pattern in the frontend to show real-time progress bars without page reloads.

7. Directory Isolation

Always isolate LoRAs by purpose to prevent dropdown clutter:

• get_available_loras() -> Characters
• get_available_clothing_loras() -> Outfits
• get_available_action_loras() -> Actions/Poses
• get_available_style_loras() -> Styles