Architecting a Text-to-Image Inference Platform

PixelMuse is a modern, type-safe text-to-image generation platform built with Next.js 14, Clerk Auth, and the Replicate API. Here's how I am designing and developing the architecture to create a seamless user experience with beautiful UI and a comprehensive + realiable AI image generation service.

Artist Gallery Pages

Generating 3d Objects .GBL files

Generated on PixelMuse using the Trelis AI model.

Technical Implementation Details

Application Architecture

Here's a high-level overview of how the different components interact:

TypeSafe API for Image Generation

The integration with Replicate's API is handled through a type-safe client, generated from their OpenAPI specification:

/account
/collections
/collections/{collection_slug}
/deployments
/deployments/{deployment_owner}/{deployment_name}
/deployments/{deployment_owner}/{deployment_name}/predictions
/hardware
/models
/models/{model_owner}/{model_name}
/models/{model_owner}/{model_name}/predictions
/models/{model_owner}/{model_name}/versions
/models/{model_owner}/{model_name}/versions/{version_id}
/models/{model_owner}/{model_name}/versions/{version_id}/trainings
/predictions
/predictions/{prediction_id}
/predictions/{prediction_id}/cancel
/trainings
/trainings/{training_id}
/trainings/{training_id}/cancel
/webhooks/default/secret

Project Structure

The application follows a clean, modular structure:

src/
├── app/
│   ├── page.tsx                    # Home/generation page
│   ├── layout.tsx                  # Root layout
│   ├── pricing/
│   │   └── page.tsx               # Pricing page
│   └── api/
│       ├── auth/
│       │   └── webhook/route.ts   # Clerk webhook handler
│       ├── credits/
│       │   ├── check/route.ts     # Check credit balance
│       │   ├── consume/route.ts   # Consume credits
│       │   └── refresh/route.ts   # Refresh daily credits
│       ├── generate/
│       │   └── [model]/route.ts   # Image generation endpoints
│       └── payments/
│           └── webhook/route.ts   # Stripe webhook handler
├── components/
│   ├── ui/                        # shadcn/ui components
│   ├── layout/
│   │   ├── header.tsx            # Main nav with credits/auth
│   │   └── footer.tsx            # Site footer
│   ├── auth/
│   │   ├── auth-button.tsx       # Sign in/out button
│   │   └── user-profile.tsx      # User profile dropdown
│   ├── credits/
│   │   ├── credit-display.tsx    # Credit balance + buy button
│   │   └── credit-history.tsx    # Transaction history
│   ├── generation/
│   │   ├── prompt-form.tsx       # Text input + generate button
│   │   ├── model-select.tsx      # Model dropdown with Pro tags
│   │   └── result-display.tsx    # Generated image display
│   └── pricing/
│       ├── package-card.tsx      # Credit package display
│       └── pricing-grid.tsx      # Grid of packages
├── lib/
│   ├── db/
│   │   ├── schema.ts             # Drizzle schema
│   │   └── index.ts              # Database utilities
│   ├── replicate/
│   │   ├── client.ts             # Replicate API client
│   │   ├── models.ts             # Model configurations
│   │   └── types.ts              # Replicate API types
│   ├── auth/
│   │   └── clerk-utils.ts        # Clerk helpers
│   └── utils/
│       ├── error-handling.ts     # Error utilities
│       └── toast.ts              # Toast notifications
├── config/
│   ├── site.ts                   # Site configuration
│   ├── credits.ts                # Credit system config
│   └── models.ts                 # AI model config
└── styles/
    └── globals.css               # Global styles

The Foundation: Next.js 14 and TypeScript

I chose Next.js 14 as the foundation for PixelMuse, leveraging its powerful features like React Server Components (RSC) and server actions. The entire application is built with TypeScript, ensuring type safety from the database schema to the API endpoints.

Key architectural decisions included:

• Using pnpm for faster, more efficient package management
• Implementing a monorepo structure for better code organization
• Leveraging server components by default for optimal performance
• Strict TypeScript configuration throughout the codebase

Authentication and User Management

For user authentication, I integrated Clerk, which provides a robust, type-safe authentication system. We Sync User data from Clerk to our supabase via Drizzle and a webhook when a user signs up.

Database and Type Safety

The database layer is built on Supabase with Drizzle ORM, providing:

• Type-safe database queries and schema management
• Real-time credit balance updates
• Efficient user data synchronization

Credit System Implementation

One of the core features is the credit system. Users can purchase credits in packages, and the system automatically deducts credits from their balance when an image is generated. I used Drizzle, Clerk, and Stripe to implement this.

Looking Forward

Building PixelMuse has been an exciting journey in creating a type-safe, modern web application. The architecture decisions I made have resulted in a robust platform that's easy to maintain and extend.

Some key learnings:

• The importance of proper type definitions throughout the stack
• Value of proper error handling and user feedback

The platform continues to evolve, and I'm excited to add more features while maintaining the high standards of type safety and user experience that have been established.