Phase: P3: Launch
Target: Weeks 29–34
Sprints: S14 (Weeks 29–30, shared with M09), S15 (Weeks 31–32), S16 (Weeks 33–34)
Release: billing/v0.1.0-alpha
Phase Context
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.
ZenHub Configuration
| Field | Value |
|---|
| Milestone | M10: Monetization |
| Due Date | 2026-11-01 |
| Default Pipeline | Product Backlog |
| Primary Epic(s) | Billing & Subscriptions, Come Follow Me, Social Sharing |
Prerequisites
| Prerequisite | Source | Why Needed |
|---|
| M04: Auth integration | P1 | User identity (Clerk + JWT) required for subscriptions — must know who is paying |
| M02: Gateway | P0 | Entitlement middleware extends the gateway's middleware stack |
| M00: PostgreSQL schemas | P0 | gl_subscriptions, gl_stripe_events tables created in M00; billing service adds the API layer |
| M05: Staging environment | P1 | Stripe sandbox testing requires staging deployment |
Epic: Billing & Subscriptions
7 story areas. Stripe subscription flow with Scholar entitlement gating.
Issues — Billing & Subscriptions
| Issue | Title | Status | Notes |
|---|
| M10-001 | Billing Service — Stripe Webhook Handler & Subscription CRUD | 🔶 Partial | plans.yaml exists but webhook.go, subscription service missing |
| M10-002 | PostgreSQL Tables — Subscription & Entitlement API Layer | 🔶 Partial | 2 migration files exist but repository methods missing |
| M10-003 | Stripe Checkout — Web Checkout Flow | ✅ Done | Implemented in PR #961 |
| M10-004 | Entitlement Middleware — Gateway Feature Gating | ✅ Done | Implemented in PR #961 |
| M10-005 | Subscription UI — Plan Comparison, Checkout Trigger & Billing Portal | ✅ Done | Implemented in PR #975 |
| M10-006 | Diamond Indicators — Premium Feature Markers | ✅ Done | Implemented in PR #975 |
| M10-007 | Free Trial — 14-Day Scholar Trial on Signup | ✅ Done | Implemented in PR #975 |
Epic: Come Follow Me
3 story areas. Come Follow Me integration for weekly scripture reading.
Issues — Come Follow Me
| Issue | Title | Status | Notes |
|---|
| M10-008 | CFM Schedule Data — Weekly Reading Plan Mapping | ✅ Done | Implemented in PR #973 |
| M10-009 | CFM Integration — Surface Current Week's Reading on Home | ✅ Done | Implemented in PR #973 |
| M10-010 | Whisper Card — Contextual Insight Card per Reading | ✅ Done | WhisperCard in @gospelib/ui; whisper-engine + whisper-storage + ReaderWhisperCard wrapper in apps/web |
Epic: Social Sharing
2 story areas. Scripture card generation and sharing.
Issues — Social Sharing
| Issue | Title | Status | Notes |
|---|
| M10-011 | Scripture Card Generator — Verse-to-Image Card Creator | ✅ Done | Implemented in PR #973 |
| M10-012 | Share Targets — Image Export, Deep Link & Clipboard | ✅ Done | Implemented in PR #973 |
Progress: 10 Done · 2 Partial · 0 To Do (83%)
Issue Dependency Graph
M00-002 ──► M10-002 ──► M10-001 ──► M10-003 ──► M10-005 ──► M10-006
M00-003 ──► M10-002 │ │ ▲
M00-003 ──► M10-001 │ ▼ │
M04-002 ──► M10-001 ├──► M10-004 ──► M10-005 ──────────────┘
│ ├──► M10-006
│ ▼
├──► M10-007 ──► M11
▼
M10-005 ──► M10-006
M02 ──► M10-008 ──► M10-009 ──► M10-010
M02 ──► M10-009
M02 ──► M10-010
M02 ──► M10-011
M02 ──► M10-012
M04-001 ──► M10-003
M04-003 ──► M10-004
M04-004 ──► M10-011 ──► M10-012
Legend: A ──► B means 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 | Legal compliance, church disclaimer, trademark | CFM integration compliance |
| business/POLICY-TERMS.md | Privacy policy, terms of service drafts | Subscription/billing terms |
Additional Spec References for M10
Sprint Mapping
| Sprint | Weeks | Primary Focus |
|---|
| S14 | 29–30 | AI routes + caching + UI (M09 overlap), beginning of P3 billing work |
| S15 | 31–32 | Billing service (Stripe), entitlement middleware, subscription UI |
| S16 | 33–34 | CFM integration, scripture card sharing, free trial flow |
Sprint Load Warnings
⚠️ 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.
Additional considerations:
- Stripe webhook handling requires idempotency key management and careful error handling — this is where billing bugs cost real money.
- Entitlement middleware is a security-critical path: a bug here means users get free access or paying users get locked out.
Release Info
| Release | Tag | Trigger | Contains |
|---|
v0.10.0-alpha | billing/v0.1.0-alpha | M10 complete | Billing + CFM + sharing |
Tags follow <component>/v<semver> per release-please-config.json.
Note: This is the first release of the billing service (billing/v0.1.0-alpha).
Entitlement Gating: M09→M10
This milestone adds Scholar entitlement gating for features that shipped ungated in earlier milestones:
| Feature | Shipped In | Ungated Until | Gated By |
|---|
| AI study assistant | M09 | M10 billing goes live | Billing & Subscriptions — entitlement middleware |
| Interlinear + lexicon | M06 | M10 billing goes live | Billing & Subscriptions — entitlement middleware |
| JST interlinear | M07 | M10 billing goes live | Billing & Subscriptions — entitlement middleware |
| Constellation view | M08 | M10 billing goes live | Billing & Subscriptions — entitlement middleware |
During the window between each Scholar feature shipping and M10 completion, all authenticated users have Scholar-level access. Once the entitlement middleware is live, only users with an active Scholar subscription (or active free trial) can access these endpoints.
Relevant Risks
| Risk | Impact | Mitigation |
|---|
| Clerk/Stripe integration complexity | Delays auth + billing | Start integration in parallel with reader; use sandbox environments early |
| 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 |
| Missing specification documents | DESIGN-SYSTEM.A1.md doesn't exist (referenced by M10/M11 UX flows) | Write DESIGN-SYSTEM.A1.md before P3 or merge content into DESIGN-SYSTEM.md |
Cross-Cutting Concerns
Testing
Documentation
| Doc | Update Trigger |
|---|
| API OpenAPI specs | Billing service endpoints added |
| ADRs | Stripe integration decisions, entitlement model |
CI/CD
| Addition | Phase | Detail |
|---|
| E2E tests | P3 | Playwright E2E tests activated for critical user journeys (subscription flow) |
| Production CD pipeline | P3 | Release tag → approval gate → deploy (preparation for M11) |
Dependencies
Upstream (what M10 needs)
| Dependency | Milestone | Detail |
|---|
| Auth integration (Clerk + JWT) | M04 | User identity required for subscription management |
| Gateway with middleware stack | M02 | Entitlement middleware extends the existing gateway middleware |
| PostgreSQL schemas (billing tables) | M00 | gl_subscriptions, gl_stripe_events tables must exist |
| Staging environment | M05 | Stripe sandbox testing on staging |
| AI service deployed | M09 | Entitlement gating wraps AI endpoints |
| Scholar features deployed | M06–M09 | All Scholar features must exist to be gated |
Downstream (what depends on M10)
| Dependent | Milestone | Detail |
|---|
| M11 production deployment | M11 | Billing must be operational before production launch |
| M11 onboarding flow | M11 | Onboarding references subscription plans and trial |
| M11 analytics | M11 | Subscription conversion tracking as leading indicator |
Summary
| Metric | Count |
|---|
| Total Issues | 12 |
| Sub-Issues | 0 |
| Total Estimate (pts) | 63 |
| Sprints | S14–S16 |
| Dependencies (blocking) | 13 |
| Dependencies (blocked by) | 24 |