Glossary¶
Canonical terms for cs-lewis-backend. Use these consistently across code, docs, and conversation.
| Term | Definition |
|---|---|
| Content piece | A single unit of content. Exists once; referenced from many places. The same piece reached via two routes is still the same piece. |
| Passage | The atom: a short, standalone, consumable Lewis passage — completable on its own (read/listen/reflect/wander) without opening its source. The canonical traversal starting point and primary interaction unit. Rich-text body (verbatim canon prose); its own content type (not merged into the readable-unit model below). Formerly called Excerpt (renamed in code + API, CSL-141); product/design surfaces also call it Quote. Use Passage in code. |
| Quote | Product/design synonym for a Passage (e.g. Home's "Today's Quote" hero). Same thing as Passage. Use Passage in code. |
| Readable unit | The full-text reading types — Letter, Essay, Chapter — one model (Writing) differentiated by a kind field, with kind-specific fields optional + validated per kind. Shared spine: body, themes, tags, reflection_prompt, optional audio, single source → Work. |
| Writing | The code model implementing Readable unit (kind = letter / essay / chapter). A Wagtail snippet with draft/live + revisions. Use Writing in code; kind names in product copy. |
| Letter | A full Lewis letter (Writing with kind=letter), held in full and readable in-app. Real correspondence — carries recipient and original date. Rich-text body. Audio is on the roadmap for all readable types (MVP populates only Passage audio). |
| Essay | A full essay Lewis wrote (Canon; Writing with kind=essay), readable in-app. Author = Lewis. Contemporary team-written pieces are Articles, not Essays. |
| Article | The atom's editorial counterpart: a contemporary, team-written piece (not Lewis) — e.g. Substack-sourced commentary with a named contributor. Distinct from Essay (Lewis Canon). The canonical code name for what product/spec language calls an Editorial piece; schema planned, not yet modelled. Its own content type. |
| Editorial piece | Product/spec synonym for an Article (the code model). Same thing. Use Article in code. |
| Podcast | Longer-form external audio — embedded, not CMS-hosted. Separate shape from the readable types. Phase 1 is a schema stub only. |
| Work | The single source a readable unit / Passage came from (our Book), reached via a single source FK — editors pick one main edition (not a many-edition M2M). Proxy for books not held in full; drives the source ladder to purchase. Source reference only in V1 (no e-reader): cover, synopsis, publication date, future buy link. |
| Content Item | Polymorphic bridge across Passage / Writing (letter, essay, chapter) / Podcast — the design-era abstraction for uniform traversal over separate storage types. Not built as such: a JourneyChapter references exactly one Passage, Writing or Article through three nullable FKs with a database check, and the same nullable-FK pattern is planned for bookmarks and reflections (ADR-0008 #3). |
| Journey | A guided course through Lewis's work: an editor-curated, ordered set of chapters built around one central question. Belongs to one or more Themes. A user can have multiple journeys in progress simultaneously. |
| Portal | The same object as a Journey, viewed as a doorway — the entry animation. Don't model as two things. |
| JourneyChapter | One chapter of a Journey — one content piece (Passage xor Writing xor Article) plus the editorial framing around it for this position in this journey: opening_question, intro_pages (the lead-in, split into pages the reader moves through), pause_line, practice, reveal_line. A chapter is a piece, not a container of pieces, and holds no taxonomy of its own: its reflection_prompt, themes and primary_theme all read through to the piece, so a piece is tagged once and every journey using it inherits that. The Journey carries the taxonomy for the course as a whole. Use JourneyChapter in code — never bare "Chapter", which collides with the Book-Chapter sense below. |
| Chapter | Two senses, disambiguated by context. (1) Journey chapter: the product/API/FE word for a JourneyChapter — the API field is chapter. (2) Book chapter: the readable unit (Writing with kind=chapter) with its own body + source → Work. Both ship. In backend code always write JourneyChapter for the first sense; bare chapter means the second. |
| Emblem | The single image standing for a Journey, held on the Journey alongside the words shown with it (emblem_title, emblem_line). It is the journey-card artwork and the collectible: the FE reveals it progressively as chapters complete ("the journey becomes a little clearer") and the reader collects it at the end. One image, not two — the blur is a front-end effect, not a second asset. Replaces the earlier per-chapter keystone card, and the icon field the design drafts named. Feeds the future Soul Map. |
| Theme | A navigable world / mood filter with bespoke portal imagery and colour scheme. A global controlled vocabulary spanning every content type (not per-book), created/refreshed via sync_themes from the Figma design library (CSL-170). Set of 14: Temptation, Love, Imagination, Humility, Reason, Morality, Wonder, Grief, Myth, Growth, Joy, Faith, Friendship, Courage. Each carries a palette color (accent/arch/background + opacity tints), a per-theme portal_icon, and a per-palette background wash. Content pieces and Journeys are assigned Themes by multi-select — a piece may sit in several worlds. Switching a Theme recolours the whole UI. |
| Explore | The open-world browse surface (graph traversal); search lives inside it. |
| Dive deeper | Tag-graph traversal surface within Explore or a reading screen. |
| Front door | Narnia — the deliberate entry wedge for newcomers. |
| Soul Map | The user's personal record of what they've read and reflected on — the visual representation of bookmarks + reflections on Profile. Visualization deferred out of V1; inputs (accounts + reflection storage) ship in V1 so data accrues for Phase 2. |
| Source ladder | Passage → chapter audio → bookstore purchase handoff. Narnia skips the chapter rung (HarperCollins rights). A passage's source is always shown. |
| Thought provoker | Pre-reading prompt/lens shared by every content piece (e.g. "What if loneliness was a dog?"). Scopes to the chapter when the piece sits in a Journey, otherwise to the standalone piece. Earlier called "AI interpretation / lens." |
| Deeper meaning | Longer AI-assisted interpretive annotation (CMS text block); needs editorial QA. Likely deprioritized in V1 — client has no editorial team to QA it. |
| Reflection | User-generated community note attached to a content piece. Moderated ("publish, not post" — never appears as raw user input). Surfaced as ambient presence ("14 have sat with this"), not a comment thread. |
| Prompt | A standalone reflection question. Not built as a model: each piece carries its own reflection_prompt, and a JourneyChapter reads that through rather than overriding it — a piece asks the same thing wherever it is read. |
| Tag-overlap graph | Computed edges between content items based on shared tags. Deterministic, build-time. Powers Explore and related-content surfaces. No stored edges (except editor hero-pins). |
| Provenance | Tag axis: evergreen (Lewis's existing corpus) vs editorial (produced into the CMS — essays, commissioned work). |
| Motif | Fine-grained tag that cuts across works; powers surprise jumps between pieces. |
| Life stage | Single tag per piece (youth → grief). |
| Register | Tag axis: bedtime / morning / anytime. |
| Tone depth | Tag axis: meaning (default) / theological (opt-in). |
| Daily Drop | Scheduled "today's passage" pointer. Schema can land at MVP; scheduling UI is Phase 2. |