M02: Content API — `v0.2.0-alpha`

Version tag: content/v0.2.0-alpha, gateway/v0.2.0-alpha Phase: P0: Foundation Target: Weeks 7–10 (overlaps M01 tail) Sprints: S3 (tail), S4

Phase Context

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.

ZenHub Configuration

Field	Value
Milestone	M02: Content API
Due Date	2026-05-17
Default Pipeline	Product Backlog
Primary Epic(s)	Content Service API, Gateway Core, Shared Types & SDK

Prerequisites

M01: Data Pipeline — FalkorDB client + Stage 3 (scripture text) must complete. Content service queries require ingested data.

Epic: Content Service API

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

Issues

ID	Title	Status	Notes
M02-001	Implement GraphClient with FalkorDB Connection Pool and Redis Query Cache	✅ Done	implemented in PR #901 (2026-04-03)
M02-002	Define Pydantic Response Models Matching API Envelope	✅ Done	implemented in PR #901 (2026-04-03)
M02-003	Implement Passage Routes	✅ Done	implemented in PR #901 (2026-04-03)
M02-004	Implement Lexicon Routes	✅ Done	implemented in PR #901 (2026-04-03)
M02-005	Implement Topic Routes	✅ Done	implemented in PR #901 (2026-04-03)
M02-006	Implement Dictionary Routes	✅ Done	implemented in PR #901 (2026-04-03)
M02-007	Implement Graph Connection Routes	✅ Done	implemented in PR #901 (2026-04-03)
M02-008	Implement Redis Caching Layer	✅ Done	implemented in PR #901 (2026-04-03)
M02-009	Configure FastAPI OpenAPI Spec Generation	✅ Done	implemented in PR #901 (2026-04-03)
M02-010	Content Service Test Suite	✅ Done	implemented in PR #901 (2026-04-03)
M02-011	Implement Reverse Proxy to Content Service	✅ Done	implemented in PR #901 (2026-04-03)
M02-012	Implement Request ID Middleware	✅ Done	implemented in PR #901 (2026-04-03)
M02-013	Implement CORS Middleware	✅ Done	implemented in PR #901 (2026-04-03)
M02-014	Implement Rate Limiting Middleware	✅ Done	implemented in PR #901 (2026-04-03)
M02-015	Implement Health Check Aggregation	✅ Done	implemented in PR #901 (2026-04-03)
M02-016	Gateway Test Suite	✅ Done	implemented in PR #901 (2026-04-03)
M02-017	Implement `@gospelib/types` — Scripture and API Types	✅ Done	implemented in PR #901 (2026-04-03)
M02-018	Implement `@gospelib/sdk` — Client SDK for Content API	✅ Done	implemented in PR #901 (2026-04-03)
M02-019	Implement `@gospelib/config` — Zod Environment Schemas	✅ Done	implemented in PR #901 (2026-04-03)

Progress: 19 Done · 0 Partial · 0 To Do (100%) — All issues completed and verified present in codebase (2026-04-03)

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

Issues

(Issues for this epic are numbered as part of the main M02 issue list above)

Epic: Shared Types & SDK

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

Issues

(Issues for this epic are numbered as part of the main M02 issue list above)

Issue Dependency Graph

Content Service Chain:

M02-001 ──► M02-003 ──► M02-009 ──► M02-018
M02-001 ──► M02-004 ──► M02-009
M02-001 ──► M02-005 ──► M02-009
M02-001 ──► M02-006 ──► M02-009
M02-001 ──► M02-007 ──► M02-009
M02-001 ──► M02-008
M02-002 ──► M02-003, M02-004, M02-005, M02-006, M02-007
M02-002 ──► M02-017 ──► M02-018
M02-001..M02-007 ──► M02-010

Gateway Chain:

M02-003 ──► M02-011 ──► M02-015
M02-012 ──► M02-011
M02-011, M02-012, M02-013, M02-014, M02-015 ──► M02-016

Independent:

M02-019 (no internal blockers)

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
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
S3 (tail)	7–8	M01 pipeline completion overlaps — M02 work begins as FalkorDB client and Stage 3 land
S4	9–10	Content service (GraphClient, passage routes), gateway proxy

Sprint Load Warnings

No explicit load warnings for S3–S4. S4 is focused on content service + gateway — a clean sprint boundary.

Release Info

Release	Tag	Contains
`v0.2.0-alpha`	`content/v0.2.0-alpha`	Content API serving passages, lexicon, topics, dictionary, graph queries
`v0.2.0-alpha`	`gateway/v0.2.0-alpha`	Gateway proxying to content service with request ID, CORS, rate limiting

Relevant Risks

Risk	Impact	Mitigation
FalkorDB performance at corpus scale	Slow content API, bad UX	Benchmark after M01; index tuning; caching layer in M02
Ingest pipeline data quality issues	Content API returns bad data	Corpus validation epic in P0; dry-run + schema enforcement

Cross-Cutting Concerns

Testing

Layer	Framework	When	Spec Reference
Python unit/integration	pytest + testcontainers	Every PR	TECH-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

Documentation

Doc	Update Trigger
Local Dev Setup	M02 complete — document full stack
Adding a Service	M02 complete — codify established pattern
API OpenAPI specs	Each service milestone
ADRs	Each major technical decision

CI/CD

Addition	Detail
Nx affected test execution	Vitest workspace already configured; needs per-project configs

Dependencies

Upstream (what M02 needs)

M00: Tech Prep — response envelope utilities, structured logging, health check contract, error code catalog, request ID propagation, OpenAPI spec workflow
M01: Data Pipeline — FalkorDB client + Stage 3 (ingested scripture text data)

Downstream (what depends on M02)

M03: Scripture Reader — depends on content API serving passage data; @gospelib/sdk wired to content endpoints
M05: Search & Staging — search API extends content service
M08: Knowledge Graph — constellation view queries graph connections API built here
M09: AI Study Assistant — AI needs passage context from content API
M10: Monetization — entitlement middleware extends gateway built here

Summary

Metric	Count
Total Issues	19
Sub-Issues	7
Total Estimate (pts)	86
Sprints	S3–S4
Dependencies (blocking)	32
Dependencies (blocked by)	33

Phase Context​

ZenHub Configuration​

Prerequisites​

Epic: Content Service API​

Issues​

Epic: Gateway Core​

Issues​

Epic: Shared Types & SDK​

Issues​

Issue Dependency Graph​

Document References​

Sprint Mapping​

Sprint Load Warnings​

Release Info​

Relevant Risks​

Cross-Cutting Concerns​

Testing​

Documentation​

CI/CD​

Dependencies​

Upstream (what M02 needs)​

Downstream (what depends on M02)​

Summary​

Phase Context

ZenHub Configuration

Prerequisites

Epic: Content Service API

Issues

Epic: Gateway Core

Issues

Epic: Shared Types & SDK

Issues

Issue Dependency Graph

Document References

Sprint Mapping

Sprint Load Warnings

Release Info

Relevant Risks

Cross-Cutting Concerns

Testing

Documentation

CI/CD

Dependencies

Upstream (what M02 needs)

Downstream (what depends on M02)

Summary