Content management — technical reference

What this domain owns

Changing published learning content safely without changing the code catalogue for every editorial update.

Feature flow diagram

Content editor
        │
        v
Admin content page ──> admin API route
        │                         │
        │                         v
        │                 role + payload validation
        │                         │
        v                         v
Draft / revision record ──publish──> published lesson or week override
                                            │
                                            v
                                  course screens load published only

This diagram shows the normal direction of control and data. Follow it before changing a boundary or adding a dependency.

Class and relationship diagram

┌──────────────┐ command ┌────────────────────┐ stores ┌──────────────┐
│ Admin editor │─────────▶│ Content service    │──────▶│ Revision      │
└──────────────┘          ├────────────────────┤       └──────┬───────┘
                        │ + saveRevision()    │              │ publish
                        │ + publish()         │              ▼
                        └──────────┬──────────┘       ┌──────────────┐
                                   ▼                  │ Published    │
                          ┌─────────────────┐         │ override     │
                          │ Role validator  │         └──────┬───────┘
                          └─────────────────┘                ▼
                                                       ┌──────────────┐
                                                       │ Course UI    │
                                                       └──────────────┘

Boxes show the important data types or services. Their fields and main methods are listed inside; arrows show the primary dependency or data relationship.

Sequence diagram

Editor

Admin content page

Admin page

Admin API

Role guard

Content service

Published override

Course screen

Content API

edit lesson/week

submit command

confirm content-editor access

editor allowed

validate and save revision

saved revision

publish revision

mark current version

publication confirmed

load published override only

Read this from top to bottom: each arrow is the next interaction in the normal successful path.

Start here in the code

Choose any filename to open it directly in VS Code.

How it works

Editor authenticates as content editor.
Admin route validates edit.
Content service records revision/published state.
Course screens load published overrides only.

Read this code

src/contexts/content-management/server.tsOpen in VS Code — Publish an editorial change through a service

await requireRole(actor, 'content_editor');
const input = updateLessonSchema.parse(payload);
const revision = await content.saveRevision(input);

if (input.publish) await content.publish(revision.id);

What each part is doing

The route identifies the editor; the service should not trust a role sent in the form.
Validation turns unknown editor input into a typed update command.
Saving a revision and publishing it are separate actions so drafts stay safe.

This is a deliberately short excerpt of the real pattern, with unrelated details omitted. Read the named file for the complete implementation.

Related API and server boundaries

GET /api/content/lessons
GET /api/content/lessons/:id
/api/admin/content/lessons
/api/admin/content/images

Tests to read and run

Implementation notes

This is the home for detailed explanations, decision records, request examples, and diagrams for this feature. Add new feature-specific documentation here instead of expanding the platform overview.