E0: Foundation — 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:

• Stand up a working local dev environment in Docker: Postgres 16 + pgvector + Next.js 14 shell
• Create the full database schema from the project design doc's data model
• Scaffold the repo layout so E1, E2, and E3 have clear homes for their code
• Establish env-var conventions, secrets handling, and local setup docs
• Provide a make dev (or equivalent) one-command bring-up

Non-Goals:

• No ingestion logic (E1)
• No MCP servers (E2)
• No UI features beyond a shell page that proves the stack is wired (E3)
• No production deploy, hosting config, or CI
• No auth — explicitly deferred past Demo MVP

Problem Statement#

We have a design doc and a revised MVP plan, but zero code. Every other epic is blocked until the local stack runs. Without a foundation, E1 can't target a schema, E2 can't talk to a database, and E3 can't render anything.

The goal is to hit "I can run docker compose up, open localhost, and see a working page backed by an empty but schema-complete Postgres+pgvector" in as few hours as possible — then stop. Nothing else.

What Is This Epic?#

Foundation is the scaffolding epic. It creates the repo skeleton, the Docker environment, the database schema, and a minimal Next.js app that proves the connection layer works end-to-end. When E0 is done, every other epic has a concrete target to build into.

Context#

Dependents#

Every other MVP epic depends on E0:

• E1 (Ingestion + Vector DB) — needs the schema to exist before it can load data
• E2 (MCP Servers) — needs the DB connection layer and env conventions
• E3 (UI) — needs the Next.js shell to build pages into

Dependencies#

• Node.js 20+ installed locally
• Docker Desktop running
• A directory to put the repo (likely ~/Documents/Code/quoteai)

No external APIs, no cloud accounts. Fully local.

Current State#

No code. The design doc lives in Foundry at projects/quoteai/design.md. The Brehob source data lives in a shared Google Drive folder (QuoteAI - Brehob Quote History) — relevant to E1, not E0.

Affected Systems#

Design#

Repo Structure#

quoteai/
├── app/                          # Next.js 14 (App Router)
│   ├── app/
│   │   ├── layout.tsx            # root layout, dark-mode-first
│   │   ├── page.tsx              # placeholder home
│   │   └── health/
│   │       └── page.tsx          # "✓ DB connected" smoke test
│   ├── lib/
│   │   └── db.ts                 # Postgres client (pg or @neondatabase/serverless)
│   ├── package.json
│   └── tsconfig.json
├── db/
│   ├── schema.sql                # full schema from design doc
│   ├── migrations/               # numbered SQL files, applied on container boot
│   │   └── 001_init.sql
│   └── seed/                     # empty for E0; populated by E1
├── ingestion/                    # E1 lives here (empty stub for E0)
│   └── .gitkeep
├── mcp-servers/                  # E2 lives here (empty stub for E0)
│   ├── equipment/.gitkeep
│   └── quotes/.gitkeep
├── docker-compose.yml            # postgres + pgvector + next dev container (optional)
├── .env.example                  # documented env contract
├── .env                          # local only, gitignored
├── Makefile                      # make dev, make db-reset, make test
├── README.md
└── CLAUDE.md                     # project-specific instructions for CC

Docker Compose Target#

# docker-compose.yml — shape only, not final
services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_DB: quoteai
      POSTGRES_USER: quoteai
      POSTGRES_PASSWORD: quoteai
    ports: ["5432:5432"]
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./db/migrations:/docker-entrypoint-initdb.d

Next.js runs on the host (not in Docker) for fast HMR during dev. Docker only hosts Postgres for MVP.

Data Model Changes#

Apply the full schema from the project design doc's Data Model section, plus three E1-driven additions folded in now (pre-E1-ingest, so no migration later).

Tables created in 001_init.sql:

• products (catalog + vector)
• past_quotes (raw text + vector)
• quote_line_items (the description library — atomic retrieval units)
• vendor_quotes (reference)
• quote_log (empty for Demo MVP but schema exists)
• quote_log_items (empty for Demo MVP but schema exists)
• feedback
• All ivfflat vector indexes

E1-driven additions (per agreed decision 2026-04-18 in E1 Decisions Log). Added to products, past_quotes, and quote_line_items:

extractor_version TEXT,   -- e.g., "haiku-4-5-v1" — enables A/B comparison when extraction prompts evolve
source_hash TEXT,         -- hash of raw input text (pre-parse) — skip file entirely if unchanged
content_hash TEXT,        -- hash of extracted content block (post-parse) — re-embed only changed blocks within a file

Why these three now: The E1 ingestion pipeline will write extractor_version per row for prompt-versioning; the re-embed detection logic needs both hash columns. Landing them in 001_init.sql is free right now (no data yet); migrating after E1 ingests would be painful.

Quote log tables are created even though they're not populated until Full MVP — saves a migration later.

Approach#

1. git init the repo at ~/Documents/Code/quoteai
2. Scaffold Next.js 14 with TypeScript, Tailwind, App Router
3. Add shadcn/ui primitives (button, form, input, card) — dark-mode-first since Dan prefers dark mode
4. Write docker-compose.yml with pgvector/pgvector:pg16
5. Write db/migrations/001_init.sql with full schema
6. Write app/lib/db.ts with a typed Postgres client
7. Add /health page that runs SELECT 1 and shows status
8. Write README.md and CLAUDE.md (CC operating instructions for this repo)
9. Write Makefile with dev, db-reset, test targets

API / Interface Changes#

No external APIs. Internal interface to establish:

• app/lib/db.ts exports a singleton Postgres pool with typed query helper
• Environment variables: DATABASE_URL, ANTHROPIC_API_KEY (placeholder, unused until Full MVP), OPENAI_API_KEY (for embeddings — used by E1)

Edge Cases & Gotchas#

Testing Strategy#

QuoteAI doesn't have a full Validation Pipeline yet (that's Routr's level of rigor). For E0, testing is minimal and manual.

Test Layers#

Verification Checklist#

1. make dev brings up Postgres and Next.js with zero manual steps beyond copying .env.example to .env
2. /health page shows DB connection OK + a list of created tables matching the schema
3. psql into the container confirms pgvector extension is installed and all tables exist
4. make db-reset wipes and rebuilds the DB from migrations cleanly

Stories#

Known Issues / Tech Debt#

Open Questions#

Open questions that need a human call before implementation.

Risks#

Decisions Log#

Once E0 is shipped, stories for E1 can begin. No other epic can start until make dev is green.