Data model¶

Every table this project owns, what it holds, how it links, and what the database refuses to store. The tables below are generated from the models, so this page cannot fall behind a migration.

Where the rest lives

Columns, types and help text are in src/data/models/, one module per area, and each model carries a docstring explaining itself. The reasoning behind the shape is in the ADRs. The request path that reads these tables is in Architecture, and the payloads the app receives are in the API reference.

Regenerate this page with make data-model-doc after any model change. A test fails the suite if you forget.

How to read it¶

One app owns every table. They all live in src/data/, and nothing outside it defines a model. Reads go through src/readers/, writes through src/actions/. Framework tables that Wagtail, Django auth and django-taggit create are not listed here.

Publishable means Wagtail draft and live. A publishable model has a draft version and a live version, and readers only ever see live. One exception, on purpose: a piece unpublished after a reader saved it stays in that reader's bookmark list with is_available: false, so the save does not look lost. They get the card, never the body. A journey chapter is not publishable on its own: it is a child row captured inside the journey's revision, so publishing the journey publishes its chapters with it.

A row that points at "a piece" carries one nullable foreign key per piece type, plus a check constraint on how many may be set. Bookmarks and audio take exactly one. A reflection takes at most one, because its link is cleared when the piece is deleted and the reflection stays. A single content_type column would have been shorter but would lose the database-level integrity this keeps (ADR-0008).

A journey chapter owns its passage. Passage.journey_only marks a passage made for a chapter. A chapter accepts only those, and a unique constraint keeps each one with a single chapter. The discovery queries filter on the flag. Writings and articles stay shareable (ADR-0015).

Deleting follows three rules. A chapter PROTECTs the piece it uses, so an editor cannot delete a passage that a journey is built on. Everything a reader owns CASCADEs from the reader, so deleting an account takes the reader's data with it. A reflection's link to its piece is SET_NULL, because what the reader wrote outlives the piece it answered.

Some absences are deliberate. There is no current_chapter column: the next chapter is derived from what the reader has completed (ADR-0011). There is no audio staleness flag: a row exists only for approved audio, and staleness is a hash comparison at read time. There is no mid-chapter cursor: position inside a chapter stays on the device.

Every publishable model also carries latest_revision, live_revision and locked_by from Wagtail. They are the same on every such model, so they are left out of the tables below.

Join tables are drawn, not listed. A many-to-many field creates its own table, for example themes on a passage. The tables below list declared models only, so the link shows up as an edge in the diagram rather than as a row of its own.

Taxonomy¶

The vocabulary every other table points at. Themes are the worlds the app skins itself to and are loaded by sync_themes; tags are editor-made and grouped into categories.

Table	Model	Kind	What it holds
`data_tag`	`Tag`	Table	A value within a Tag Category.
`data_tagcategory`	`TagCategory`	Table	An editor-created container for tags, e.g. 'Emotional Register', 'Depth'.
`data_theme`	`Theme`	Table	A world a user enters (not a tag).

erDiagram
    data_tagcategory ||--o{ data_tag : "category"