GPT-Image2 Repository Architecture: Full-Stack React, Vercel, and Supabase Breakdown

The GPT-Image2 repository is a full‑stack web application that combines a React/Vite front‑end, Vercel serverless API routes, Supabase for authentication and data storage, and an external CIYUAN service for AI image generation.

The freestylefly/awesome-gpt-image-2 project demonstrates a modern Jamstack architecture that cleanly separates UI rendering from business logic and external service integration. This guide explores how each layer interacts to provide a seamless image generation experience with credit-based billing and agent extensibility.

Frontend Layer: React and Vite

The user interface is a single‑page React application bundled with Vite. The entry point src/main.jsx initializes the component tree, manages language internationalization, and handles authentication state for the gallery and generation dialogs.

Key frontend components include:

• src/main.jsx — Primary UI entry point that renders the gallery and handles language switching
• src/community.jsx — Community page displaying shared generations
• src/styles.css — Global CSS styles and responsive design tokens

The frontend communicates with backend services via standard HTTP fetch requests to /api/* endpoints. This restful approach ensures the React layer remains purely presentational while delegating all business logic to serverless functions.

Backend Layer: Vercel Serverless API Routes

The API layer runs on Vercel serverless functions located in the api/ directory. These files expose REST‑style endpoints that manage image generation, user profiles, favorites, and billing workflows.

Critical endpoints include:

• api/generate-image.js — Core generation endpoint handling credit reservations and CIYUAN integration
• api/me.js — Returns the authenticated user's profile and current credit balance
• api/billing/*.js — Stripe and Alipay checkout handlers, webhook processing, and credit pack management

Each endpoint validates the Supabase session before executing protected operations. This pattern ensures that credit deductions and generation requests occur only for authenticated, authorized users.

Data and Authentication: Supabase Integration

Supabase provides the authentication, database, and storage infrastructure. The file src/supabaseClient.js instantiates a singleton client used throughout both the browser and server‑side code.

The authentication flow follows this sequence:

1. The client initializes using VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY environment variables
2. API routes extract the JWT from request headers via getAuthContext
3. Serverless functions query the profiles table to verify membership status and available credits

This centralized architecture guarantees consistent session state across the React SPA and stateless API functions.

Image Generation Flow: CIYUAN Integration

The system implements a reservation pattern to handle credit accounting reliably. When a user requests image generation, the API reserves a credit before calling the external CIYUAN service, then commits or rolls back the transaction based on success or failure.

The reservation logic in api/generate-image.js differentiates between administrative and standard users:

// Reservation pathway selection based on user role
if (auth.profile.isSuperAdmin) {
  reservation = await reserveCreditGeneration(auth.client, auth.user.id, caseId, prompt);
} else {
  reservation = await reserveGeneration(auth.client, auth.user.id, caseId, prompt);
}

The reserveGeneration and reserveCreditGeneration functions manage atomic database transactions to prevent race conditions during concurrent generation requests. Upon successful CIYUAN response, the endpoint returns a base‑64 data URL ready for immediate rendering in the browser.

Agent Skills and Style Library

The repository maintains a sophisticated agent skill system that packages the website's styling definitions as an installable NPM module. The canonical source data/style-library.json contains categories, templates, tags, and scene definitions synchronized across the UI and external AI agents.

The skill generation pipeline works as follows:

1. scripts/generate-style-skill.mjs parses data/style-library.json
2. The script generates the agents/skills/gpt-image-2-style-library/ directory with CLI tooling
3. Users can install the skill globally and query templates via commands like gpt-image-2-style-library get-template --id tpl-ui

This architecture ensures that AI agents like Claude Code and Codex access identical style definitions as the web interface, maintaining consistency across manual and automated workflows.

Configuration and Environment

All sensitive credentials use Vercel environment variables injected at runtime. The frontend receives only variables prefixed with VITE_, while serverless functions access the full environment.

Required configuration includes:

• VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY — Public Supabase endpoints
• CIYUAN_API_KEY — Private API key for image generation services
• STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET — Payment processing credentials

The vite.config.js manages build optimization and development server settings, while package.json defines scripts for development (npm run dev), production builds, and the skill generation workflow.

Summary

• GPT-Image2 implements a decoupled architecture with React/Vite frontend and Vercel serverless API routes
• Supabase handles authentication, session management, and credit tracking across the entire stack
• The reservation pattern in api/generate-image.js ensures reliable credit accounting before calling external CIYUAN services
• A JSON-driven style library (data/style-library.json) powers both the web UI and a generated NPM agent skill
• Environment-based secrets management keeps payment and API keys secure while supporting flexible deployment pipelines

Frequently Asked Questions

How does GPT-Image2 handle user authentication across the stack?

GPT-Image2 uses Supabase Auth with JWT tokens managed through src/supabaseClient.js. The React frontend initializes the client and manages the user session, while API routes like api/me.js and api/generate-image.js validate incoming JWTs using the same client configuration. This shared approach ensures consistent authentication state between the browser and serverless functions.

What prevents users from losing credits during failed image generations?

The system implements a reservation pattern in api/generate-image.js that calls either reserveGeneration or reserveCreditGeneration before contacting the CIYUAN service. If the external API returns an error or times out, the reservation is released and the credit returns to the user's account. Only successful generations finalize the reservation and permanently deduct the credit.

How does the style library stay synchronized between the website and AI agents?

The repository uses data/style-library.json as the single source of truth for all style templates, categories, and scenes. The scripts/generate-style-skill.mjs utility reads this JSON file and generates the agents/skills/gpt-image-2-style-library/ NPM package. This build‑time generation ensures that any updates to the style library automatically propagate to both the React UI and CLI tooling used by AI agents.

Where are the billing and payment endpoints defined?

Payment processing endpoints reside in the api/billing/ directory, implementing Stripe and Alipay integrations. These serverless functions handle checkout session creation, webhook verification using STRIPE_WEBHOOK_SECRET, and credit pack allocation upon successful payment. The frontend initiates these flows by POSTing to /api/billing/checkout or similar routes defined within this directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}