MVP Implementation Plan

Version: 1.2 — Working Document v1.2 changes: Audit pass — fixed document references, normalized epic table structure, decomposed bundled stories, added missing story areas, added milestone dependencies, added sprint load warnings, clarified M9→M10 entitlement gating v1.1 changes: Added M0: Tech Prep milestone, pulled staging deployment forward to M5, adjusted sprint cadence (+2 weeks) Scope: MVP.md feature set through founding-user launch Audience: Solo founder + 1 contract engineer; GitHub Projects tracking

⚠ 2026-06-08: Many inline story references point to TECH-SPEC.md, DESIGN-SYSTEM.md, DEPLOY-GUIDE.md, REPO-MAP.md, and GOSPELIB-SCHEMAS.md — these docs were never created or have been deleted. See the Document References table below for where that information actually lives now. The inline TECH-SPEC.md § … links are retained as section-intent markers but do not resolve to files.

---

How to Read This Document

This plan translates the MVP build order into GitHub-trackable work units. It does not repeat feature specs, API contracts, or design details — those live in the docs referenced below. Each epic here is a thin planning wrapper: enough context for story/issue writing, with pointers to authoritative sources.

Document References

Updated 2026-06-08: Several docs referenced below were never created or have been deleted as obsolete. Dead references are marked struck with notes.

Doc	Contains	Use When Writing Stories For
MVP.md	Feature scope, tier breakdown, success criteria, budget	Acceptance criteria, scope boundaries
TECH-SPEC.md	(never created — architecture lives in CORPUS-SPEC.md + service-level READMEs)	Technical implementation details
GOSPELIB-SCHEMAS.md	(deleted — superseded by CORPUS-SPEC.md §§ 14–16 and FalkorDB schema in services/ingest/)	Data models, graph schema
GOSPELIB-INGEST-SPEC.md	Ingest pipeline architecture (Draft — see note in file)	Ingest pipeline stories
DESIGN-SYSTEM.md	(never created — design tokens live in apps/web/styles/ and packages/ui/)	UI component stories
DEPLOY-GUIDE.md	(never created — see Deployment Overview)	Infrastructure and deployment stories
REPO-MAP.md	(never created — see monorepo layout in project root README)	All stories (coding standards)
GOSPELIB-MIGRATION-SPEC.md	(never created — migration handled by gldl adapter architecture)	M0 data preparation stories
Business	LEGAL.md, POLICY-TERMS.md, executive summary, market research, GTM	Launch readiness, legal/compliance stories

---

Tracking Structure

GitHub Project (board)
 └── Milestone (time-boxed release target)
      └── Epic (label) — groups related issues
           └── Issue / Story — single deliverable

Level	GitHub Construct	Naming Convention
Project	GitHub Project (board view)	GospeLib MVP
Phase	Project field (single-select)	P0: Foundation, P1: Reader, etc.
Milestone	GitHub Milestone	M1: Data Pipeline, M2: Content API, etc.
Epic	Label (epic:<name>)	epic:ingest, epic:reader, etc.
Sprint	GitHub Iteration field	2-week iterations
Story/Issue	GitHub Issue	Conventional title, links to epic label
Release	GitHub Release + tag	v0.1.0-alpha, v0.2.0-alpha, etc.

---

Phase Overview

Four phases mapping to MVP.md § Build Phases. Phases are sequential at the macro level; epics within a phase may overlap.

Phase	Milestones	Duration	Ends With
P0: Foundation	M0–M2	Weeks 1–10	Data pipeline operational, content API serving passages
P1: Core Reader	M3–M5	Weeks 9–20	Free-tier web app usable for daily scripture study, staging environment live
P2: Scholar Features	M6–M9	Weeks 17–32	Interlinear, JST, constellation, AI — all gated behind Scholar
P3: Launch	M10–M11	Weeks 29–38	Freemium billing, CFM, polish, founding-user onboarding

Overlap is intentional. Infrastructure work for the next phase starts 1–2 weeks before the current phase ends. Founding users enter at ~Week 22 per MVP.md § Build Phases.

Week  1       5       10      15      20      25      30      35      38
      |-------|-------|-------|-------|-------|-------|-------|-------|→
P0    ██████████████████████
P1              ░░██████████████████████████
P2                          ░░██████████████████████████████
P3                                        ░░████████████████████████
                                    ▲
                            Founding users

---

P0: Foundation

Goal: Corpus data flows from JSON files through the ingest pipeline into FalkorDB, and the content service serves passage data over HTTP.

Key constraint: Everything downstream depends on this. No reader, no interlinear, no graph view without a working data layer.

Milestone M0: Tech Prep — No release tag

Target: Weeks 1–2 (Sprint 0) Prerequisite milestone — no release artifact, just verified readiness for all downstream work.

Epic: epic:tech-prep

Establish cross-service patterns, tooling, and testing infrastructure before business logic begins.

Story Area	Scope	Spec Reference
Dev environment validation	Verify pnpm infra:up works, all services start with go run/uv run, setup.sh is current, document issues	TECH-SPEC.md § Development Workflow
PostgreSQL migration framework	Install golang-migrate, create migrations/ directory structure in auth + billing, add Nx migration targets (nx run auth:migrate-up), add migration CI step	TECH-SPEC.md § Data Architecture
Initial PostgreSQL schemas	gl_users, gl_user_devices, gl_subscriptions, gl_stripe_events, gl_highlights, gl_notes, gl_bookmarks, gl_reading_progress, gl_audit_log — all tables from tech spec	TECH-SPEC.md § PostgreSQL Schema
Typesense collection schemas	Define passages, topics, lexicon collection schemas per tech spec	TECH-SPEC.md § Typesense Collections
Response envelope utilities	Implement SuccessResponse/ErrorResponse helpers in Go (gateway, auth, billing) and Python (content, ai) matching the API contract	TECH-SPEC.md § Response Envelope
Structured logging configuration	Configure zerolog (Go) and structlog (Python) with JSON format, request_id, service name, version fields across all services	TECH-SPEC.md § Observability
Health check contract	Implement /health (alive) and /ready (dependency check) on all services with consistent JSON response shape	TECH-SPEC.md § Health Endpoints
Request ID propagation	Gateway generates X-Request-ID; downstream services extract and include in logs and error responses	TECH-SPEC.md § Communication
Testing infrastructure	Create per-project vitest.config.ts for TS packages, implement conftest.py fixtures for Python services, create one reference Go table-driven test per service, validate all test runners in CI	TECH-SPEC.md § Testing
OpenAPI spec workflow	Content service auto-generates OpenAPI via FastAPI; set up gen-types.sh to pull /openapi.json and generate TS types, validate generation pipeline	TECH-SPEC.md § API Design
Env validation schemas	Implement Zod env schemas in @gospelib/config for web app env vars	TECH-SPEC.md § Shared Packages
Error code catalog	Define UPPER_SNAKE error codes as constants in Go and Python (PASSAGE_NOT_FOUND, INVALID_REQUEST, UNAUTHORIZED, etc.)	TECH-SPEC.md § Response Envelope
Corpus v1→v2 migration	Run convert_corpus.py --input corpus --output data, validate output against v2 schemas, confirm data/ is canonical for ingest	GOSPELIB-MIGRATION-SPEC.md, REPO-MAP.md § Data & Corpus

Milestone M1: Data Pipeline — v0.1.0-alpha

Target: Weeks 3–8 Release artifact: ingest/v0.1.0-alpha — full corpus ingested into local FalkorDB

Epic: epic:ingest-core

Implement the 7-stage ingest pipeline per GOSPELIB-INGEST-SPEC.md.

Story Area	Scope	Spec Reference
Pydantic models	All 7 schema families + shared types	GOSPELIB-SCHEMAS.md § Schema Families
Book registry	Load + validate data/book_registry.json	GOSPELIB-INGEST-SPEC.md § Stage 1
ID generators	All 10 ids.py functions	GOSPELIB-INGEST-SPEC.md § ID Derivation
File loader	Schema-dispatched Pydantic validation	GOSPELIB-INGEST-SPEC.md § loader.py
FalkorDB client	Connection pool, batch write helpers, retry	GOSPELIB-INGEST-SPEC.md § Batch Strategy
Cypher constants	All MERGE queries for 12 node types + 16 edge types	GOSPELIB-INGEST-SPEC.md § Cypher Constants
Index creation	Stage 0 — primary + secondary indices	GOSPELIB-INGEST-SPEC.md § Index Schema
Lexicon pipeline	Stage 2 — :Word nodes, DERIVES_FROM, RELATED_TO	GOSPELIB-INGEST-SPEC.md § Stage 2
Scripture text pipeline	Stage 3 — :Passage, :Witness, :WordAlignment + all edges	GOSPELIB-INGEST-SPEC.md § Stage 3
TG/BD/Index pipelines	Stage 4 — concurrent file I/O, sequential writes	GOSPELIB-INGEST-SPEC.md § Stage 4
Commentary pipelines	Stage 5 — verse + scholarly commentary	GOSPELIB-INGEST-SPEC.md § Stage 5
Pending resolution	Stage 6 — promote :PendingPassage stubs	GOSPELIB-INGEST-SPEC.md § Stage 6
Pipeline runner	IngestRunner orchestrating stages 0–6 + report	GOSPELIB-INGEST-SPEC.md § Runner
CLI interface	Click commands: run, --dry-run, --only, --reset	GOSPELIB-INGEST-SPEC.md § CLI
Run report	JSON report with timing, counts, errors	GOSPELIB-INGEST-SPEC.md § Report

Epic: epic:ingest-test

Story Area	Scope	Spec Reference
Unit tests	Registry, ID derivation, Pydantic models (valid + invalid), batch helpers	GOSPELIB-INGEST-SPEC.md § Testing
Integration tests	Each pipeline against real FalkorDB (testcontainers)	GOSPELIB-INGEST-SPEC.md § Testing
Test fixtures	Minimal corpus files in data/fixtures/	GOSPELIB-SCHEMAS.md
Smoke test	Full pipeline on all fixtures	GOSPELIB-INGEST-SPEC.md § Testing

Epic: epic:corpus-validation

Story Area	Scope	Spec Reference
Schema compliance audit	Validate every corpus JSON file against Pydantic models	GOSPELIB-SCHEMAS.md
Data quality checks	Missing cross-refs, orphaned Strong’s numbers, encoding issues	GOSPELIB-SCHEMAS.md § Cross-References
Fixture generation	Create minimal test fixtures from real corpus files	GOSPELIB-SCHEMAS.md

Milestone M2: Content API — v0.2.0-alpha

Target: Weeks 7–10 (overlaps M1 tail) Release artifact: content/v0.2.0-alpha — passage retrieval + basic graph queries via HTTP

Prerequisites: M1 FalkorDB client + Stage 3 (scripture text) must complete — content service queries require ingested data

Epic: epic:content-service

Build out the content service per TECH-SPEC.md § Content Service.

Story Area	Scope	Spec Reference
GraphClient	FalkorDB connection pool, Redis query caching	TECH-SPEC.md § Content Service
Passage routes	GET /passages/{id}, GET /passages/{book}/{chapter}	TECH-SPEC.md § API Endpoints
Lexicon routes	GET /lexicon/{wordId}	TECH-SPEC.md § API Endpoints
Topic routes	GET /topics, GET /topics/{slug}	TECH-SPEC.md § API Endpoints
Dictionary routes	GET /dictionary/{term}	TECH-SPEC.md § API Endpoints
Graph routes	GET /graph/connections/{nodeId}	TECH-SPEC.md § API Endpoints
Response models	Pydantic response models matching the API envelope	TECH-SPEC.md § Response Envelope
Caching layer	Redis caching with gl:<resource>:<id> key pattern	TECH-SPEC.md § Caching Strategy
OpenAPI spec	Auto-generated by FastAPI at /openapi.json — no hand-authored spec needed	—
Content service tests	Unit tests for graph queries (mocked FalkorDB), integration tests for passage/lexicon/topic routes	TECH-SPEC.md § Testing

Epic: epic:gateway-core

Minimal gateway to route traffic to content service. Full auth/billing integration deferred to P3.

Story Area	Scope	Spec Reference
Reverse proxy	Route /api/v1/passages/*, /api/v1/lexicon/*, etc. → content	TECH-SPEC.md § Gateway
Request ID	Generate + inject X-Request-ID header	TECH-SPEC.md § Communication
CORS	Allow web app origin	TECH-SPEC.md § Gateway Middleware
Rate limiting	Basic sliding-window rate limiter (Redis)	TECH-SPEC.md § Gateway Middleware
Health aggregation	Gateway health check includes downstream service health	—
Gateway tests	Table-driven Go tests for proxy routing, request ID injection, rate limiting	TECH-SPEC.md § Testing

Epic: epic:shared-types

Story Area	Scope	Spec Reference
@gospelib/types	Scripture types (Passage, Verse, Chapter, etc.) generated or hand-typed from content OpenAPI	TECH-SPEC.md § Shared Packages
@gospelib/sdk	openapi-fetch client wired to content service endpoints	TECH-SPEC.md § Shared Packages
@gospelib/config	Zod env schemas for NEXT_PUBLIC_API_URL, etc.	TECH-SPEC.md § Shared Packages

---

P1: Core Reader

Goal: A web app where users can read all LDS scriptures, navigate by book/chapter, search, and annotate (highlights, notes, bookmarks). The free tier of MVP.md § Free Tier.

Key constraint: This must be "genuinely better than Gospel Library" — the free tier IS the acquisition funnel.

Milestone M3: Scripture Reader — v0.3.0-alpha

Target: Weeks 9–14 Release artifact: Web app displaying scripture text with chapter navigation

Prerequisites: M2 content API serving passage data; @gospelib/sdk wired to content endpoints

Epic: epic:reader-core

Story Area	Scope	Spec Reference
App shell	Layout, navigation sidebar, responsive breakpoints	DESIGN-SYSTEM.md § Navigation
Route structure	(marketing)/ and (app)/ route groups	TECH-SPEC.md § Next.js Apps
Scripture text display	ScriptureText, VerseNumber, ChapterHeader components	DESIGN-SYSTEM.md § P1 Components
Chapter navigation	Book selector → chapter list → verse display	DESIGN-SYSTEM.md § Navigation
Typography controls	Font size, 3 density modes (spacious/comfortable/compact)	MVP.md § Feature #9, DESIGN-SYSTEM.md § Reader
Dark mode	Light / Study Dark / Blackout themes	DESIGN-SYSTEM.md § Dark Mode
Reading modes	Reading mode (default) — Study and Interlinear modes deferred	DESIGN-SYSTEM.md § Render Modes
Responsive layout	Desktop, tablet, mobile breakpoints — web only	MVP.md § Platform

Epic: epic:ui-foundation

Build foundational @gospelib/ui components. Ref: DESIGN-SYSTEM.md § Component Priority.

Story Area	Scope	Spec Reference
Design token system	Full token implementation: color scales (navy, tan, white), doctrinal colors, corpus colors, semantic colors, functional colors, personal highlight colors, Night Warm tints. Spacing, radii, elevation shadows, motion curves/durations, layout constants, density presets — all from tokens.ts	DESIGN-SYSTEM.md § Design Tokens Reference
Typography infrastructure	Font loading/serving: Gentium Plus (scripture), Inter (UI), SBL Hebrew (Hebrew). Type scale (xs–3xl). Scripture text rendering rules (font-feature-settings, verse number styling, chapter drop caps, red-letter toggle). Original language text rules (RTL direction, sizing, line height)	DESIGN-SYSTEM.md § Typography
Paper & chrome surface system	Two surface personalities: paper (warm texture, white-200, noise pattern, warm shadows) vs chrome (clean, flat, cooler). 6-level elevation scale with warm rgba(20,16,10) shadows	DESIGN-SYSTEM.md § Elevation & Surface Language
Shape & geometry system	Corner radius philosophy: 12px paper, 8px chrome, 4px chips, 50% circular. Border usage rules. Horizontal rule styling	DESIGN-SYSTEM.md § Shape & Geometry
Custom icon set (P1 subset)	Stroke-based 1.5px icon system. P1 icons: reader, explore, study, search, profile, settings, corpus icons (corpus-ot, corpus-nt, corpus-bom, corpus-dc, corpus-pogp). Line default / filled active state convention	DESIGN-SYSTEM.md § Iconography
Motion & animation system	Easing curves (spring-snappy, smooth-in-out, decelerate, accelerate). Duration scale (instant→slow). Reduced motion support (prefers-reduced-motion crossfade fallbacks)	DESIGN-SYSTEM.md § Motion & Animation
Theme provider (3 modes)	Light / Study Dark / Blackout modes with semantic token resolution. Night Warm independent overlay. CSS custom properties or RN theme context for all tokens	DESIGN-SYSTEM.md § Dark Mode & Theming
Core primitives	Button, Icon, Text, Card, Badge — using token system	DESIGN-SYSTEM.md § Component Catalog P5
Scripture display components	ScripturePage (paper surface, scroll, gesture detection), VerseBlock (number + text + layers), ChapterHeader (drop cap, corpus bar, 3 styles)	DESIGN-SYSTEM.md § Component Catalog P1
Layout components	BottomTabBar, SideRail, ReaderChrome (auto-hide/summon with 3s timeout), SplitPaneLayout (tablet/web)	DESIGN-SYSTEM.md § Component Catalog P5, DESIGN-SYSTEM.md § Layout & Navigation
Loading & skeleton states	Scripture page shimmer (tan gradient, 1.8s), verse-number placeholders, content-shaped skeletons matching scripture text metrics. Optimistic UI pattern. First-load breathing icon animation	DESIGN-SYSTEM.md § Loading & Waiting States
Empty & error state patterns	Inline amber error cards (Elevation 1, never modal). Wordless success confirmations (visual change + haptic only). Empty state template (icon mark + one sentence + action)	DESIGN-SYSTEM.md § App-Wide Polish & Tone
Accessibility foundation	System font size scaling + in-app slider. 44×44px minimum touch targets. WCAG 2.1 AA contrast in default modes, AAA in Blackout. Screen reader labels. lang attributes for Hebrew/Greek	DESIGN-SYSTEM.md § Accessibility
Component playground	Storybook-based internal playground (packages/ui/.storybook/). All components in all states. Mode/density/font toggles. Visual regression baseline	DESIGN-SYSTEM.md § Design System Governance

Epic: epic:reader-interaction

Reader interaction patterns and gesture system needed for the P1 reading experience.

Story Area	Scope	Spec Reference
Reader chrome behavior	Auto-hide after 3s, single-tap margin summon, scroll-reveal (configurable). Minimal top bar (book/chapter nav) + bottom bar (progress + tools)	DESIGN-SYSTEM.md § Reader Chrome Behavior
Quick Settings Tray	Half-swipe-up invocation. Font size slider (12–28px, live preview), line spacing slider, brightness, density chips, mode chips, font dropdown. Bottom sheet (280px resting height)	DESIGN-SYSTEM.md § Quick Settings Tray
Reading density modes	Spacious / Comfortable / Compact. Line height, paragraph spacing, font size delta. Animated transitions (300ms smooth-in-out) with scroll position preservation	DESIGN-SYSTEM.md § Reading Density
Context panel (tablet/web)	Right-side 360px persistent workspace. State-driven content (empty → word → verse → AI → topic → search). History navigation. Remembers last content on chapter switch	DESIGN-SYSTEM.md § Contextual Panel System

Milestone M4: Annotations — v0.4.0-alpha

Target: Weeks 13–17 Release artifact: Users can highlight, note, and bookmark verses (persisted to PostgreSQL)

Prerequisites: M0 PostgreSQL schemas (annotation tables); M3 reader shell (verse anchoring for annotations)

Epic: epic:auth-integration

Story Area	Scope	Spec Reference
Clerk setup	Web app Clerk provider, sign-in/sign-up flows	TECH-SPEC.md § Authentication
Auth service	Clerk webhook handler, user sync to PostgreSQL (gl_users schema from M0)	TECH-SPEC.md § Auth Service
Gateway JWT	JWT validation middleware, X-User-Id injection	TECH-SPEC.md § Gateway Middleware

Epic: epic:annotations

Story Area	Scope	Spec Reference
Highlight system	8 doctrinal colors + 4 personal; verse long-press → color picker	MVP.md § Feature #2, DESIGN-SYSTEM.md § Floating Toolbar
Notes	Verse-anchored notes, markdown editor	MVP.md § Feature #3
Bookmarks	Double-tap bookmark, bookmark list view	MVP.md § Feature #4
Floating Toolbar	Contextual verse action menu (highlight, note, bookmark, share, cross-ref) — replaces deleted ActionRing	DESIGN-SYSTEM.md § Floating Toolbar
Annotation CRUD API	gl_highlights, gl_notes, gl_bookmarks CRUD routes in auth service (tables created in M0; this story adds the API layer)	TECH-SPEC.md § PostgreSQL Schema
User data API	CRUD endpoints for highlights/notes/bookmarks via gateway	TECH-SPEC.md § API Endpoints
Reading history	gl_reading_progress — chapter-level tracking	MVP.md § Feature #7

Milestone M5: Search + Staging — v0.5.0-alpha

Target: Weeks 16–20 Release artifact: Reference lookup + full-text search via Typesense; staging environment live

Prerequisites: M1 ingest pipeline (Typesense sync extends it); M3 reader (search UI lives in web app)

Epic: epic:search

Story Area	Scope	Spec Reference
Typesense sync	Ingest pipeline addition: index passages into Typesense	TECH-SPEC.md § Typesense
Search API	GET /search route in content service — query, filters, pagination	TECH-SPEC.md § API Endpoints
Reference lookup	Parse John 3:16, 1 Ne. 3:7, etc. → direct passage fetch	MVP.md § Feature #5
Search UI	Search bar, results list, facets (book, testament)	DESIGN-SYSTEM.md § P4 Components

Epic: epic:footnotes

Footnote rendering, data flow, and interaction. Ref: DESIGN-SYSTEM.md § Footnote & Reference System.

Story Area	Scope	Spec Reference
Footnote data API	Content service returns footnote data (cross-refs, TG/BD links, JST variants) as part of passage response — ensure ingest pipeline populates :VerseNote nodes and ANNOTATES edges	TECH-SPEC.md § Content Service, GOSPELIB-SCHEMAS.md § VerseNote
Footnote display modes	Three configurable modes: Superscript (default), Margin Flag, Inline Tooltip — user preference stored in reader settings	DESIGN-SYSTEM.md § Footnote & Reference System
Footnote type color coding	Visual coding per type: JST=gold, TG=navy, BD=tan, scholarly=purple, cross-ref=blue	DESIGN-SYSTEM.md § Footnote & Reference System
Footnote card component	Tap footnote → card with colored left border, content preview, navigation link	DESIGN-SYSTEM.md § Footnote & Reference System

Epic: epic:staging-deploy

Ship a staging environment before founding users arrive at ~Week 22.

Story Area	Scope	Spec Reference
Staging environment	EKS cluster (Terraform infra/terraform/environments/staging/), RDS, ElastiCache, Kustomize staging overlay, deploy all services	DEPLOY-GUIDE.md § Environments, REPO-MAP.md § Infrastructure
Staging CD pipeline	GitHub Actions → ECR → Kustomize overlay → ArgoCD sync on push to main	DEPLOY-GUIDE.md § CI/CD, REPO-MAP.md § CI/CD Files
Sentry integration	Error tracking SDK in web app + Python services + Go services	TECH-SPEC.md § Observability
Secrets management	AWS Secrets Manager or equivalent for staging API keys	DEPLOY-GUIDE.md § Secrets
Staging data seeding	Run ingest pipeline against staging FalkorDB; document seeding procedure	GOSPELIB-INGEST-SPEC.md § CLI

---

P2: Scholar Features

Goal: The three paid pillars that justify $79.99/year — interlinear Hebrew/Greek + JST, constellation view, and constrained AI. Ref: MVP.md § Paid Tier.

Key constraint: Founding users enter during this phase (~Week 22). Ship incrementally; don't wait for "complete."

Milestone M6: Interlinear & Lexicon — v0.6.0-alpha

Target: Weeks 17–24 Release artifact: Word-tap lexicon bubble and interlinear display mode for OT Hebrew + NT Greek

Prerequisites: M1 word alignment + lexicon data ingested; M3 reader (interlinear mode extends reader)

Epic: epic:interlinear

Story Area	Scope	Spec Reference
Interlinear data verification	Validate word alignment data in corpus against schemas	GOSPELIB-SCHEMAS.md § WordAlignment
Interlinear API	Passage response enriched with word alignment + Strong's data	TECH-SPEC.md § Content Service
WordToken component	Tap target for each original-language word	DESIGN-SYSTEM.md § P1 Components
Lexicon bubble	Tap word → pop-up with Strong's number, gloss, root, morphology	MVP.md § Priority #1
Word journey	Tap word → occurrences highlighted across current chapter	MVP.md § Priority #1
Interlinear display mode	Word-by-word with transliteration + gloss	DESIGN-SYSTEM.md § Interlinear View
Hebrew RTL rendering	Gentium Plus / SBL Hebrew font, BiDi layout	DESIGN-SYSTEM.md § Original Language
Study mode	Activate study mode from reader — verse long-press entry point	DESIGN-SYSTEM.md § Render Modes
P2 icon additions	interlinear, witness, strong-number, word-journey, graph-node icons	DESIGN-SYSTEM.md § Bespoke GospeLib Icons

Milestone M7: JST Interlinear — v0.7.0-alpha

Target: Weeks 23–27 Release artifact: JST variants displayed inline alongside KJV verses

Epic: epic:jst

Story Area	Scope	Spec Reference
JST data verification	Validate JST corpus files against schemas	GOSPELIB-SCHEMAS.md
JST API	Endpoint or passage enrichment returning JST variants for a verse	MVP.md § Priority #1b
Inline diff view	KJV ↔ JST word-level diff highlighting	MVP.md § Priority #1b
Manuscript attribution	Tap variant → source manuscript + context from JSPP	MVP.md § Priority #1b
Witness layer UI	Pull-down or panel for manuscript variant access	DESIGN-SYSTEM.md § Witness Layer

Milestone M8: Knowledge Graph — v0.8.0-alpha

Target: Weeks 25–32 Release artifact: Constellation view for KJV NT passages with cross-refs and topical links

Epic: epic:constellation

Story Area	Scope	Spec Reference
Graph data layer	Ensure cross-refs + topical guide edges ingested for NT	GOSPELIB-SCHEMAS.md § Edge Types
Graph query API	GET /graph/connections/{nodeId} — neighbors with typed edges	TECH-SPEC.md § API Endpoints
Constellation view	Interactive node graph — passages, topics, cross-references	MVP.md § Priority #2, DESIGN-SYSTEM.md § Constellation
Node rendering	Passage nodes, topic nodes; solid (cross-ref) vs dashed (topical) edges	MVP.md § Priority #2
Zoom interaction	Pinch-to-zoom-out from reader to constellation	MVP.md § Priority #2
List view toggle	Accessible alternative to graph visualization	MVP.md § Priority #2
ConnectionCard	Tap node → card with passage preview, link to navigate	DESIGN-SYSTEM.md § P3 Components
Graph-specific icons	temple-link, constellation node type shapes (rounded square, circle, hexagon, folded-corner, pentagon)	DESIGN-SYSTEM.md § Bespoke GospeLib Icons, DESIGN-SYSTEM.md § Constellation View

Milestone M9: AI Study Assistant — v0.9.0-alpha

Target: Weeks 28–32 Release artifact: Constrained AI Q&A about current passage with citations

Prerequisites: M2 content API (AI needs passage context); M3 reader (AI panel in web app). Note: AI ships without Scholar entitlement gating; entitlement enforcement added in M10 when billing goes live.

Epic: epic:ai-service

Story Area	Scope	Spec Reference
LLM client ABC	Abstract LLMClient with Anthropic (primary) + OpenAI (fallback)	TECH-SPEC.md § AI Service
Prompt templates	Jinja2 .j2 files for explain, questions, "what does original language reveal"	MVP.md § Priority #3
Caching decorator	Redis semantic caching by prompt hash	TECH-SPEC.md § AI Service
AI routes	POST /ai/explain, POST /ai/questions	TECH-SPEC.md § API Endpoints
Session limiting	10 sessions/month on Scholar tier (counter in Redis)	MVP.md § Priority #3
Citation linking	AI responses reference passages + lexicon entries as tappable links	MVP.md § Priority #3
AI UI	StudyAssistant panel, prompt template buttons, response display	DESIGN-SYSTEM.md § P4 Components
Gateway AI routing	Route /api/v1/ai/* → AI service; auth-required but Scholar entitlement gating deferred to M10 (epic:billing)	TECH-SPEC.md § Gateway
AI icon	ai-assistant spark/four-pointed star icon	DESIGN-SYSTEM.md § Navigation Icons

---

P3: Launch

Goal: Subscription billing, Come Follow Me integration, polish, and founding-user onboarding. Ship the product.

Key constraint: Billing/entitlement must be rock-solid. A user who pays must immediately get access. A failed payment must immediately revoke.

Milestone M10: Monetization — v0.10.0-alpha

Target: Weeks 29–34 Release artifact: Stripe subscription flow with Scholar gating live

Prerequisites: M4 auth integration (user identity for subscriptions); M2 gateway (entitlement middleware extends it)

Epic: epic:billing

Story Area	Scope	Spec Reference
Billing service	Stripe webhook handler, subscription CRUD, entitlement checks	TECH-SPEC.md § Billing Service
PostgreSQL tables	Subscriptions, entitlements, idempotency keys	TECH-SPEC.md § PostgreSQL Schema
Stripe checkout	Web checkout flow → Stripe Checkout → webhook confirm	TECH-SPEC.md § Billing
Entitlement middleware	Gateway checks plan tier before routing to Scholar endpoints	TECH-SPEC.md § Gateway Middleware
Subscription UI	Plan comparison, checkout trigger, billing portal link	DESIGN-SYSTEM.md § Subscription Boundaries
Diamond indicators	Premium feature markers (◇) in UI, warm unlock moments	DESIGN-SYSTEM.md § Subscription Boundaries
Free trial	14-day Scholar trial on signup	MVP.md § Freemium

Epic: epic:cfm

Story Area	Scope	Spec Reference
CFM schedule data	Weekly schedule mapping (year → week → passages)	MVP.md § Feature #6
CFM integration	Surface current week's reading on home/dashboard	MVP.md § Feature #6
Whisper card	Single contextual insight card per reading	MVP.md § Feature #13, DESIGN-SYSTEM.md § Whisper Cards

Epic: epic:sharing

Story Area	Scope	Spec Reference
Scripture card generator	Select verse → generate styled image card	MVP.md § Feature #11, DESIGN-SYSTEM.md § Scripture Cards
Share targets	Image export, deep link, clipboard	DESIGN-SYSTEM.md § Sharing

Milestone M11: Launch Readiness — v1.0.0

Target: Weeks 33–38 Release artifact: v1.0.0 — production deployment, founding users onboarded

Epic: epic:onboarding

Story Area	Scope	Spec Reference
Onboarding flow	3-act: reading plan → personalize → first passage with tutorial	DESIGN-SYSTEM.md § Onboarding
Returning user routing	Last reading position resume	DESIGN-SYSTEM.md § Onboarding

Epic: epic:polish

Story Area	Scope	Spec Reference
PWA optimization	Service worker, manifest, offline cache, home-screen install	MVP.md § Feature #8
Offline data caching	Cache recently read books for offline access via service worker	MVP.md § Feature #8
Performance audit	Core Web Vitals, time-to-interactive on scripture pages	—
Accessibility	Keyboard navigation, screen reader, ARIA labels, color contrast	DESIGN-SYSTEM.md § Accessibility
Error handling	Global error boundaries, API error states, offline fallbacks	—
SEO	Meta tags, OG images, structured data for scripture passages	—
Analytics	Event tracking for leading indicators	MVP.md § Leading Indicators

Epic: epic:infrastructure

Story Area	Scope	Spec Reference
Production environment	EKS + RDS + ElastiCache, production Kustomize overlay	DEPLOY-GUIDE.md § Production
Production CD pipeline	Release tag → approval gate → production deploy	DEPLOY-GUIDE.md § CI/CD
Monitoring & dashboards	Grafana dashboards, Prometheus alerting (Sentry already live from M5)	DEPLOY-GUIDE.md § Monitoring
Database migration automation	golang-migrate init containers, migration gating in CD	DEPLOY-GUIDE.md § Migrations
Backup procedures	RDS snapshots, FalkorDB BGSAVE → S3	DEPLOY-GUIDE.md § DR & Backups

Explicit Deferrals

The following workspace components are not in MVP scope and are intentionally deferred:

Component	Deferral Reason
Mobile app (apps/mobile)	MVP is web-only per MVP.md § Platform. Expo shell and navigation are scaffolded for post-launch.
Admin app (apps/admin)	No admin features in MVP scope. Dashboard skeleton exists for post-launch operational tooling.
Notifications service (services/notifications)	Redis Streams consumer and push/email stubs are scaffolded. Full implementation deferred to post-MVP when user engagement features are prioritized.

Epic: epic:legal

Story Area	Scope	Spec Reference
Privacy policy	Finalize + attorney review	POLICY-TERMS.md
Terms of service	Finalize + attorney review	POLICY-TERMS.md
Church disclaimer	In-app and marketing materials	LEGAL.md
Trademark filing	USPTO filing for “GospeLib”	LEGAL.md

---

Cross-Cutting Concerns

These are not milestones — they are ongoing practices that apply across all phases.

Testing

Layer	Framework	When	Spec Reference
Python unit/integration	pytest + testcontainers	Every PR	GOSPELIB-INGEST-SPEC.md § Testing
Go unit	go test -race + table-driven	Every PR	TECH-SPEC.md § Testing
TypeScript unit	Vitest	Every PR	TECH-SPEC.md § Testing
Component visual	Storybook or playground	P1+	DESIGN-SYSTEM.md § Governance
E2E	Playwright (deferred to P3)	Pre-release	—
Visual regression	Playwright + pixelmatch	P1+ (any packages/ui/ or apps/*/src/ change)	DESIGN-SYSTEM.md § Visual Regression CI

Documentation

Doc	Update Trigger
Getting Started	M1 complete — document local setup
Local Dev Setup	M2 complete — document full stack
Adding a Service	M2 complete — codify established pattern
Deployment Overview	M11 — document production deploy
Running Ingest	M1 complete — document pipeline operation
API OpenAPI specs	Each service milestone
ADRs	Each major technical decision

CI/CD

CI is already configured (.github/workflows/ci.yml). Key additions needed:

Addition	Phase	Detail
Python test containers in CI	P0	FalkorDB + PostgreSQL service containers for ingest integration tests
Nx affected test execution	P1	Vitest workspace already configured; needs per-project configs
Staging CD pipeline	P1	Merge to main → ECR → Kustomize → deploy (activated in M5)
Sentry error tracking	P1	Web + Python + Go SDK integration (activated in M5)
Production CD pipeline	P3	Release tag → approval gate → deploy
Visual regression screenshots	P1	Playwright renders component playground; pixelmatch diff blocks PRs exceeding 0.5% threshold

---

Sprint Cadence

2-week sprints. 19 sprints (S0–S18) to cover Weeks 1–38.

Sprint	Weeks	Phase	Primary Focus
S0	1–2	P0	Tech Prep: Dev environment validation, PostgreSQL migration framework + initial schemas, response envelope utilities, structured logging, health check contracts, testing infrastructure, OpenAPI workflow
S1	3–4	P0	Pydantic models, book registry, ID generators, file loader
S2	5–6	P0	FalkorDB client, Cypher constants, Stage 0–2 (indices + lexicon)
S3	7–8	P0	Stages 3–6 (scripture text → pending resolution), CLI, report
S4	9–10	P0→P1	Content service (GraphClient, passage routes), gateway proxy
S5	11–12	P1	Design token system, typography infrastructure, paper/chrome surfaces, icon set (P1), motion system, theme provider, core primitives, app shell, route structure
S6	13–14	P1	Scripture display components, reader chrome, Quick Settings Tray, density modes, dark mode, loading/skeleton states, empty/error patterns, accessibility, component playground
S7	15–16	P1	Auth integration (Clerk), annotations system (highlights, notes, bookmarks)
S8	17–18	P1→P2	Search (Typesense sync + API + UI), PWA offline, staging deploy + Sentry
S9	19–20	P2	Interlinear data verification, API enrichment, WordToken component
S10	21–22	P2	Lexicon bubble, word journey, interlinear display mode, Hebrew RTL
S11	23–24	P2	Founding users enter. JST data, inline diff view, manuscript attribution
S12	25–26	P2	Constellation view — graph query API, node rendering, zoom
S13	27–28	P2	Constellation polish (list view toggle), AI LLM client + prompts
S14	29–30	P2→P3	AI routes + caching + UI, session limiting, gateway AI routing
S15	31–32	P3	Billing service (Stripe), entitlement middleware, subscription UI
S16	33–34	P3	CFM integration, scripture card sharing, free trial flow
S17	35–36	P3	Onboarding, production deploy, monitoring dashboards, performance audit
S18	37–38	P3	Production polish, legal finalization, backup procedures, launch

⚠️ Sprint load warnings:

• S5 (Weeks 11–12) packs the entire design token system + typography + surfaces + icons + motion + theme + primitives + app shell + routes into 2 weeks. Consider splitting: tokens + typography + theme in S5; icons + motion + primitives + app shell in S6.
• S6 (Weeks 13–14) compounds with scripture display + reader chrome + Quick Settings + density + dark mode + loading states + error patterns + accessibility + playground. May need to push some items to S7.
• S15 (Weeks 31–32) includes full Stripe billing integration — historically one of the most complex third-party integrations. Allow buffer or start Stripe sandbox integration earlier.

---

Release Strategy

Tags follow <component>/v<semver> per release-please-config.json.

Release	Tag	Trigger	Contains
v0.1.0-alpha	ingest/v0.1.0-alpha	M1 complete	Full ingest pipeline operational
v0.2.0-alpha	content/v0.2.0-alpha, gateway/v0.2.0-alpha	M2 complete	Content API + gateway serving passages
v0.3.0-alpha	web/v0.3.0-alpha	M3 complete	Scripture reader (display + navigation)
v0.4.0-alpha	web/v0.4.0-alpha, auth/v0.1.0-alpha	M4 complete	Authentication + annotations
v0.5.0-alpha	web/v0.5.0-alpha	M5 complete	Search + offline; staging environment goes live
v0.6.0-alpha	web/v0.6.0-alpha	M6 complete	Interlinear + lexicon (Scholar)
v0.7.0-alpha	web/v0.7.0-alpha	M7 complete	JST interlinear (Scholar)
v0.8.0-alpha	web/v0.8.0-alpha	M8 complete	Constellation view (Scholar)
v0.9.0-alpha	web/v0.9.0-alpha, ai/v0.1.0-alpha	M9 complete	AI study assistant (Scholar)
v0.10.0-alpha	billing/v0.1.0-alpha	M10 complete	Billing + CFM + sharing
v1.0.0	web/v1.0.0, all services v1.0.0	M11 complete	Production launch

---

Risk Registry

Risk	Impact	Mitigation
Ingest pipeline data quality issues	Blocks all downstream features	Corpus validation epic in P0; dry-run + schema enforcement
FalkorDB performance at corpus scale	Slow content API, bad UX	Benchmark after M1; index tuning; caching layer in M2
Clerk/Stripe integration complexity	Delays auth + billing	Start integration in parallel with reader; use sandbox environments early
Interlinear Hebrew RTL rendering	Core differentiator broken or ugly	Prototype RTL layout early in P2; test with real corpus data
Constellation view performance	Graph viz too slow for complex passages	Start with NT-only subset per MVP scope; lazy-load nodes
AI cost overruns	Monthly API costs exceed budget	Session limiting, prompt caching, Anthropic's caching API, cost monitoring
Solo founder velocity	38-week plan too aggressive	Founding users at Week 22 provide feedback before full scope; cut P3 scope if needed
Custom icon set scope creep	Delays P1 reader delivery	Ship P1 with minimum viable icon set (navigation + corpus only); expand in P2. Consider temporary placeholder icons
Design token system complexity	Over-engineering slows initial delivery	Implement tokens incrementally: colors + typography first (S5), then elevation + motion + density (S6). Keep token API simple
Tech prep scope creep	Delays P0 ingest work	Strict 2-week timebox for Sprint 0; defer nice-to-haves; only implement what's blocking downstream work
Missing specification documents	DESIGN-SYSTEM.A1.md doesn't exist (referenced by M10/M11 UX flows); GOSPELIB-MIGRATION-SPEC.md not written	Write DESIGN-SYSTEM.A1.md before P3 or merge content into DESIGN-SYSTEM.md; document corpus migration process before M1

---

Current State → First Steps

Note (2026-06-12): The “starting conditions” below described the initial scaffolded state at project kickoff. As of June 2026, the codebase has progressed far beyond this state: 8 fully implemented services, 9 shared packages, 24+ ingest pipeline stages, a complete web app with plugin architecture, study map, and 332 of 365 milestone issues complete (91%).

The codebase was initially fully scaffolded with zero business logic implemented. Key starting conditions at project kickoff:

• Monorepo tooling: Nx, pnpm workspaces, CI pipeline, Docker Compose, commitlint, Release Please — all functional
• All services: Health-only stubs (/health, /ready). Go services were identical boilerplate; Python services had empty sub-packages
• Ingest service: Stub files (models, pipelines, DB layer) — all NotImplementedError or # TODO
• TypeScript apps: “Coming soon” placeholders. No route groups, no components, no data fetching
• Packages: Empty barrels (types had empty interfaces, sdk returned {}, config had empty Zod schema)
• Corpus data: Complete across all 7 schema families (~966 files, ~215 MB)
• Infrastructure: Docker Compose functional (4 data stores). K8s base manifests existed. Terraform modules were stubs.
• Tests: Zero implemented
• OpenAPI specs: None generated

Immediate actions (Sprint 0 — Tech Prep):

1. Verify local dev environment — pnpm infra:up spins up all data stores, all services start with go run/uv run
2. Set up PostgreSQL migration framework (golang-migrate) and write initial schemas for all tables
3. Implement response envelope utilities in Go and Python — error codes, success/error response helpers
4. Configure structured logging (zerolog/structlog) with consistent JSON format across all services
5. Bootstrap testing infrastructure — per-project Vitest configs, Python conftest.py fixtures, reference Go tests
6. Set up OpenAPI spec generation workflow (gen-openapi.sh → gen-types.sh)

Sprint 1 then begins epic:ingest-core — Pydantic models are the foundation of everything.

---

Appendix: Epic Label Reference

For GitHub Issues, apply these labels:

Label	Phase	Color
epic:ingest-core	P0	#0E8A16
epic:ingest-test	P0	#0E8A16
epic:corpus-validation	P0	#0E8A16
epic:content-service	P0	#1D76DB
epic:gateway-core	P0	#1D76DB
epic:shared-types	P0	#1D76DB
epic:reader-core	P1	#5319E7
epic:ui-foundation	P1	#5319E7
epic:reader-interaction	P1	#5319E7
epic:auth-integration	P1	#D93F0B
epic:annotations	P1	#D93F0B
epic:search	P1	#D93F0B
epic:footnotes	P1	#D93F0B
epic:interlinear	P2	#FBCA04
epic:jst	P2	#FBCA04
epic:constellation	P2	#FBCA04
epic:ai-service	P2	#FBCA04
epic:billing	P3	#B60205
epic:cfm	P3	#B60205
epic:sharing	P3	#B60205
epic:onboarding	P3	#E99695
epic:polish	P3	#E99695
epic:infrastructure	P3	#E99695
epic:legal	P3	#E99695
epic:tech-prep	P0	#0E8A16
epic:staging-deploy	P1	#1D76DB