M04: Annotations — v0.4.0-alpha
Phase: P1: Core Reader Target: Weeks 13–17 Sprints: S6 (tail), S7, S8 (start) Release Tags:
web/v0.4.0-alpha,auth/v0.1.0-alpha
Phase Context
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.
ZenHub Configuration
| Field | Value |
|---|---|
| Milestone | M04: Annotations |
| Due Date | 2026-07-05 |
| Default Pipeline | Product Backlog |
| Primary Epic(s) | Auth Integration, Annotations & Study Tools |
Prerequisites
| Prerequisite | Source Milestone | What Must Be Complete |
|---|---|---|
| PostgreSQL annotation schemas | M00: Tech Prep | gl_highlights, gl_notes, gl_bookmarks, gl_reading_progress, gl_users, gl_user_devices tables created via migration framework |
| Reader shell with verse anchoring | M03: Scripture Reader | Scripture text display, verse rendering, chapter navigation — verse elements must support annotation anchoring |
Epics
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 M00) | TECH-SPEC.md § Auth Service |
| Gateway JWT | JWT validation middleware, X-User-Id injection | TECH-SPEC.md § Gateway Middleware |
Issues — Auth Integration
| ID | Title | Status | Notes |
|---|---|---|---|
| M04-001 | Clerk Setup — Web App Authentication Provider | ✅ Done | implemented in PR #901 (2026-04-03) |
| M04-002 | Auth Service — Clerk Webhook Handler & User Sync | ✅ Done | implemented in PR #901 (2026-04-03) |
| M04-003 | Gateway JWT Validation Middleware & User Injection | ✅ Done | implemented in PR #901 (2026-04-03) |
| M04-004 | Action Ring — Radial Verse Action Menu | ✅ Done | completed (2026-04-03) |
| M04-005 | Highlight System — Doctrinal Colors & Color Picker | ✅ Done | Completed in PR #962 (2026-04-13); gutter annotation panel opener wired |
| M04-006 | Notes — Verse-Anchored Notes with Markdown Editor | ✅ Done | Completed in PR #962 (2026-04-13); My Notes list view panel added |
| M04-007 | Bookmarks — Double-Tap & Bookmark List | ✅ Done | completed (2026-04-03) |
| M04-008 | Annotation CRUD API — Auth Service Endpoints | ✅ Done | completed (2026-04-03) |
| M04-009 | User Data API — Gateway Routing for Annotations | ✅ Done | completed (2026-04-03) |
| M04-010 | Reading History — Chapter-Level Progress Tracking | ✅ Done | Completed in PR #962 (2026-04-13); chapter nav read/unread indicators added (Go tests still pending) |
Progress: 10 Done · 0 Partial · 0 To Do (100%)
Issue Dependency Graph
M04-001 ──► M04-002
──► M04-003
──► M04-004
──► M04-005
──► M04-006
──► M04-007
──► M04-008
──► M04-009
──► M04-010
M04-002 ──► M04-003
──► M04-005
M04-003 ──► M04-005
──► M04-006
──► M04-007
──► M04-008
──► M04-009
──► M04-010
M04-004 ──► M04-005
──► M04-006
M04-005 ──► M04-008
M04-006 ──► M04-008
M04-007 ──► M04-008
M04-008 ──► M04-009
Legend:
A ──► Bmeans A blocks B (B is blocked by A)
Document References
| Doc | Contains | Use When Writing Stories For |
|---|---|---|
| MVP.md | Feature scope, tier breakdown, success criteria, budget | Acceptance criteria, scope boundaries |
| TECH-SPEC.md | Architecture, service boundaries, data stores, API catalog | Technical implementation details |
| GOSPELIB-SCHEMAS.md | All 7 schema families, node/edge types, validation rules | Data models, Pydantic models, graph schema |
GOSPELIB-INGEST-SPEC.md | 7-stage pipeline, Cypher templates, batch strategy, CLI | Ingest pipeline stories |
| DESIGN-SYSTEM.md | Visual identity, component catalog, reader modes, tokens | UI component stories |
| DESIGN-SYSTEM.md §§ 13, 21–23 | Footnotes (§13), subscription boundaries (§21), sharing (§22), onboarding (§23) | UX flow stories |
| Deployment & Operations | Environments, K8s, CI/CD, migrations, secrets, DR | Infrastructure and deployment stories |
| REPO-MAP.md | Directory structure, naming conventions, dependency rules | All stories (coding standards) |
| Business | LEGAL.md, POLICY-TERMS.md, executive summary, market research, GTM | Launch readiness, legal/compliance stories |
Sprint Mapping
| Sprint | Weeks | Primary Focus for M04 |
|---|---|---|
| S7 | 15–16 | Auth integration (Clerk), annotations system (highlights, notes, bookmarks) |
S6 (Weeks 13–14) is primarily M03 work (scripture display, reader chrome) but overlaps M04 start. S8 (Weeks 17–18) begins M05 search work.
Sprint Load Warnings
- 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.
Release Info
| Release | Tag | Contains |
|---|---|---|
v0.4.0-alpha | web/v0.4.0-alpha, auth/v0.1.0-alpha | Authentication + annotations |
Tags follow <component>/v<semver> per release-please-config.json.
Relevant Risks
| Risk | Impact | Mitigation |
|---|---|---|
| Clerk/Stripe integration complexity | Delays auth + billing | Start integration in parallel with reader; use sandbox environments early |
| Solo founder velocity | 38-week plan too aggressive | Founding users at Week 22 provide feedback before full scope; cut P3 scope if needed |
Cross-Cutting Concerns
Testing
| Layer | Framework | When | Spec Reference |
|---|---|---|---|
| Go unit (auth service) | go test -race + table-driven | Every PR | TECH-SPEC.md § Testing |
| TypeScript unit (web app) | Vitest | Every PR | TECH-SPEC.md § Testing |
| Component visual | Storybook or playground | P1+ | DESIGN-SYSTEM.md § Governance |
| Visual regression | Playwright + pixelmatch | P1+ (any packages/ui/ or apps/*/src/ change) | DESIGN-SYSTEM.md § Visual Regression CI |
Documentation
| Doc | Update Trigger |
|---|---|
| API OpenAPI specs | Auth service milestone |
| ADRs | Each major technical decision |
CI/CD
| Addition | Phase | Detail |
|---|---|---|
| Nx affected test execution | P1 | Vitest workspace already configured; needs per-project configs |
Dependencies
Upstream (what M04 needs)
| Dependency | Source | Status |
|---|---|---|
| PostgreSQL migration framework | M00: Tech Prep | Must be complete |
| Initial PostgreSQL schemas (annotation + user tables) | M00: Tech Prep | Must be complete |
| Reader shell with verse anchoring | M03: Scripture Reader | Must be complete |
| Gateway with reverse proxy + request ID | M02: Content API | Must be complete (gateway extended with JWT middleware here) |
Downstream (what depends on M04)
| Dependent | Milestone | What It Needs From M04 |
|---|---|---|
| Billing + subscriptions | M10: Monetization | Auth integration (user identity for subscriptions) |
| AI study assistant | M09: AI Study Assistant | Auth (user identity for session limiting) |
| All Scholar features (M06–M09) | P2 milestones | Authenticated user context for feature gating |
Summary
| Metric | Count |
|---|---|
| Total Issues | 10 |
| Sub-Issues | 0 |
| Total Estimate (pts) | 58 |
| Sprints | S7 |
| Dependencies (blocking) | 23 |
| Dependencies (blocked by) | 23 |