Data Model Plan¶

Draft 3 · 2026-06-30 · Reconciled with Lina's CMS Content Model + IA stand-up refinements

Settled schema has been promoted to cms-architecture.md — the canonical field-level reference. This document retains the design rationale and reconciliation narrative.

This is a reading app for C.S. Lewis's body of work — passages, letters, essays, podcasts, and editorial content — where every piece is connected to every other through shared themes. The core promise is a "Wikipedia rabbit hole" feeling: start with one passage and the app surfaces surprising connections across the whole corpus. That mechanic, plus a curated alternative, drives every structural decision below.

Two navigation modes sit on top of the same content.

• Explore is open-world graph traversal — you follow computed tag-overlap edges from item to item.
• Journeys are editorially curated paths — a human picks specific pieces, orders them into chapters, and frames them with reflection prompts. On top of both, users accumulate a personal
• Soul Map (saves, progress, completions) that persists across sessions — which is why accounts are in V1 despite there being no paywall.

Three layers, one content spine¶

The model splits cleanly into three layers. The Content Library and Editorial Structure come from Lina's CMS model — this is what editors author. The App layer (graph engine, user data, community) is what the backend computes and stores on top, and is not part of the CMS authoring surface. The bridge between them is a polymorphic Content Item — any of Passage / Letter / Essay / Podcast — which is what Journeys reference, what the graph traverses, and what users save.

Legend: 🔵 Content Library · 🩵 Worlds & taxonomy · 🟣 Editorial structure · 🩷 App layer (not in CMS) · 🔮 Content Item bridge

graph TB
  subgraph LIB["Content Library (CMS-authored)"]
    direction LR
    Passage["<b>Passage</b><br/><i>Lewis excerpt · audio</i>"]
    Letter["<b>Letter</b><br/><i>Lewis, held in full</i>"]
    Essay["<b>Essay</b><br/><i>contributor · Substack</i>"]
    Podcast["<b>Podcast</b><br/><i>external embed</i>"]
    Work["<b>Work</b><br/><i>book proxy + buy link</i>"]
    Author["<b>Author</b>"]
    Prompt["<b>Prompt</b>"]
  end

  subgraph WORLDS["Worlds & Taxonomy"]
    Theme["<b>Theme</b><br/><i>= navigable world / portal</i>"]
    PortalImg["<b>Portal Image</b>"]
    Tags["<b>Tags</b><br/><i>faceted — TBD</i>"]
  end

  subgraph EDIT["Editorial Structure"]
    Journey["<b>Journey</b>"]
    Chapter["<b>Chapter</b>"]
    Blocks["<b>Content Blocks</b><br/><i>Theme page + Home</i>"]
  end

  subgraph APP["App Layer (computed / user — not CMS)"]
    Graph["<b>Tag-Overlap Graph</b><br/><i>computed edges</i>"]
    User["<b>User</b>"]
    Save["<b>Save</b> · Soul Map"]
    Reflection["<b>Reflection</b><br/><i>community, moderated</i>"]
    DailyDrop["<b>DailyDrop</b>"]
  end

  CI(["<b>Content Item</b><br/>Passage | Letter | Essay | Podcast"])

  Passage --> CI
  Letter --> CI
  Essay --> CI
  Podcast --> CI

  Passage -->|source| Work
  Passage -->|source| Letter
  Passage -->|source| Essay
  Essay --> Author
  Passage -.-> Prompt
  Letter -.-> Prompt
  Essay -.-> Prompt
  Podcast -.-> Prompt

  CI -->|tagged| Tags
  CI -->|tagged| Theme
  Theme --> PortalImg
  Theme --> Blocks
  Journey -->|belongs to| Theme
  Journey --> Chapter
  Chapter -->|references| CI

  CI --> Graph
  Save --> CI
  User --> Save
  Reflection --> CI
  DailyDrop --> CI

  classDef lib fill:#EFF6FF,stroke:#3B82F6,color:#1F2937;
  classDef world fill:#ECFEFF,stroke:#06B6D4,color:#1F2937;
  classDef edit fill:#F5F3FF,stroke:#8B5CF6,color:#1F2937;
  classDef app fill:#FDF2F8,stroke:#EC4899,color:#1F2937;
  classDef bridge fill:#EEF2FF,stroke:#6366F1,color:#1F2937;

  class Passage,Letter,Essay,Podcast,Work,Author,Prompt lib;
  class Theme,PortalImg,Tags world;
  class Journey,Chapter,Blocks edit;
  class Graph,User,Save,Reflection,DailyDrop app;
  class CI bridge;

Content Library¶

Lina's model keeps the content types separate rather than collapsing them into one unified record, and the reasoning is field-level and concrete. A Passage body is plain text because word-by-word audio sync needs a clean string — rich text would break streaming. A Letter carries a Recipient and an Original Date and is read, not listened to. An Essay is not Lewis — it has a named contributor, a Substack source, and an author-driven card. These differences don't survive a single unified table, so they stay distinct. (My earlier draft unified them; see the open decision at the end for how the graph layer still gets uniform traversal across separate types.)

Everything in the library is created once and referenced many times. Each piece optionally carries a Prompt and is classified by Tags and Themes. The source chain is the key relational bit: a Passage is always an excerpt, so it links to a source — either a Work (a book we don't hold in full, a proxy that routes to purchase) or directly to a Letter/Essay we do hold in full (the piece is the destination). Never both.

Worlds & Taxonomy¶

This is the biggest terminology correction from the reconciliation. The navigable "world" — the portal — is the Theme, not the Journey. Editors create Theme worlds (Grief, Hope, Courage, Narnia), each with its own landing page, bespoke colour palette, and portal imagery. Content pieces and Journeys are assigned to Themes via multi-select, and a single Journey can live in several Theme worlds at once. (My earlier draft put "portal" on the Journey; that was wrong — Journey is a path inside the worlds.)

Editorial Structure¶

Journeys are the curated counterpart to Explore. A Journey holds no content of its own — it's an ordered sequence of Chapters, and each Chapter references existing Library pieces. A Chapter has one Primary Reading (the only required content field) anchored by optional opening and supporting pieces. Because the Chapter is just a positioned reference, the same piece can appear in many Journeys with different framing — and the Chapter's Prompt Override lets it carry a different reflection question each time.

Journey → Chapter → Content Item¶

graph LR
  J["<b>Journey</b><br/>opening + final question<br/>belongs to Theme(s)"]
  C1["<b>Chapter 1</b><br/>opening question<br/>prompt override"]
  C2["<b>Chapter N</b>"]
  OP["opening passage"]
  PR["<b>primary reading</b> (req)"]
  SC["supporting content ×N"]

  J --> C1
  J --> C2
  C1 --> OP
  C1 --> PR
  C1 --> SC

  classDef edit fill:#F5F3FF,stroke:#8B5CF6,color:#1F2937;
  classDef bridge fill:#EEF2FF,stroke:#6366F1,color:#1F2937;
  class J,C1,C2 edit;
  class OP,PR,SC bridge;

Tag-Overlap Graph (app layer — not in CMS model)¶

This layer is not in Lina's CMS doc, because it's runtime, not authoring — but it's the load-bearing mechanic for Explore and every "related content" surface. The graph's nodes are Content Items (any Passage / Letter / Essay / Podcast); its edges are computed, not stored, from the shared Tags + Themes the CMS attaches. This is exactly where keeping the content types separate (CMS view) and giving them a uniform traversal interface (app view) coexist — the graph reads through the shared tag surface and doesn't care which underlying collection a node came from.

Overlap scoring produces two flavours of edge: further_in (same thematic thread, deeper) and connects_across (same theme in a different work or format). Hand-curation was rejected — it doesn't scale to Lewis's corpus and kills the serendipity. Tagging is a build-time pipeline: AI drafts at ingest, editors QA before publish, graph recomputes on publish. No runtime AI in the content API path.

graph LR
  CI(["<b>Content Item</b><br/>Passage | Letter | Essay | Podcast"])
  TH["Themes <i>(M:N)</i>"]
  TG["Tags <i>(faceted, TBD)</i>"]
  OV["<b>Overlap Score</b><br/>pairwise"]
  FI["<b>further_in[]</b><br/>same thread, deeper"]
  CA["<b>connects_across[]</b><br/>same theme, diff. work"]

  CI --> TH
  CI --> TG
  TH --> OV
  TG --> OV
  OV --> FI
  OV --> CA

  classDef bridge fill:#EEF2FF,stroke:#6366F1,color:#1F2937;
  classDef world fill:#ECFEFF,stroke:#06B6D4,color:#1F2937;
  classDef app fill:#FDF2F8,stroke:#EC4899,color:#1F2937;
  classDef lib fill:#EFF6FF,stroke:#3B82F6,color:#1F2937;
  class CI bridge;
  class TH,TG world;
  class OV app;
  class FI,CA lib;

Candidate tag facets (input to the deferred Tags session): motif (cross-work, powers surprise jumps) · life-stage (youth → grief) · register (bedtime / morning / anytime) · tone-depth (meaning / theological). Edge weighting across facets is TBD and determines the further_in vs connects_across split.

User Data & Soul Map (app layer — not in CMS model)¶

Also outside Lina's CMS doc, because it's user state, not authored content. The Soul Map is the user's personal record of what they've read and reflected on — and the reason accounts exist in V1. The app is fully usable as a guest; you make an account specifically to keep your Soul Map. No paywall, no content gating in V1.

Soul Map isn't its own table — it's a virtual aggregate of Save (the reflection moment: which item, which prompt was shown, the user's response), JourneyProgress (resume point per active Journey), and JourneyCompletion. Save snapshots the prompt text rather than referencing it by ID, because a Chapter can override a piece's default Prompt — the Save must record what the user actually saw. Reflection is the moderated community layer ("publish, not post") surfaced as ambient presence, not a comment thread. Account deletion is mandatory (App Store policy), done as soft delete.

graph TB
  U["<b>User</b><br/>email/password · soft delete"]
  S["<b>Saves</b><br/>item + prompt snapshot + response"]
  JP["<b>JourneyProgress</b><br/>current chapter + resume item"]
  JC["<b>JourneyCompletion</b>"]
  U --> S
  U --> JP
  U --> JC
  classDef app fill:#FDF2F8,stroke:#EC4899,color:#1F2937;
  class U,S,JP,JC app;

The open decision: separate types vs unified traversal¶

Key design decisions¶

Open blockers¶