Technical Architecture
V1System Design
How the V1 SIX generates personalized layouts using manual API calls, structured AI output, and schema validation.
V1 Architecture: One-shot layout generation via manual fetch() calls. See V2 Architecture for the Agent-Native approach with CopilotKit, useCoAgent, and bidirectional state sync.
System Context
The V1 SIX sits between the shopper and the product catalog, using AI to dynamically generate personalized layouts via direct API calls.
V1 Request Flow
User Selects Persona
User chooses "Hunter" or "Gatherer" mode. Optional context (weather, urgency) is derived from client signals or explicitly set.
Manual API Request
Frontend calls POST /api/generate-layout via fetch(). Request is validated against Zod schema.
Inventory Filtering
Products are loaded from JSON file 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 (One-Shot)
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 → sanitizeLayout 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
]);V1 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 |
| State Management | React useState | Simple local state (V2 uses useCoAgent) |
| Data Store | JSON files | Zero latency for POC |