Architecture Overview

Relevant source files

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

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

This document provides a technical overview of the Peinture AI Image Generator application. The application is a client-side, single-page application (SPA) built with React and TypeScript. It functions without a dedicated backend, instead orchestrating calls to various external Hugging Face and Pollinations.ai APIs for its core functionality. User data, such as image generation history and settings, is persisted locally in the browser's localStorage, ensuring user privacy.

The architecture is centered around the main App.tsx component, which manages application state, user interactions, and the data flow between UI components and external services. The overall design prioritizes a reactive user interface, modular components, and direct integration with third-party AI model endpoints.

Sources: README.md, App.tsx

Component Architecture

The application's UI is built from a set of modular React components. The App component serves as the root, orchestrating state and logic for all child components.

This diagram illustrates the primary component hierarchy and their relationships.

Key Components

Component	Description	Source File
App	The main application component. Manages all state, handles user input, and orchestrates API calls.	App.tsx
HistoryGallery	Displays a horizontally scrollable gallery of previously generated images. Allows users to select an image to view.	components/HistoryGallery.tsx
SettingsModal	A modal dialog for application settings, including language selection and entering an optional Hugging Face API token.	components/SettingsModal.tsx
ImageComparison	A component that provides a slider to compare an original image with its upscaled version.	components/ImageComparison.tsx
CustomSelect	A reusable dropdown component used for selecting the AI model and aspect ratio.	components/CustomSelect.tsx
hfService	Not a component, but a service module containing all logic for interacting with external APIs (Hugging Face, Pollinations.ai).	services/hfService.ts

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

State Management

The application employs a client-side state management strategy using React hooks, primarily within the App.tsx component. There is no global state management library like Redux; instead, state is centralized in the App component and passed down to child components as props.

Key state variables include:

• prompt: The user-entered text prompt.
• model: The selected AI model (z-image-turbo or qwen-image-fast).
• history: An array of GeneratedImage objects, representing all generated images.
• currentImage: The GeneratedImage object currently displayed in the main preview area.
• isLoading, isOptimizing, isUpscaling: Boolean flags to track the status of asynchronous operations and provide feedback to the user.
• error: A string to hold any error messages from API calls.

State changes trigger re-renders, and useEffect hooks are used to persist state to localStorage and to manage side effects like timers.

Sources: App.tsx:49-92

Data Persistence

User data is stored exclusively in the browser's localStorage. This includes generated image history, application language, and the optional Hugging Face token. This approach makes the application serverless from a user data perspective.

• Image History: Stored under the key ai_image_gen_history. On initialization, the application loads this history and filters out any entries older than one day.
• Language Preference: Stored under app_language.
• Hugging Face Token: Stored under huggingFaceToken.

Sources: App.tsx:95-108, App.tsx:120-122, components/SettingsModal.tsx:21-25

LocalStorage Data Model

The primary data object stored is GeneratedImage. The following diagram shows its structure.

External Services Integration

All interactions with external AI models are handled by the hfService.ts module. The application communicates with three main types of services, all hosted on Hugging Face Spaces or Pollinations.ai.

API Endpoints

Service	Base URL	Purpose
Z-Image Turbo	https://luca115-z-image-turbo.hf.space	Image Generation
Qwen Image Fast	https://mcp-tools-qwen-image-fast.hf.space	Image Generation
Upscaler	https://tuan2308-upscaler.hf.space	4x Image Resolution Upscaling
Prompt Optimizer	https://text.pollinations.ai/openai	Prompt Enhancement

Sources: services/hfService.ts:3-6

Image Generation Flow

Image generation uses a two-step process common for Hugging Face Gradio APIs. First, a request is sent to queue a job, which returns an event_id. Second, a request is made to a streaming endpoint using that event_id to receive the result.

The following sequence diagram shows the flow when a user clicks "Generate".

Prompt Optimization Flow

Prompt optimization uses a single API call to Pollinations.ai, which acts as a proxy to an OpenAI model.

Image Upscaling Flow

The upscaling flow is similar to image generation, using the same two-step Gradio API pattern but targeting the upscaler service.

Summary

The Peinture application architecture is a modern, client-centric design that leverages the power of external AI services. Its key characteristics are:

• A serverless architecture for user data, enhancing privacy.
• Centralized state management within a single root React component.
• Modular and reusable UI components.
• A dedicated service layer (hfService.ts) that encapsulates all third-party API communication, cleanly separating concerns.
• Reliance on browser localStorage for simple and effective data persistence.

This structure makes the application lightweight, easy to deploy on static hosting platforms, and maintainable by keeping UI logic, state management, and external service communication in distinct, well-defined parts of the codebase.

Sources: README.md, App.tsx, services/hfService.ts