Technical Deep-Dive

How I Built FlayshList

A production-grade portfolio with full-stack AI capabilities. Built with modern React patterns, type-safe APIs, and infrastructure that scales.

What This App Demonstrates

Full-stack AI image generation

Production-grade embed handling

Local AI chat, zero API costs

Server-first, minimal client JS

Comprehensive E2E testing

Custom design system

AI Image Generation Toolkit

Flagship Feature

A production-grade AI image generation system demonstrating full-stack capabilities: API design, state management, rate limiting, and multi-service integration.

Multi-Model Support

FLUX Schnell (fast), FLUX Pro (quality), SD3 (creative control)

Aspect Ratios

1:1, 16:9, 9:16, 4:3, 3:4 with auto dimension calculation

Persistent Gallery

Vercel KV storage with 60-image auto-cleanup

Rate Limiting

Two-tier sliding window (5/hr, 20/day) with dev bypass

Recreate Flow

Click any image to regenerate with identical settings

Type-Safe API

Discriminated unions for error handling

Tech Stack

Frontend

Next.js 16 - App Router, Server Components

React 19 - Latest concurrent features

TypeScript 5 - Strict mode, discriminated unions

Tailwind CSS 4 - Custom design system tokens

AI & Infrastructure

Replicate - FLUX + Stable Diffusion 3 models

Vercel Blob - CDN-backed image storage

Vercel KV - Redis-compatible metadata

Upstash Ratelimit - Sliding window rate limiting

Testing & Quality

Playwright - E2E critical path coverage

TypeScript Strict - Compile-time validation

ESLint 9 - Automated code quality

Production

GitHub Actions - 3 parallel CI jobs

Security Headers - CSP, XSS, frame protection

Vercel Analytics - Performance monitoring

Architecture

PresentationReact Server Components

Zero-JS by default, selective hydration

Design SystemTailwind + CSS Variables

Consistent spacing, typography, color scales

API LayerRoute Handlers + Edge

Validation, rate limiting, external API calls

InfrastructureReplicate + Vercel KV/Blob

AI models, persistent storage, CDN delivery

Quality GatesTypeScript + Playwright + CI

Type safety, E2E tests, automated checks

Key Engineering Decisions

Discriminated Union Responses

TypeScript enforces handling success/error cases at compile time

type Response = { success: true; data } | { success: false; error }

Model Capability Flags

Adding new AI models only requires config changes, not code changes

supportsNegativePrompt, supportsGuidanceScale, maxGuidanceScale

Server/Client Boundary

Server fetches initial data for fast first paint, client handles state

page.tsx (server) → client.tsx (state management)

Two-Tier Rate Limiting

Burst protection (hourly) + quota management (daily) for cost control

5 requests/hour, 20 requests/day, localhost bypass

Project Structure

flayshlist/

├── src/
│   ├── app/                      # Next.js App Router
│   │   ├── page.tsx              # Homepage with hero
│   │   ├── ai-toolkit/           # AI Image Generation
│   │   │   ├── page.tsx          # Server (data fetch)
│   │   │   └── client.tsx        # Client (state)
│   │   ├── api/ai/image/         # Generation endpoint
│   │   ├── performance/          # Platform analysis
│   │   ├── music/, reels/, about/, chat/, tools/
│   │   └── layout.tsx, error.tsx, globals.css
│   │
│   ├── components/
│   │   ├── ai-toolkit/           # 1000+ lines
│   │   │   ├── PromptDock.tsx    # Main interface (352 lines)
│   │   │   ├── MasonryGrid.tsx   # Gallery + lazy load
│   │   │   ├── AssetModal.tsx    # Full-screen viewer
│   │   │   └── ModelSelector, AspectRatioSelector...
│   │   ├── ui/                   # Design system
│   │   ├── layout/               # Header, Footer
│   │   └── performance/          # Dashboard components
│   │
│   ├── lib/
│   │   ├── ai-models.ts          # Model configs (109 lines)
│   │   ├── gallery.ts            # KV operations (131 lines)
│   │   ├── ratelimit.ts          # Rate limiting (77 lines)
│   │   └── design-system/
│   │
│   └── types/ai.ts               # Discriminated unions
│
├── docs/AI_TOOLKIT.md            # Technical documentation
├── e2e/smoke.spec.ts             # Playwright tests
└── .github/workflows/ci.yml      # 3 parallel CI jobs

Engineering Signals

Performance

Server Components by default
WebP images, responsive sizes
1-year immutable cache headers
Lazy loading in masonry grid

Quality

TypeScript strict mode
Discriminated union types
E2E critical path tests
Automated CI on every push

Production

Two-tier rate limiting
Security headers configured
Auto-cleanup (60 image limit)
Graceful error handling

CI/CD Pipeline

.github/workflows/ci.yml

Lint→

Type Check→

E2E Tests→

Build

3 parallel jobs: lint+typecheck, e2e, build. Artifacts uploaded for test reports.

Built for Artlist

This project demonstrates production-grade React engineering: ruthless simplicity, type-safe APIs, and infrastructure that scales. I build tools for creators because I am one.