Skip to main content

M08: Knowledge Graph — v0.8.0-alpha

Phase: P2: Scholar Features Target: Weeks 25–32 Sprints: S12 (Weeks 25–26), S13 (Weeks 27–28) Release: web/v0.8.0-alpha

Phase Context​

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."

ZenHub Configuration​

FieldValue
MilestoneM08: Knowledge Graph
Due Date2026-10-18
Default PipelineProduct Backlog
Primary Epic(s)Knowledge Graph

Prerequisites​

PrerequisiteSourceWhy Needed
M01: Data Pipeline completeP0Cross-ref and topical guide edges must be ingested into FalkorDB
M02: Content API servingP0Graph query API extends the content service
M03: Scripture ReaderP1Constellation view launches from the reader; pinch-to-zoom interaction
M05: Staging environmentP1Founding users are already using staging during P2

Epic: Knowledge Graph​

8 story areas. Interactive knowledge graph visualization for scripture cross-references and topical links.

Story AreaScopeSpec Reference
Graph data layerEnsure cross-refs + topical guide edges ingested for NTGOSPELIB-SCHEMAS.md § Edge Types
Graph query APIGET /graph/connections/\{nodeId\} — neighbors with typed edgesTECH-SPEC.md § API Endpoints
Constellation viewInteractive node graph — passages, topics, cross-referencesMVP.md § Priority #2, DESIGN-SYSTEM.md § Constellation
Node renderingPassage nodes, topic nodes; solid (cross-ref) vs dashed (topical) edgesMVP.md § Priority #2
Zoom interactionPinch-to-zoom-out from reader to constellationMVP.md § Priority #2
List view toggleAccessible alternative to graph visualizationMVP.md § Priority #2
ConnectionCardTap node → card with passage preview, link to navigateDESIGN-SYSTEM.md § P3 Components
Graph-specific iconstemple-link, constellation node type shapes (rounded square, circle, hexagon, folded-corner, pentagon)DESIGN-SYSTEM.md § Bespoke GospeLib Icons, DESIGN-SYSTEM.md § Constellation View

Document References​

DocContainsUse When Writing Stories For
MVP.mdFeature scope, tier breakdown, success criteria, budgetAcceptance criteria, scope boundaries
TECH-SPEC.mdArchitecture, service boundaries, data stores, API catalogTechnical implementation details
GOSPELIB-SCHEMAS.mdAll 7 schema families, node/edge types, validation rulesData models, Pydantic models, graph schema
GOSPELIB-INGEST-SPEC.md7-stage pipeline, Cypher templates, batch strategy, CLIIngest pipeline stories
DESIGN-SYSTEM.mdVisual identity, component catalog, reader modes, tokensUI component stories
DESIGN-SYSTEM.md §§ 13, 21–23Footnotes (§13), subscription boundaries (§21), sharing (§22), onboarding (§23)UX flow stories
Deployment & OperationsEnvironments, K8s, CI/CD, migrations, secrets, DRInfrastructure and deployment stories
REPO-MAP.mdDirectory structure, naming conventions, dependency rulesAll stories (coding standards)

Additional Spec References for M08​

Sprint Mapping​

SprintWeeksPrimary Focus
S1225–26Constellation view — graph query API, node rendering, zoom
S1327–28Constellation polish (list view toggle), AI LLM client + prompts (M09 overlap)

Note: S13 is shared with M09 (AI Study Assistant). The first half of S13 finishes constellation polish; the second half begins AI work.

Sprint Load Warnings​

No specific sprint load warnings from the plan apply to S12 or S13. However:

  • S12–S13 overlap with the period where founding users are active (entered ~Week 22). Bug reports and feedback from founding users may consume capacity.
  • Constellation view performance is a flagged risk (see Risk Registry below). Budget time for performance tuning.

Release Info​

ReleaseTagTriggerContains
v0.8.0-alphaweb/v0.8.0-alphaM08 completeConstellation view (Scholar)

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

Relevant Risks​

RiskImpactMitigation
Constellation view performanceGraph viz too slow for complex passagesStart with NT-only subset per MVP scope; lazy-load nodes
FalkorDB performance at corpus scaleSlow content API, bad UXBenchmark after M01; index tuning; caching layer in M02
Solo founder velocity38-week plan too aggressiveFounding users at Week 22 provide feedback before full scope; cut P3 scope if needed

Cross-Cutting Concerns​

Testing​

LayerFrameworkWhenSpec Reference
Python unit/integrationpytest + testcontainersEvery PRGOSPELIB-INGEST-SPEC.md § Testing
TypeScript unitVitestEvery PRTECH-SPEC.md § Testing
Component visualStorybook or playgroundP1+DESIGN-SYSTEM.md § Governance
Visual regressionPlaywright + pixelmatchP1+ (any packages/ui/ or apps/*/src/ change)DESIGN-SYSTEM.md § Visual Regression CI

Documentation​

DocUpdate Trigger
API OpenAPI specsGraph query endpoint added
ADRsAny major technical decision (e.g., graph viz library choice)

CI/CD​

Staging CD pipeline should be live (activated in M05). Visual regression screenshots should be running in CI.

Dependencies​

Upstream (what M08 needs)​

DependencyMilestoneDetail
Cross-ref + topical guide edges in FalkorDBM01Graph data layer requires ingested edge data
Content service with graph routesM02GET /graph/connections/\{nodeId\} builds on content service
Reader shell with navigationM03Constellation view is a reader mode (pinch-to-zoom entry point)
Staging environmentM05Founding users testing during this phase

Downstream (what depends on M08)​

DependentMilestoneDetail
M10 entitlement gatingM10Scholar entitlement middleware gates constellation view
M11 polish and performanceM11Performance audit covers constellation view

Issues​

IssueTitleStatusNotes
M08-001Verify Cross-Reference and Topical Guide Edges Ingested for NT Corpus❌ To Donot implemented
M08-002Implement Graph Query API — GET /connections/{nodeId}✅ Doneconnections.py with GET /connections/{node_id}
M08-003Build ConstellationView — Interactive Force-Directed Graph Visualization❌ To Donot implemented
M08-004Implement GraphNode Component — Typed Node Rendering❌ To Donot implemented
M08-005Implement Zoom Interaction — Pinch-to-Zoom Between Reader and Constellation❌ To Donot implemented
M08-006Implement List View Toggle — Accessible Alternative to Graph❌ To Donot implemented
M08-007Build ConnectionCard — Node Tap Preview with Navigation❌ To Donot implemented
M08-008Create Graph-Specific Bespoke Icons❌ To Donot implemented

Progress: 1 Done · 0 Partial · 7 To Do (13%)

Epic: Knowledge Graph​

Issue Dependency Graph​

M08-001 ──► M08-002 ──► M08-003 ──► M08-004 ──► M08-007
  └──► M08-003    │         ├──► M08-005 ──────────┘
                  │         └──► M08-006
                  └──► M08-006
M08-008 ──► M08-004
       └──► M08-006

Cross-milestone: M01 ──► M08-001, M02-001 ──► M08-002, M03 ──► M08-005

Legend: A ──► B means A blocks B (B is blocked by A)

Summary​

MetricCount
Total Issues8
Sub-Issues0
Total Estimate (pts)52
SprintsS12–S13
Dependencies (blocking)12
Dependencies (blocked by)10