Home

Relevant source files

The following files were used as context for generating this wiki page:

• App.tsx
• services/hfService.ts
• README.md
• types.ts
• components/HistoryGallery.tsx
• components/SettingsModal.tsx
• components/ImageComparison.tsx
• index.html
• translations.ts

The Home view is the primary user interface for the AI Image Gen application, also known as Peinture. It is a single-page application (SPA) built with React that provides a comprehensive suite of tools for generating, managing, and enhancing AI-created images. The entire user experience, from prompt input to image viewing and history management, is encapsulated within the App.tsx component and its children. The application is designed to be privacy-focused, storing all user-generated content and settings in the browser's localStorage.

This page details the architecture, core features, data flows, and configuration of the Home view. It leverages multiple external Hugging Face and Pollinations.ai services to deliver its functionality.

Sources: README.md:3-8, App.tsx, index.html

System Architecture

The application's front-end architecture is centered around the main App.tsx component, which orchestrates state management and data flow between various child components and external services. It's a classic React component hierarchy where App.tsx holds the primary state for user inputs, generated images, and application status.

Sources: App.tsx, index.tsx:4-14

Component Structure

The diagram below illustrates the high-level component architecture. App.tsx serves as the container for UI controls, the image preview area, and the history gallery, delegating specific functionalities to specialized components.

This diagram shows that App.tsx is the central hub, interacting with both UI components and the hfService module, which in turn communicates with external APIs.

Sources: App.tsx, components/HistoryGallery.tsx, components/SettingsModal.tsx, services/hfService.ts

State Management

All primary application state is managed within App.tsx using React's useState and useEffect hooks. There is no external state management library.

Key state variables include:

• prompt, model, aspectRatio, seed: User inputs for generation.
• isLoading, isOptimizing, isUpscaling: Status flags for asynchronous operations.
• currentImage: The currently selected or newly generated image object.
• history: An array of GeneratedImage objects, persisted to localStorage.
• error: Stores error messages from API calls.
• lang: The current UI language ('en' or 'zh').

Sources: App.tsx:47-120

Core Features

The application provides several key features accessible from the main interface.

Image Generation

Users can generate images by providing a text prompt and selecting various parameters. The generation process is handled by the handleGenerate function, which calls the generateImage service.

The image generation flow is as follows:

1. User fills the prompt and selects a model and aspect ratio.
2. User clicks the "Generate" button, triggering handleGenerate.
3. App.tsx sets isLoading to true and calls generateImage in hfService.ts.
4. hfService.ts dispatches the request to the appropriate Hugging Face API based on the selected model.
5. The service uses a two-step process: first, it queues the job and gets an event_id, then it polls the result endpoint.
6. The final Server-Sent Event (SSE) stream is parsed by extractCompleteEventData to get the image URL.
7. The new GeneratedImage object is added to the history state and set as the currentImage.

Sources: App.tsx:183-205, services/hfService.ts:114-180

The following sequence diagram illustrates the image generation process.

Supported Models

The application supports two distinct image generation models.

Model Name	Value	API Endpoint
Z-Image Turbo	z-image-turbo	https://luca115-z-image-turbo.hf.space
Qwen Image Fast	qwen-image-fast	https://mcp-tools-qwen-image-fast.hf.space

The Z-Image Turbo model also supports an "HD" option which generates images at a higher resolution.

Sources: App.tsx:41-44, services/hfService.ts:3-5, services/hfService.ts:9-46

Prompt Optimization

An integrated AI prompt enhancer can expand simple ideas into detailed descriptions. This is triggered by the handleOptimizePrompt function, which calls the optimizePrompt service. This service sends the user's prompt to the Pollinations.ai API, which uses an OpenAI model to rewrite it.

4x Resolution Upscaling

Generated images can be upscaled to 4x their original resolution using the RealESRGAN_x4plus model. This feature is handled by the upscaler function in hfService.ts.

The user flow for upscaling is a two-step process to allow for comparison:

1. User clicks the "Upscale" button on a selected image.
2. handleUpscale is called, which invokes the upscaler service.
3. The service calls the upscaler API (https://tuan2308-upscaler.hf.space).
4. Upon receiving the upscaled image URL, the app enters a "comparison mode" by setting isComparing to true and displaying the ImageComparison component.
5. The user can then visually compare the original and upscaled images and choose to "Keep Changes" (handleApplyUpscale) or "Discard" (handleCancelUpscale).

Sources: README.md:16-17, App.tsx:220-258, services/hfService.ts:182-213, components/ImageComparison.tsx

History Management

All generated images are automatically saved to the browser's localStorage under the key ai_image_gen_history.

• Persistence: The history state is written to localStorage whenever it changes.
• Expiration: On application load, the history is filtered to remove any images older than one day (24 hours).
• Display: The HistoryGallery component renders a scrollable thumbnail strip of the images in the history.
• Interaction: Users can select an image from the gallery to view it, delete it, download it, or toggle a blur effect (for NSFW content).

Sources: App.tsx:101-115, App.tsx:135-137, components/HistoryGallery.tsx

Data Model

The core data structure for a generated image is defined by the GeneratedImage interface.

Field	Type	Description
id	string	A unique identifier for the image, generated via crypto.randomUUID().
url	string	The URL of the generated image file.
prompt	string	The text prompt used to generate the image.
aspectRatio	string	The aspect ratio of the image (e.g., "1:1", "16:9").
timestamp	number	The Unix timestamp (in milliseconds) when the image was created.
model	string	The model used for generation (e.g., "z-image-turbo").
seed	number (optional)	The seed value used for generation.
duration	number (optional)	The time taken to generate the image, in seconds.
isBlurred	boolean (optional)	Flag to toggle a blur effect on the image.
isUpscaled	boolean (optional)	Flag indicating if the image has been successfully upscaled.

Sources: types.ts:3-14

Configuration and Settings

Application settings can be configured via the SettingsModal component. All settings are persisted in localStorage.

Setting	localStorage Key	Description
Language	app_language	Sets the UI language. Supported values are 'en' and 'zh'.
Hugging Face Token	huggingFaceToken	An optional user-provided token to authenticate with Hugging Face APIs for higher rate limits.

The Hugging Face token is retrieved from localStorage and added as a Bearer token in the Authorization header for all requests to Hugging Face Spaces.

Sources: components/SettingsModal.tsx, App.tsx:47-53, 131-133, services/hfService.ts:68-77, translations.ts

Conclusion

The Home view of the Peinture application is a robust and feature-rich interface that serves as the complete user-facing portion of the project. It effectively orchestrates complex asynchronous operations with multiple external AI services while maintaining a responsive user experience. Its architecture, centered on the App.tsx component, demonstrates a clean separation of concerns between state management, service calls, and UI representation, making it a well-structured and capable SPA for AI image generation.

Sources: README.md, App.tsx