┌─────────────────────────────────────────────────────────────┐
│                        Frontend                              │
│  Next.js App Router + React + Tailwind + shadcn/ui          │
├─────────────────────────────────────────────────────────────┤
│                      API Layer                               │
│  /api/chat  /api/upload  /api/production  /api/stripe       │
├─────────────────────────────────────────────────────────────┤
│                    Service Layer                             │
│  lib/ai/     lib/billing/     lib/image/     lib/shopify    │
├─────────────────────────────────────────────────────────────┤
│                   External Services                          │
│  Supabase    Replicate/fal    Stripe    Shopify    CDN      │
└─────────────────────────────────────────────────────────────┘

garmint/
├── app/                      # Next.js App Router
│   ├── page.tsx              # Main chat studio
│   ├── garments/             # Garment browser
│   ├── gallery/              # Saved generations
│   ├── collections/          # Design collections
│   ├── production/           # Order tracking
│   ├── projects/             # Workspace settings
│   ├── ops/                  # Admin dashboard
│   ├── api/                  # API routes
│   │   ├── chat/             # AI generation endpoint
│   │   ├── upload/           # File upload
│   │   ├── production/       # Order management
│   │   ├── stripe/           # Payment webhooks
│   │   └── auth/             # Supabase auth callback
│   ├── components/           # Shared UI components
│   └── providers.tsx         # State management
├── lib/                      # Core business logic
│   ├── ai/                   # AI generation (Replicate/fal)
│   ├── billing/              # Token & subscription logic
│   ├── image/                # Upload & transformation
│   ├── production/           # Order processing
│   ├── supabase/             # Database clients
│   └── shopify.ts            # Shopify API client
├── hooks/                    # React hooks
├── types/                    # TypeScript definitions
├── supabase/                 # Database schema
│   ├── migrations/           # SQL migrations
│   └── seed.sql              # Initial data
└── docs/                     # This documentation

// middleware.ts - Auth flow
1. Check DEV_AUTH_USERNAME/PASSWORD (optional basic auth for previews)
2. Verify Supabase session via cookies
3. Redirect unauthenticated users to /login
4. Allow public routes: /landing, /login, /api/auth/*

// lib/billing/tokens.ts

// Token costs per operation (user-facing)
const TOKEN_COSTS = {
  "nano-banana": 12,         // Fast generation
  "nano-banana-pro": 45,     // High quality
  "nano-banana-pro-4k": 90,  // Print-ready 4K
  "remove-bg": 3,            // Background removal
  "upscale": 1,              // Image upscaling
};

// Balance check before generation
const balance = await getProjectTokenBalance(projectId);
if (balance < tokensNeeded) {
  return { error: "Insufficient tokens", code: 402 };
}

// Debit after successful generation
await recordUsageLedger(projectId, tokensSpent, jobId);

// lib/ai/mockup.ts - generateUnified()

// Step 1: Generate isolated design
const designPrompt = `Create [design] on white background, 
  centered, ready for print. Square format 1:1.`;
const graphic = await replicate.run(model, { prompt: designPrompt });

// Step 2: Composite onto garment
const mockupPrompt = `Place this design on [garment], 
  professional product photo, design within bounds.`;
const mockup = await replicate.run(model, {
  prompt: mockupPrompt,
  image: graphic,
  image_2: garmentUrl,
});

return { mockups: [mockup], graphicUrl: graphic };

// StudioStateProvider
- collection: Garment[]           // Liked garments
- savedGenerations: Generation[]  // Gallery items
- designCollections: Collection[] // Organized groups
- activeProjectId: string         // Current workspace

// hooks/useProductionRealtime.ts
const channel = supabase
  .channel(`order:${orderId}`)
  .on('postgres_changes', {
    event: 'UPDATE',
    schema: 'public',
    table: 'production_orders',
    filter: `id=eq.${orderId}`,
  }, handleUpdate)
  .subscribe();