E3: UI — Epic Design Doc#

Status: 🔄 In Refinement (Step 0) Authors: Dan Hannah & Clay Created: 2026-04-18 Parent: QuoteAI Project Design Doc

Overview#

Goals & Non-Goals#

Goals:

• Ship a structured quote-request form (the "wall" per John) with all 15+ required fields, validated
• Ship a draft-view page that renders the CC-generated quote in 4M-template shape
• Wire the form → CC → draft-view flow end-to-end
• Dark-mode-first design (per user preference) — clean, "nice-looking," professional enough to show John
• Feedback buttons on the draft view (👍/👎 per line item)

Non-Goals:

• No authentication / login
• No approval workflow UI (Full MVP)
• No quote log / dashboard UI (Full MVP)
• No PDF export (copy-paste from the rendered draft is fine for demo)
• No responsive mobile polish (desktop demo first)
• No admin UI for managing ingested data (CLI only, per E1)

Problem Statement#

The UI is the face of the demo. Two things have to work: (1) the form must feel like a natural upgrade to the Brehob spreadsheet salespeople fill today, and (2) the output must look like a Brehob quote, not a "generic AI draft." Both are needed for John to react with "this is how every quote should look."

Per John's "wall" constraint, the form is the only way salespeople interact with the system. No chat, no freeform AI prompt. The form is the contract.

What Is This Epic?#

A Next.js (App Router) UI with two primary pages:

1. /quotes/new — the structured quote request form
2. /quotes/draft/[id] — the CC-assembled draft view in Brehob template format

Plus the glue that connects them: a Server Action or API route that receives the form submission, writes a pending request to a temp table, triggers CC to assemble the draft, and displays the result.

Context#

Dependents#

• Demo experience — E3 is what John actually sees
• Future Full MVP E4 (Approval Workflow) — adds a review queue on top of /quotes/draft/*

Dependencies#

• E0 (Foundation) — Next.js shell, Tailwind, shadcn/ui primitives exist
• E2 (MCP Servers) — CC needs them running to assemble drafts
• E1 (Data) — via E2
• Claude Code — the demo's generator; triggered from the app

Current State#

Next.js shell exists from E0 with a /health page. No forms, no draft view, no generate flow.

Affected Systems#

Design#

Page: /quotes/new#

Form built with React Hook Form + Zod validation. Sections:

1. Customer Info — Company, contact, address, ship-to, email, phone
2. Quote Metadata — Salesperson name, TM number, date required, (auto-filled) quote number preview
3. Line Items (repeatable, 1-N) — Each with: description hint, qty, CFM, PSI, HP, voltage, cooling (air/water), unit price (entered by salesperson)
4. Context — Free-text field for "special requirements" (e.g., "food-grade environment, oilless required")

Submit button: "Generate Draft"

Validation (per design doc "The Wall"):

• CFM: 1–5,000
• PSI: 10–500
• HP: 1–500
• Voltage: must match patterns like 230/1/60, 460/3/60
• TM Number: required (salesperson's territory number)
• All customer fields required
• Date required: must be a future date
• At least one line item with a description

Page: /quotes/draft/[id]#

Renders the assembled draft in Brehob template shape. Layout:

1. Header bar — Quote #, status badge, copy-to-clipboard button
2. Document preview — Rendered markdown (from CC's output) styled to mimic the 4M letterhead/template
3. Per-line-item feedback — Each line item has 👍/👎 with optional comment
4. Action bar — "Regenerate" button (useful during iteration), "Copy Quote Text" (for paste-into-email-to-customer)

Important: This is a display layer for CC's output, not a WYSIWYG editor. For demo, salesperson edits happen by re-submitting the form. Full MVP can add inline editing.

Generate Flow (form → CC → draft)#

Demo architecture uses Claude Code as the generation engine. This is the only real "magic" in the demo — the flow needs to be explicit about it.

1. Form submits to POST /api/quotes/generate (Next.js Route Handler)
2. Handler validates form data against Zod schema
3. Handler inserts a row into `quote_drafts` with status='pending', form_json
4. Handler invokes Claude Code via a local subprocess (or a "/quoteai-generate" skill)
   passing: form_json + path to templates/brehob-quote.md + MCP server config
5. CC calls search_line_items, search_equipment, search_past_quotes as needed
6. CC returns assembled draft text
7. Handler updates quote_drafts row: status='ready', generated_text
8. Handler redirects to /quotes/draft/[id]
9. Page renders generated_text in Brehob template style

CC invocation detail: Easiest path is a local CLI spawn: claude -p "$PROMPT" --mcp-config ./cc-mcp-config.json. The prompt assembles form data + reference to the template file. CC handles MCP tool calls internally.

If the subprocess path is awkward, alternative: CC runs as a persistent background agent and the app talks to it via a local HTTP endpoint. TBD in S0 spike.

Styling / Design System#

• shadcn/ui components (Form, Input, Card, Button, Badge, Tabs)
• Tailwind with dark-mode class on <html> by default
• Typography — Inter or similar for UI; serif for the document preview (mimics Brehob's Word-doc feel)
• Color palette — neutral dark with a single accent (maybe Brehob blue?) — keep it calm, professional
• Print styles — document preview should print/PDF cleanly even though explicit PDF export is post-MVP

Data Model Changes#

One new table for demo flow persistence:

CREATE TABLE quote_drafts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    form_json JSONB NOT NULL,
    generated_text TEXT,
    status TEXT DEFAULT 'pending',  -- pending, ready, failed
    generated_at TIMESTAMPTZ,
    error TEXT,
    created_at TIMESTAMPTZ DEFAULT now()
);

This is demo-scoped. When Full MVP E5 lands, quote_drafts rows get promoted into quote_log + quote_log_items. Or the table gets renamed. Decide during Full MVP scoping.

API / Interface Changes#

Route Handlers (Next.js)#

Client Components#

• <QuoteRequestForm /> — the form
• <LineItemEditor /> — repeatable line-item sub-form
• <DraftView /> — renders generated_text
• <FeedbackButton /> — per-line-item rating

Edge Cases & Gotchas#

Testing Strategy#

Test Layers#

Required Fixtures#

Note on benchmark quotes (new per 2026-04-18 decision): Distinct from the golden retrieval test (E1). The golden retrieval test asks "did we find the right line items?" The benchmark quotes ask "does the assembled draft match a known-good Brehob quote?" Both run during E3's E2E verification.

Verification Rules#

1. Golden scenario passes end-to-end before demo. Open form → fill it in → draft appears matching golden-draft.md within acceptable drift.
2. Benchmark quotes pass end-to-end. Given the original form inputs for 4M / Bowen / Munson, the generated drafts match the benchmark fixtures for description fidelity, formatting, and completeness. This is the assembled-output quality gate (complementary to the golden retrieval test in E1).
3. Dark mode is the primary baseline. Per user preference.
4. Form validation errors are clear and in-place (not a toast at the top).
5. All user preferences from memory files respected (dark mode especially).

Stories#

Post-S11 demo polish (2026-04-21 → 2026-04-22)#

Not numbered stories — small scoped changes landing ahead of John's review.

Note on story drift. The pre-implementation Stories list (2026-04-18) had different summaries for S3-S10 — field validation, line-item repeater, multi-option tabs, feedback buttons, loading states, E2E walkthrough, dark-mode polish. Implementation diverged as shape emerged. Most notably S5 (multi-option quotes) was dropped per E3-D1, and post-generation UX (streaming, three-rail draft, regenerate flow) became the bulk of the work. The table above reflects what shipped, not the original aspiration.

Known Issues / Tech Debt#

Risks#

Decisions Log#

Active decisions being validated during John's demo review live in quoteai/decisions.md — E3-D1 (no multi-option), E3-D4 (thinking disabled), E3-D5 (four-stage checklist), E3-D6 (display pacer), E3-D8 (preamble trim). They graduate here once the demo validates them.

E3 is the demo. Everything previous exists to make this moment — John opens the page, fills the form, and sees the draft — land right.