Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
97 lines (65 loc) · 7.4 KB

ARCHITECTURE.md

File metadata and controls

97 lines (65 loc) · 7.4 KB

🧬 CharacterCraft Pro Architecture

The Philosophy: Solving the "Holy Grail" of AI Image Generation

The core mission of CharacterCraft Pro is to solve the most persistent problem in AI image generation: maintaining perfect character identity across different scenes, styles, and contexts. Traditional prompt-based methods often result in frustrating inconsistencies, where a character's appearance drifts with each new generation.

Our solution is an application architecture built upon the principles of a sophisticated, deterministic Prompt Protocol Engine. This engine translates a user's creative intent into a highly structured, machine-readable set of instructions for the Gemini gemini-2.5-flash-image-preview (Nano Banana) model. The goal is to leave nothing to chance, providing the AI with an unambiguous blueprint that prioritizes identity preservation above all else.

Architectural Overview

CharacterCraft Pro Architecture Diagram

Figure 1: High-level architecture of CharacterCraft Pro

The flow of data and logic is designed for precision and control:

  1. User Input: The user provides a reference character image and a creative text prompt.
  2. Prompt Protocol Engine: This is the "brain" of the application. It takes the simple user inputs and forges them into a detailed, multi-part prompt protocol.
  3. Structured API Call: The structured prompt, along with the reference image(s), is sent to the Gemini API.
  4. High-Fidelity Generation: The Gemini model interprets the detailed instructions, generating an image that adheres to the strict consistency constraints.
  5. UI Display: The resulting image is displayed in the gallery for the user to review, download, or refine.
[User Input: Image + Prompt]
           |
           v
[Prompt Protocol Engine]
           |
           v
[Structured Prompt Sent to Gemini API]
  - Contents (Image Parts, Detailed Instructional Prompt)
           |
           v
[Image Generated by Gemini]
           |
           v
[Display in Application UI]

Prompt Architecture: The Core of Consistency

To ensure a responsive and reliable user experience, the application's core logic revolves around its prompt architecture. The key principle is to provide the AI model with an unambiguous, direct command rather than a vague description.

  • Single, Structured Prompt: Instead of separating system-level instructions from user prompts, CharacterCraft Pro combines everything into a single, structured prompt within the contents field. This prompt is dynamically generated based on the user's mode (Creative or Fusion) and inputs.

  • Instructional Phrasing: For example, a creative generation prompt is phrased as a command: Place the character "Captain Eva" from the reference image into a new scene described as: on a mountain summit at sunset.

This method is highly effective because it frames the task as a direct command to an image editing tool, leveraging the specific capabilities of the gemini-2.5-flash-image-preview model. By being explicit, we minimize the chance of the AI misinterpreting the request and drifting from the source character's identity. This approach keeps the API call payload concise and focused on the immediate task, ensuring efficient and reliable generations.

Human-in-the-Loop Refinement

The application implements an iterative feedback loop where the user is the ultimate judge of quality and consistency.

  • The "Verifier" is the User: The gallery allows them to quickly review a batch of images and decide which ones meet their creative vision.
  • The "Refinement Loop" is the "Refine" Button: Clicking the "Refine" button on an image instantly loads its base prompt back into the control panel. This allows the user to make small, targeted adjustments and re-run the generation, creating a manual but highly intuitive and controlled refinement cycle.
  • Intelligent Variations as Exploration: The "Generate x2 / x4" feature, powered by the variationService, acts as a controlled exploration mechanism. Instead of random mutations, it generates a small, diverse batch of prompts based on different artistic dimensions (composition, style, lighting). This allows the user to efficiently explore the creative space around their core idea.

UI/UX Design Philosophy: The Personalized & Expressive Framework

Inspired by modern design systems like Material You, the application's UI is guided by a framework that balances expressive, delightful interactions with user control and accessibility. The goal is to make the creative process not only powerful but also intuitive, personal, and enjoyable.

1. Personalization & Dynamic Theming

The UI is not static; it's a personal creative environment. Through the Settings Panel, users are given direct control over the application's look and feel.

  • Light & Dark Modes: Users can switch between a crisp light theme and a focused dark theme to match their preference or working environment.
  • Accent Colors: A palette of vibrant accent colors allows users to personalize the UI, making it feel uniquely their own.
  • State Persistence: All theme and personalization settings are saved locally, ensuring the user's customized environment is ready for them on their next visit.

2. Expressive Motion & Inclusive Design

Movement brings life to the interface, but it is always purposeful and respectful of user needs.

  • Fluid Micro-Interactions: Physics-based animations on UI elements provide satisfying feedback for taps and state changes, making interactions feel natural and responsive.
  • Accessibility First: We provide a "Reduce Motion" toggle in the settings. This option respects both user choice and system-level prefers-reduced-motion settings, ensuring a comfortable experience for users who are sensitive to motion.

3. Intuitive Gestures & Efficient Workflow

The interface is designed to accelerate the creative process with intuitive shortcuts and a clear layout.

  • Keyboard Shortcuts: Common actions, like generating an image, can be triggered with keyboard shortcuts (Cmd/Ctrl + Enter), empowering power users.
  • Glanceable Information: The layout prioritizes a clear content hierarchy, surfacing important controls and generated content without deep navigation. Loading states and progress are clearly communicated.

4. Consistent & Adaptive Design Language

A robust design system, built on CSS variables, ensures a cohesive and predictable experience across the entire application.

  • Thematic Consistency: Every component, from buttons to modals, is connected to the central theme engine. When a user changes their theme or accent color, the entire UI updates instantly and consistently.
  • Responsive Layouts: The UI is fully responsive, adapting gracefully to different screen sizes and orientations, from mobile to desktop.

5. User Control & Transparency

We believe in empowering users and being transparent about the application's behavior.

  • Centralized Settings: The Settings Panel provides a single, clear location for users to manage their preferences.
  • Clear State Indication: The application provides immediate and clear visual feedback for its state (e.g., loading indicators, progress counters, error messages), so the user always knows what's happening.

This framework creates a "sticky" user experience that is not just a tool, but a delightful and personal creative partner.