Technical Architecture
System Design
How the SIX generates personalized layouts in real-time using structured AI output, schema validation, and component composition.
System Context
The SIX sits between the shopper and the product catalog, using AI to dynamically generate personalized layouts.
Generation Flow
Each layout request flows through six stages, with hallucination prevention integrated at multiple points.
Request Flow
User Selects Persona
User chooses "Hunter" or "Gatherer" mode. Optional context (weather, urgency) is derived from client signals or explicitly set.
API Request
Frontend calls POST /api/generate-layout with persona and context. Request is validated against Zod schema.
Inventory Filtering
Products are loaded and filtered by: in-stock status, persona fit score (>0.2), context-relevant tags, and maximum count (50 for hunter, 30 for gatherer).
Prompt Construction
System prompt (persona definitions, rules) and user prompt (context + product list) are assembled. Product IDs are explicitly listed to prevent hallucination.
AI Generation
generateObject() from Vercel AI SDK calls GPT-4o with the prompt and Zod schema. Output is constrained to match the schema.
Validation & Rendering
Layout is validated for hallucinated product IDs. If valid, sent to client.LayoutRenderer maps component types to React components.
Hallucination Prevention
The primary failure mode for AI-generated commerce layouts is hallucinated product IDs. The model might reference products that don't exist or are out of stock. We prevent this with a three-layer defense:
Prompt Grounding
The prompt explicitly lists valid product IDs and instructs the model to "ONLY use product IDs from the provided inventory list."
NEVER invent or hallucinate product IDsSchema Enforcement
Zod schemas constrain output structure. generateObject()uses OpenAI's structured output mode for guaranteed schema compliance.
z.array(z.string()).min(1).max(24)Post-Validation
Every product ID in the response is checked against the valid ID set. Throws HallucinationError if any invalid.
validateLayout() → retry → sanitizeRetry & Fallback Strategy
- On hallucination: retry up to 2 more times with lower temperature (0.5)
- If still failing:
sanitizeLayout()removes invalid IDs - If no valid products remain: return deterministic fallback layout
Layout Schema
The AI generates a layout as a JSON object matching this Zod schema. The discriminated union on type allows type-safe component rendering.
// Layout response structure
LayoutResponseSchema = z.object({
metadata: z.object({
persona: z.enum(['hunter', 'gatherer']),
reasoning: z.string().max(500),
contextApplied: z.array(z.string())
}),
components: z.array(ComponentSchema).min(1).max(5)
});
// Component types (discriminated union)
ComponentSchema = z.discriminatedUnion('type', [
HeroComponentSchema, // Gatherer: hero section
GridComponentSchema, // Both: product grid
MagazineComponentSchema, // Gatherer: editorial sections
BannerComponentSchema // Hunter: urgency/info banners
]);
// Example: Grid component
GridComponentSchema = z.object({
type: z.literal('grid'),
columns: z.enum(['2', '3', '4']),
productIds: z.array(z.string()).min(1).max(24),
cardVariant: z.enum(['quick-buy', 'editorial', 'default']),
showFilters: z.boolean()
});Component Mapping
| Schema Type | React Component | Used By | Purpose |
|---|---|---|---|
hero | HeroLayout | Gatherer | Aspirational header with featured products |
grid | GridLayout | Hunter (primary) | Dense product grid with quick-buy cards |
magazine | MagazineLayout | Gatherer | Editorial sections with storytelling |
banner | ContextBanner | Hunter | Urgency/info messaging |
Persona-Specific Generation
Hunter Generation
- →Max 50 products considered
- →Output: 12-20 products displayed
- →Components: banner (optional) + grid
- →Card variant: quick-buy
- →Filters enabled
"Headlines should be direct: 'Rain Gear' not 'Weather the Storm in Style'"Gatherer Generation
- →Max 30 products considered
- →Output: 10-15 products displayed
- →Components: hero + magazine sections
- →Card variant: editorial
- →No filters (discovery mode)
"Make headlines poetic and mood-setting"Technology Stack
| Layer | Technology | Rationale |
|---|---|---|
| Framework | Next.js 14 (App Router) | Server components, streaming SSR, API routes |
| AI SDK | Vercel AI SDK | generateObject() with native Zod support |
| AI Model | GPT-4o | Best structured output support, fast inference |
| Validation | Zod | Type-safe schemas, runtime validation |
| Styling | Tailwind CSS | Rapid prototyping, utility-first |
| Data Store | JSON files | Zero latency for POC (upgrade path to Supabase) |