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

> Explore the GPT-Image2 repository architecture. Learn about the full-stack React, Vercel, and Supabase setup for AI image generation and data management. Get a clear breakdown.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: architecture
- Published: 2026-08-26

---

**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](https://github.com/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx) — Primary UI entry point that renders the gallery and handles language switching
- [`src/community.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/community.jsx) — Community page displaying shared generations
- [`src/styles.css`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) — Core generation endpoint handling credit reservations and CIYUAN integration
- [`api/me.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) differentiates between administrative and standard users:

```javascript
// 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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/vite.config.js) manages build optimization and development server settings, while [`package.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) ensures reliable credit accounting before calling external CIYUAN services
- A **JSON-driven style library** ([`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/supabaseClient.js). The React frontend initializes the client and manages the user session, while API routes like [`api/me.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/me.js) and [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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.