Feature guide

Learning catalogue and content

Lessons, vocabulary, phrases, exercises, readings, listening tasks, textbook references, and publication-quality checks.

← Technical overview

What this domain owns

What is taught and the structured contracts that the UI renders.

Feature flow diagram

Content files and legacy catalogue
        │
        v
createLegacyLearningCatalogue()
        │
        v
Catalogue snapshot ──> public.ts exports
        │                       │
        ├── quality checks       └── lesson / practice / exam screens
        v
Published learning structures

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

Class and relationship diagram

┌───────────────────┐ creates ┌────────────────────┐ exports ┌───────────────┐
│ Authored content  │────────▶│ LearningCatalogue  │────────▶│ Public API    │
└───────────────────┘         ├────────────────────┤         ├───────────────┤
                              │ + lessons           │         │ + lesson(id)  │
                              │ + weeks             │         │ + courseWeeks │
                              └─────────┬──────────┘         └───────┬───────┘
                                        ▼                            ▼
                                  ┌──────────┐              ┌──────────────┐
                                  │ Lesson   │              │ 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/content files
Catalogue builder
Public catalogue
Course screen
Quality tests
provide lesson structures
create typed snapshot
published snapshot
request lesson/week data
typed content
verify required content contracts

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

  1. Catalogue infrastructure creates one snapshot.
  2. The public module exposes typed learning data.
  3. Screens select the relevant lesson/task.
  4. Quality rules audit whether content is publishable and complete.

Read this code

src/contexts/learning-catalogue/public.tsOpen in VS Code — Expose one stable catalogue boundary

const catalogue = createLegacyLearningCatalogue();

export function lesson(id: string) {
  return catalogue.lessons.find((item) => item.id === id);
}

export function courseWeeks() {
  return catalogue.weeks;
}

What each part is doing

  1. Screens import this public boundary rather than digging into content files.
  2. The function returns typed lesson data or undefined, so callers must handle a missing ID.
  3. Moving data internally should not require every lesson screen to change.

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 returns published editorial overrides.
  • Admin content routes update the publication layer.

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.