Development Spec

Implementation Details

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

V1 Project Structure

src/
├── app/                          # Next.js App Router
│   ├── api/
│   │   ├── generate-layout/      # V1 AI layout generation endpoint
│   │   │   └── route.ts
│   │   └── inventory/            # Product inventory endpoint (shared)
│   │       └── route.ts
│   ├── docs/
│   │   └── v1/                   # V1 Documentation
│   │       ├── executive-summary/
│   │       ├── functional-overview/
│   │       ├── technical-architecture/
│   │       └── development-spec/
│   ├── shop/
│   │   └── v1/
│   │       └── page.tsx          # V1 Shopping experience
│   ├── layout.tsx                # Root layout
│   └── page.tsx                  # Landing page
│
├── components/
│   ├── docs/
│   │   ├── DocsLayout.tsx        # V2 Documentation layout
│   │   └── V1DocsLayout.tsx      # V1 Documentation layout
│   ├── layouts/                  # Shared layout components
│   │   ├── GridLayout.tsx        # Dense product grid (Hunter)
│   │   ├── HeroLayout.tsx        # Hero section (Gatherer)
│   │   └── MagazineLayout.tsx    # Editorial sections (Gatherer)
│   ├── products/                 # Shared product components
│   │   ├── EditorialCard.tsx
│   │   ├── ProductCard.tsx
│   │   └── QuickBuyCard.tsx
│   ├── ui/                       # Shared UI components
│   │   ├── ContextBanner.tsx
│   │   ├── LoadingState.tsx
│   │   └── PersonaToggle.tsx
│   └── LayoutRenderer.tsx        # Maps schema to components
│
├── data/
│   ├── inventory.json            # 34 products with metadata
│   └── knowledge-graph.json      # Persona & context definitions
│
├── lib/
│   ├── ai/
│   │   ├── generate-layout.ts    # V1 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 V1 Files

lib/ai/generate-layout.ts

Core

The V1 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} />
}

V1 API Reference

POST/api/generate-layout

V1 endpoint: Generate a personalized layout based on persona and context. One-shot generation—no conversation memory.

REQUEST BODY

{
  "persona": "hunter" | "gatherer",
  "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
}

V1 vs V2 Comparison

Aspect	V1 (Manual API)	V2 (Agent-Native)
State Management	React useState	useCoAgent (shared state)
API Pattern	Manual fetch() calls	CopilotKit runtime
Refinement	Not supported	Spotify Loop ("too expensive")
Inventory Updates	Static (page reload)	Real-time (STATE_DELTA)
Agent Framework	None	LangGraph + CopilotKit

See V2 Documentation for full Agent-Native architecture details

Continue Reading

Technical Architecture

System design and AI pipeline

Start Over

Executive Summary

Business context and value proposition

Ready to Experience V1?

Try the V1 Demo

Experience the Hunter and Gatherer layouts in action