Architecture of the Awesome-GPT-Image-2 Project: React, Vite, and Serverless Components Explained

The awesome-gpt-image-2 architecture combines a React frontend built with Vite, serverless Vercel functions for backend logic, and Supabase for authentication and data persistence, integrating with the APIMart service for AI image generation.

The freestylefly/awesome-gpt-image-2 repository implements a modern web application architecture designed for visual prompt discovery and AI image generation. This project demonstrates how to structure a full-stack application using contemporary serverless technologies while maintaining a seamless user experience. Understanding the architecture of the awesome-gpt-image-2 project reveals patterns for building scalable galleries with integrated third-party AI services and reusable agent skills.

Frontend Architecture: React SPA and Vite Build System

The client-side of the awesome-gpt-image-2 project is a responsive single-page application (SPA) built with React and bundled by Vite.

Component Structure and Entry Points

In src/main.jsx, the root React component assembles the UI, routing, and global hooks necessary for the gallery interface. The community features reside in src/community.jsx, providing interfaces for browsing cases and managing user-generated content. These JSX components consume static data from the data/ directory—specifically data/cases.json for the master list of 544 prompt cases—and fetch dynamic content from the serverless backend.

Build Configuration and Local Development

The vite.config.js file defines the build output directory (dist) and integrates a custom plugin located at scripts/vite-local-api.mjs. This plugin forwards API calls to the Vercel serverless environment during local development, ensuring the frontend can communicate with backend functions seamlessly before deployment.

Backend Architecture: Serverless Vercel Functions

The backend logic runs as serverless functions deployed on Vercel, eliminating the need for traditional server management.

API Endpoints Structure

All backend endpoints reside in the api/ folder, following Vercel's convention for serverless functions:

• api/generate-image.js: Handles image generation requests, manages platform credit deductions, and proxies to APIMart
• api/me.js: Returns current user profiles including credit balances, membership status, and admin privileges
• api/favorites.js: Manages user favorites and saved prompts

These functions read environment variables defined in vercel.json, including SUPABASE_SERVICE_ROLE_KEY for database access and APIMART_API_KEY for the image generation service.

Serverless Handler Implementation

In api/generate-image.js, the serverless function validates user sessions via Supabase before processing generation requests:

import { supabase } from '../../src/supabaseClient.js';
import { submitPlatformGeneration } from '../../src/apimartClient.js';

export default async function handler(req, res) {
  const { prompt } = JSON.parse(req.body);
  const { data: session } = await supabase.auth.api.getUserByCookie(req, res);
  if (!session) return res.status(401).json({ error: 'AUTH_REQUIRED' });
  const result = await submitPlatformGeneration(prompt, session.id);
  res.status(200).json(result);
}

Data Layer: Supabase and Static Assets

The architecture separates dynamic user data from static content, using Supabase for persistence and the filesystem for immutable assets.

Authentication and Session Management

The src/supabaseClient.js file initializes the Supabase client using environment-specific variables:

import { createClient } from '@supabase/supabase-js';

export const supabase = createClient(
  import.meta.env.VITE_SUPABASE_URL,
  import.meta.env.VITE_SUPABASE_ANON_KEY
);
export const isSupabaseConfigured = Boolean(
  import.meta.env.VITE_SUPABASE_URL && import.meta.env.VITE_SUPABASE_ANON_KEY
);

The frontend stores session tokens in local storage, enabling persistent authentication across page reloads. User metadata and credit balances are managed through Supabase RPCs defined in supabase/migrations/ SQL scripts.

Static Data and Media Storage

The data/ folder serves as a public directory containing:

• data/cases.json: The canonical list of all 544 prompt cases populating the gallery
• data/style-library.json: Centralized catalogue of categories, styles, and scenes
• data/images/: Case images and category covers served as static assets

Vite's configuration marks this folder as publicDir, ensuring these assets are served directly without build-time processing.

Image Generation Flow: APIMart Integration

The project implements a dual-path generation system supporting both personal API keys and platform-managed credits.

Client-Side Generation Logic

In src/apimartClient.js, the application encapsulates all APIMart communication. For users with personal API keys, requests route directly to APIMart:

export async function submitPersonalGeneration(prompt, key) {
  const resp = await fetch('https://api.apimart.ai/v1/tasks', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${key}`,
    },
    body: JSON.stringify({ prompt, model: 'stable-diffusion', steps: 30 })
  });
  if (!resp.ok) throw new Error('APIMART_REQUEST_REJECTED');
  return await resp.json(); // contains task_id
}

The client polls the APIMart task endpoint until the image URL becomes available, then displays the result alongside the original case.

Shared Constants and Error Handling

The shared/apimart.js file contains price snapshots, error code definitions, and API constants used by both frontend and backend. This shared module ensures consistency in billing logic and error handling across the application stack.

Agent Skill Architecture: Reusable Style Library

A unique component of the awesome-gpt-image-2 architecture is its exportable agent skill, allowing external AI agents to utilize the same style definitions as the web interface.

Skill Package Structure

Located in agents/skills/gpt-image-2-style-library/, this module is published to npm as gpt-image-2-style-library. The skill sources its data from the same data/style-library.json file used by the React frontend, ensuring synchronization between the website and external agents like Claude Code or Codex.

Developers can install the skill using:

npx skills add freestylefly/awesome-gpt-image-2 --skill gpt-image-2-style-library --agent claude-code

This architectural pattern demonstrates how to build isomorphic data layers where a single JSON source drives both web UI components and external tool integrations.

Summary

• The frontend uses React with Vite (src/main.jsx, src/community.jsx) to deliver a responsive SPA, with vite.config.js handling build logic and API proxying via scripts/vite-local-api.mjs
• Vercel serverless functions in the api/ folder (api/generate-image.js, api/me.js) handle backend logic without dedicated servers
• Supabase (src/supabaseClient.js) provides authentication, session management, and credit tracking via environment variables VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY
• APIMart integration (src/apimartClient.js, shared/apimart.js) manages image generation through both personal API keys and platform credits deducted via Supabase RPCs
• Static assets reside in the data/ folder, including data/cases.json for gallery content and data/style-library.json shared with the agent skill
• The agent skill architecture (agents/skills/gpt-image-2-style-library/) packages style definitions for external AI tools, maintaining consistency with the web interface

Frequently Asked Questions

What frontend technologies power the awesome-gpt-image-2 interface?

The project uses React for UI components and Vite as the build tool. The entry point resides in src/main.jsx, with community features in src/community.jsx. Vite's configuration in vite.config.js enables rapid development and optimizes production bundles, while the scripts/vite-local-api.mjs plugin simulates the serverless environment locally.

How does the image generation architecture handle billing?

The architecture implements a dual-path system. When users possess personal APIMart keys, src/apimartClient.js sends requests directly to the APIMart API. Otherwise, requests route to api/generate-image.js, which validates the session via Supabase and deducts platform credits stored in the Supabase database using RPC calls defined in supabase/migrations/.

What is the role of the style library in the project architecture?

The data/style-library.json file serves as the canonical source for categories, styles, and scenes. This JSON drives the React gallery interface and is consumed by the gpt-image-2-style-library npm package located in agents/skills/gpt-image-2-style-library/. This shared data layer ensures that external AI agents and the web application remain synchronized.

How is user authentication implemented across the stack?

Authentication relies on Supabase, initialized in src/supabaseClient.js using VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY environment variables. The frontend manages sessions in local storage, while serverless functions in the api/ folder verify cookies using the Supabase service role key to protect private endpoints and user data.

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