Skip to content
DiscipleGo
Staging

Scripture Architecture

Current implementation

DGO uses a canonical Scripture coordinate system based on KJV versification:

BibleBook -> BibleChapter -> BibleVerse

The bundled Zefania KJV XML imports into these tables with php artisan scripture:import-kjv. The importer is idempotent and stores each verse's KJV text, canonical order, and calculated KJV word count. KJV is local canonical and administrative data; it is not a requirement that users read the KJV or that future translations use KJV text.

BiblePericope stores an editable title and an inclusive start/end verse range. Its KJV word count is recalculated from the verses in that range whenever it is saved. Pericopes can be managed in Filament, with selectors searchable by canonical reference or KJV text.

ScriptureReference is a polymorphic inclusive range into the same canonical verses. It carries an optional context role, label, and position. DBS studies are its first consumer, but it does not contain DBS-specific foreign keys or Scripture text.

DBS validation

The Stories of Hope source validates these choices:

  • A series needs ordered studies and reusable default discovery questions.
  • A study may have multiple passages with vision, story, command, additional, or general roles.
  • Roles cannot be fixed columns. Stories of Hope 1 and 3 group passages without consistently labeling all three roles.
  • A passage may span multiple verses, chapters, or eventually books.
  • Additional-study references are first-class passages, not prose hidden in a description.

The development DbsSeeder supplies Stories of Hope and 911 | The Church Circle as temporary bootstrap content. Stories of Hope lessons 1 and 3 do not label Vision, Story, and Command consistently, so their primary passages use the general role rather than inferred editorial roles. Lesson 6 uses the internally consistent Stories of Hope 6 source with Philippians 1:21; the 6 - 2 revision has a summary typo that says Philippians 1:22 while its detailed Vision section still says 1:21. The 911 outline resolves roles for later studies whose individual sheets use an older grouped format. Placeholder RF additional-study entries are omitted.

Translation boundary

Canonical coordinates and content references are independent of display translations. NET, NLT, and NKJV can continue to render through their existing providers. Future translation records should map provider/edition verse identifiers to the canonical spine and explicitly handle versification differences. They should not replace canonical references with provider URLs or free-form passage strings.

Pericopes and reading plans

Canonical DGO pericopes will eventually support plan authoring and generation, including requests such as: "Generate approximately 500 canonical words per day, ending at the nearest sensible pericope."

Reading-plan assignments should later point to canonical ranges through the same reference mechanism. That will make overlap queries possible. A daily reading can then show a badge such as "Also used in Stories of Hope 6." Verse-level highlighting can be added when the reader renders provider responses by verse; it is intentionally not part of V1.

Future lexical layer

The intended lower-level direction is:

Verse -> Word/Token -> Strong's entry

Strong's identifiers and morphology belong below the canonical verse layer. Adding them should not require changing pericopes, DBS studies, or Scripture references.

Future knowledge and content layer

Future content can point to canonical ranges, including:

  • DGO summaries and book/chapter descriptions
  • themes
  • BibleProject resources
  • Jesus Said teachings and training
  • blog posts
  • disciple discussions and comments
  • reading plans
  • commentaries
  • historical and Church Fathers writings

Those associations will need a relationship type such as commentary on, quotation of, reference to, or discussion of. Do not add those abstractions until a real second consumer establishes the required behavior.

Sources and works

Imported works must preserve source identity separately from their Scripture associations. Future source/work records should retain author, title, attribution, license, publication details, and import provenance. Commentary or historical source identity must not be flattened into individual Scripture-reference rows.

Deferred work

V1 does not implement multiple local translations, Bible API ingestion, Strong's data, tokens, morphology, themes, summaries, BibleProject integration, commentaries, Church Fathers, reading-plan generation, automatic reference detection, highlighting, or a knowledge graph.

Architectural principle: Book, chapter, and verse form the canonical spine. Everything else points into that spine through canonical ranges. Translations determine how Scripture is displayed; DGO references determine where Scripture is used.