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. |
| Journey passage | A Passage an editor made for one journey chapter (Passage.journey_only, CSL-490). It belongs to that chapter: no other chapter can use it, and it never appears on Home, theme pages, related quotes, the passage list or the CMS Passages list. Its detail endpoint still serves it. The rest of the library is the main collection. |
| 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 [[Bookmark]] and [[Reflection]] are built the same way (ADR-0008 #3). |
| Journey | A guided course through Lewis's work: an editor-curated, ordered set of chapters around a primary theme, with a description that pitches it, optional intro and outro pages that open and close it, and one practice the reader is asked to carry out of it. (It used to carry a central_question; that was removed.) 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), its own description, pause_line, reveal_line. The practice sits on the Journey, not the chapter: one practice for the whole course. 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. A chapter's passage is its own [[Journey passage]]; a writing or an article can sit in several chapters. 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_description). 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. |
| Home | The app's landing surface and the single CMS settings record (Home, one row) that assembles it: the daily quote queue, Featured Journeys, Theme of the Week, What's New pins, Featured Books, and the automatic Further Reading shelf. Served as one endpoint per section, not one aggregate call. |
| Tag category | The container a Tag belongs to (TagCategory), e.g. Motif or Life stage. A tag name is unique inside its category, and deleting a category deletes its tags. |
| Tag | An editor-defined value inside one Tag category (Tag), applied to pieces to drive the tag-overlap graph. Distinct from a Theme, which is a world a reader enters rather than a label. |
| Practice | The one small thing a Journey asks the reader to carry out of the course (Journey.practice). It belongs to the journey, not to a chapter. |
| Support pages | The four public HTML pages the app and the stores link to (About, Privacy Policy, Terms of Service, Support), edited on one CMS settings screen (SupportInfoSettings) and served at the site root, outside /api/. |
| 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. |
| Bookmark | A reader saving a content piece to return to — the Bookmarked list on Profile. One per reader per canonical piece (Passage, Writing or Article), carrying nothing but the fact that it exists: no note, no folder, no reader-set order. Saving and unsaving are both safe to repeat. A bookmark belongs to the piece, not the route, so saving inside a Journey saves the piece underneath. It survives its piece being unpublished (shown unavailable) but is removed if the piece is deleted — the opposite of a [[Reflection]], because a bookmark is a pointer rather than the reader's own words. Whether a whole Journey can be bookmarked is open with design. |
| Entitlement | The backend's record that a reader holds a paid tier. One ReaderEntitlement row per reader per RevenueCat entitlement identifier (journey_premium today), mirrored from the store. Access is derived from expires_at, never a stored flag, so a second tier is a new row, not a schema change. The reader-facing status (active / cancelled / billing_issue / expired) is computed on read. |
| Journey Premium | The first paid tier: the full Journey library and its narration, sold monthly and annually with no trial (every reader instead gets one free Journey of their choice). Prices live in RevenueCat's product catalogue, not here. A planned second tier, Audiobook Premium, is not built. |
| RevenueCat | The store abstraction over Apple and Google in-app purchase. The source of truth for subscription state; the backend mirrors it into ReaderEntitlement and never takes a payment. See ADR-0013. |
| App user ID | The identity RevenueCat knows a reader by, which is the reader's Firebase UID. It doubles as the customer id RevenueCat's v2 API accepts, so store state and app account line up with no mapping table. |
| Reflection | One reader's private written answer to a content piece's reflection_prompt. One per reader per piece, kept as written — MVP has no edit, no delete and no second entry (CSL-192). It is nobody's reading material but its author's: not moderated, not shown to other readers, and not browsable by editors in the CMS. Returns in Profile as the read-only "Reflected" list. An earlier design made this a moderated community note surfaced as ambient presence ("14 have sat with this"); that idea is superseded, and community reflections are not in V1. |
| 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. The prompt is also what makes a piece reflectable: leave it empty and the piece cannot be reflected on at all. |
| 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. |
| Audio Studio | The CMS screen where narration is produced: one screen per target, reached from the target's list row or edit header. Drafts cue scripts (Bedrock), generates audio (ElevenLabs), and saves approved assets. Distinct from Voice Studio, the standalone voice-lab proof of concept. |
| Target (audio) | The CMS object an Audio Studio screen narrates — a Passage, Writing, Article, JourneyChapter, or Journey. |
| Section (audio) | One narratable field of a target (a passage's quote, a chapter's pause line). CMS-internal vocabulary: the API keys audio by field name and never says "section". |
| Take (audio) | A candidate recording an editor auditions in the studio (AudioTake). Studio-only; never served. |
| Asset (audio) | The approved narration of one field (AudioAsset) — the only audio the app serves. One per (target, field, block); exists only once approved. |