specs/01-PRD.md
CurioQuest — PRD (DRAFT skeleton)
How to read this: Every line is tagged. [LOCKED] = already decided in a frozen doc; do not reopen — just confirm. [DECISION NEEDED] = your call, blocks downstream work. [DRAFT] = my proposed wording for you to accept/edit/reject. This is a skeleton — thin on purpose. We fill each section together.
1. Purpose of this document
This PRD is the single agreed answer to what we are building, for whom, and what "done" means — for the pilot first, then the platform. It sits above the architecture, UX, and per-module specs. Nothing gets built that isn't traceable to a requirement here.
2. Product in one paragraph [LOCKED — Project-Objective v0.2]
Personalized, curriculum-aligned STEM story + activity books where the child is the hero, supported by a personalized cast and a teaching guide the family chooses (default: Professor T-Rex). Built to grow with the child across grades. Sold preview → purchase (free ~20% preview → paid digital → physical upsell), not freemium.
Confirm this is still the frozen definition, or flag any drift. I will not reopen the business/revenue model.
3. Who it's for (users & their jobs)
| User | Who | Their job-to-be-done | Phase |
|---|---|---|---|
| Operator | You (concierge pilot) | Run the factory for one child, review each stage, ship a finished book | Pilot (now) |
| Parent / buyer | Fulton County GA parents (pilot) | Get a book their child loves that actually teaches the standard | Pilot → Platform |
| Child / reader | Grade 1→2 (pilot) | Be the hero; do the experiment; earn the badge | All |
[DECIDED 2026-06-03] The operator console is the durable long-term ops cockpit — the permanent internal tool for running and reviewing book production from pilot through scale. This justifies investing in real architecture, real storage, and good UX now (not a throwaway).
4. Scope — three phases, explicit IN / OUT
Phase 0 — Concierge Pilot [LOCKED charter — Build-Decomposition-Plan]
- IN: Fulton County GA, GSE Grade 1→2 science, an 8-story Summer Bridge pack, OpenAI (gpt-4o + gpt-image-2), operator runs the factory by hand and reviews every gate.
- OUT: self-serve signup, automated payments, localization, scale automation.
- Goal of the pilot: validate the unknowns desk research can't — preview→paid ≥ 6%, repeat intent ≥ 40%, AI reject rate, POD feel. [LOCKED]
Phase 1 — MVP Platform [GATED behind pilot]
- [DECISION NEEDED] Feature list for Phase 1 is NOT yet written. Candidate set: customer storefront, preview paywall, account + progression, automated generation, POD integration. We define this after pilot data — but we should agree the shortlist now so architecture doesn't paint us into a corner.
Later
- Localization (language-first; "biggest documented upside") [LOCKED as post-MVP], scale/human-in-loop reduction.
5. Success metrics
| Metric | Target | Phase | Status |
|---|---|---|---|
| Preview → paid conversion | ≥ 6% | Pilot | [LOCKED] |
| Repeat purchase intent | ≥ 40% | Pilot | [LOCKED] |
| AI image reject rate | measure (no target yet) | Pilot | [DECISION NEEDED — set a ceiling?] |
| Per-book production cost | within unit economics | Pilot | [DECISION NEEDED — what's the cap?] |
| Per-book operator time | measure | Pilot | [DRAFT — propose we track it] |
6. The two end-to-end flows (what the system must do)
6a. Operator factory run [LOCKED structure — 14 per-book product modules]
Intake brief → n8n-orchestrated backend workflow → 14-module product pipeline → finished PDF, pausing at 7 human gates (M3, M4, M5, M7, M8, M11, M13) for approve / regenerate / reject. [DECIDED 2026-06-08] n8n is the backend workflow/control plane because it gives the founder observability and operational control. Code services remain typed generation, persistence, catalog, and API helpers that n8n can call; they are not the primary orchestration surface. The current factory code may still expose legacy 16-step progress IDs until the pipeline is refactored, but the product module catalogue is M1-M14. (Detailed per-module behavior → 02-Module-Functional-Specs.md; n8n operating policy → ../n8n/README.md.)
6b. Customer purchase flow [DECIDED 2026-06-03]
Flow: build brief → generate personalized ~20% preview → pay → generate the remaining pages → unlock full digital → POD physical upsell. - Generation timing — DECIDED: preview generated before purchase (it's what drives the sale and must be truly personalized); the rest of the book is generated after payment. Rationale: at ~6% conversion, fully generating every preview-as-book would mean paying for ~16 books per sale — too expensive. Trade-off accepted: buyer waits ~5–15 min post-purchase while the full book renders ("your book is being illustrated"). - Shopify ↔ generator seam — DECIDED (principle): Shopify owns checkout, payments, POD/fulfillment trigger, and product listings. A custom generator app owns the creation wizard, the 14-module product pipeline, preview rendering, accounts, and progression. The seam: purchase event in Shopify → triggers post-purchase generation in the app; app reports book-ready back for digital unlock + POD. - Concierge-pilot note: in the pilot the operator does all of this by hand; the above is the Phase 1 architecture principle that the data model + services must support from day one.
7. Data & storage requirements
Today (the broken state we're fixing): live state is in-memory (lost on restart), artifacts are 87 loose folders on disk, no database, no ledger.
- [DECIDED 2026-06-03] The system uses a real database as the durable record — runs, briefs, gate decisions, and orders are persisted in a proper datastore that survives restarts and is queryable. (Specific engine — SQLite vs Postgres vs Supabase — is settled in the Architecture doc 02.)
- [DECIDED — implied] Generated binary artifacts (PNGs, PDFs) still live on a filesystem/object store; the DB holds the records and points to them. Not loose unmanaged folders.
- [DECIDED 2026-06-03] The Google Sheet is dropped entirely. The real DB is the sole system of record. No gspread, no service-account, no Sheet sync — one less moving part. (SHEET_ID and the R3 ledger work are cancelled.)
8. Non-goals / frozen (do not build, do not reopen)
- Revenue model, business plan, metrics theory — FROZEN. [LOCKED]
- The superseded 12-agent architecture — dead. [LOCKED]
- n8n is now the accepted backend workflow/control plane. [DECIDED 2026-06-08]
- Localization, multi-language — post-MVP. [LOCKED]
9. Open questions blocking the build (consolidated)
- ~~Operator console: throwaway or durable?~~ DECIDED: durable cockpit. (§3)
- Phase 1 feature shortlist — enough to constrain architecture now? (§4) ← next
- ~~Storage: real DB or disk + Sheet?~~ DECIDED: real DB; files on object store; Sheet dropped. (§7)
- ~~Shopify seam + generation timing?~~ DECIDED: preview pre-purchase, full book post-purchase; Shopify=commerce, app=generation. (§6b)
- Pilot pricing, delivery order, AI reject ceiling, cost cap. (§5) — business params, can defer
- Human-in-the-loop ratio at scale — what stays gated? (later)
10. Sign-off
- [ ] Founder has reviewed every [DECISION NEEDED] and either decided or deferred with a reason.
- [ ] All [LOCKED] items confirmed as still true (no drift).
- [ ] This PRD is ratified → unlocks the Architecture doc (02).