Development Spec

Implementation Details

Project structure, file organization, key code patterns, and development workflow for the SIX.

Project Structure

src/
├── app/                          # Next.js App Router
│   ├── api/
│   │   ├── generate-layout/      # AI layout generation endpoint
│   │   │   └── route.ts
│   │   └── inventory/            # Product inventory endpoint
│   │       └── route.ts
│   ├── docs/                     # Documentation pages
│   │   ├── executive-summary/
│   │   ├── functional-overview/
│   │   ├── technical-architecture/
│   │   └── development-spec/
│   ├── shop/                     # Main shopping experience
│   │   └── page.tsx
│   ├── layout.tsx                # Root layout
│   └── page.tsx                  # Landing page
│
├── components/
│   ├── docs/
│   │   └── DocsLayout.tsx        # Documentation sidebar layout
│   ├── layouts/
│   │   ├── GridLayout.tsx        # Dense product grid (Goal-Oriented)
│   │   ├── HeroLayout.tsx        # Hero section (Browsing)
│   │   └── MagazineLayout.tsx    # Editorial sections (Browsing)
│   ├── primitives/
│   │   ├── Badge.tsx             # Status/tag badges
│   │   ├── Button.tsx            # Action buttons
│   │   └── OptimizedImage.tsx    # Next.js Image wrapper
│   ├── products/
│   │   ├── EditorialCard.tsx     # Storytelling product card
│   │   ├── ProductCard.tsx       # Default product card
│   │   └── QuickBuyCard.tsx      # Transactional card (Goal-Oriented)
│   ├── ui/
│   │   ├── ContextBanner.tsx     # Urgency/info banners
│   │   ├── LoadingState.tsx      # Skeleton loading states
│   │   └── PersonaToggle.tsx     # Goal-Oriented/Browsing selector
│   └── LayoutRenderer.tsx        # Maps schema to components
│
├── data/
│   ├── inventory.json            # 34 products with metadata
│   └── knowledge-graph.json      # Persona & context definitions
│
├── lib/
│   ├── ai/
│   │   ├── generate-layout.ts    # Main generation orchestration
│   │   ├── prompts.ts            # System & user prompts
│   │   ├── schemas.ts            # Zod schemas for layout
│   │   └── validate.ts           # Hallucination prevention
│   ├── inventory/
│   │   ├── filter.ts             # Context-aware filtering
│   │   ├── loader.ts             # JSON loader with caching
│   │   └── schemas.ts            # Product type definitions
│   └── utils.ts                  # cn() utility for Tailwind
│
└── types/
    └── index.ts                  # Shared TypeScript types

Key Files Explained

lib/ai/generate-layout.ts

Core

The orchestration layer that ties everything together. Handles inventory loading, prompt building, AI generation, validation, retries, and fallbacks.

Key functions:

generateLayout(persona, context) - Main entry point
getFallbackLayout(persona, products) - Deterministic fallback

lib/ai/schemas.ts

Types

Zod schemas that define the layout structure. Used by both AI generation (schema enforcement) and TypeScript (type inference).

Exported schemas:

LayoutResponseSchema - Full response structure
ComponentSchema - Discriminated union of component types
HeroComponentSchema, GridComponentSchema, etc.

lib/ai/validate.ts

Safety

Post-generation validation that catches hallucinated product IDs. Provides both strict validation (throws) and lenient sanitization (removes invalid).

Key exports:

HallucinationError - Custom error with invalid IDs
validateLayout(layout, products) - Strict validation
sanitizeLayout(layout, products) - Remove invalid IDs

components/LayoutRenderer.tsx

Maps AI-generated layout schema to React components. Uses discriminated union pattern for type-safe component rendering.

Pattern:

switch (component.type) {
  case 'hero': return <HeroLayout {...component} />
  case 'grid': return <GridLayout {...component} />
  case 'magazine': return <MagazineLayout {...component} />
  case 'banner': return <ContextBanner {...component} />
}

Data Models

Product (inventory.json)

{
  "id": "wj-001",
  "name": "All-Weather Shell Jacket",
  "price": 189,
  "stock": 24,
  "category": "outerwear",
  "tags": ["waterproof", "windproof", "outdoor", "rain"],
  "badges": ["new-arrival"],
  "imageUrl": "https://images.unsplash.com/...",
  "personaFit": {
    "goal-oriented": 0.9,    // High transactional appeal
    "browsing": 0.4   // Lower discovery appeal
  }
}

LayoutResponse (AI output)

{
  "metadata": {
    "persona": "goal-oriented",
    "reasoning": "Dense grid with weather-appropriate products...",
    "contextApplied": ["rain", "high-urgency"]
  },
  "components": [
    {
      "type": "banner",
      "variant": "urgency",
      "message": "Rain gear ships same-day",
      "icon": "cloud-rain"
    },
    {
      "type": "grid",
      "columns": "4",
      "productIds": ["wj-001", "rb-001", "ub-001", ...],
      "cardVariant": "quick-buy",
      "showFilters": true
    }
  ]
}

API Reference

POST/api/generate-layout

Generate a personalized layout based on persona and context.

REQUEST BODY

{
  "persona": "goal-oriented" | "browsing",
  "context": {
    "weather": "sunny" | "cloudy" | "rain" | "snow",
    "timeOfDay": "morning" | "afternoon" | "evening" | "night",
    "urgency": "low" | "medium" | "high",
    "location": string
  }
}

RESPONSE

{
  "metadata": { persona, reasoning, contextApplied },
  "components": [...]
}

Headers:
  X-Generation-Time: "1234ms"

GET/api/inventory

Retrieve all products. Used by LayoutRenderer to resolve product IDs.

RESPONSE

{
  "products": [...],
  "count": 34
}

Development Workflow

Setup

# Clone and install
git clone <repo>
cd six
npm install

# Configure environment
cp .env.example .env.local
# Add your OPENAI_API_KEY

# Run development server
npm run dev

Key Commands

npm run dev	Start development server (localhost:3000)
npm run build	Production build
npm run lint	ESLint check

Environment Variables

Variable	Required	Description
OPENAI_API_KEY	Yes	OpenAI API key for GPT-4o
LANGFUSE_PUBLIC_KEY	No	Langfuse observability (optional)
LANGFUSE_SECRET_KEY	No	Langfuse observability (optional)
POSTHOG_KEY	No	PostHog analytics (optional)

Future Enhancements

Performance

• Streaming generation with partial rendering
• Layout caching (persona + context hash)
• GPT-4o-mini for Goal-Oriented (faster, cheaper)

Features

• Real-time inventory from Supabase
• User preference learning
• A/B testing framework

Observability

• Langfuse tracing for AI calls
• PostHog for user analytics
• Error tracking (Sentry)

Scale

• Edge deployment (Vercel Edge)
• CDN caching for static assets
• Rate limiting per user

Continue Reading

Technical Architecture

System design and AI pipeline

Start Over

Executive Summary

Business context and value proposition

Ready to Experience It?

Try the Demo

Experience the Goal-Oriented and Browsing layouts in action