Project Ops

Learning Package Architecture Review

Project operations source: Learning Package Architecture Review.

Status: Working architecture review, not an approved schema or implementation plan.
Source: Concept map adapted from a class diagram supplied by Zai on 2026-07-27, based on the published internal Learning Lab site.
Purpose: Make the current structure, its friction, and the next architecture questions visible before changing curriculum packages, metadata, templates, or the Astro renderer.

Current Learning Lab concept map

Rendering note: This uses Mermaid flowchart, rather than the original classDiagram, because it is more broadly supported by VS Code Markdown preview extensions and is a clearer fit for a conceptual map. The local VS Code version is 1.130.0; the intranet’s bundled Mermaid version is 11.15.0, but a user’s VS Code preview may use a different Mermaid runtime.

flowchart LR
    subgraph source[Markdown source of truth]
        tracks[Tracks]
        modules[Modules]
        labs[Labs]
        support[Guides, examples, materials, and static assets]
    end

    tracks -->|suggest paths through| modules
    modules -->|link to primary practice in| labs
    labs -->|may include| support

    metadata[Package metadata<br/>lifecycle, learner availability,<br/>owner, and review needs]
    relationships[Declared relationships<br/>track, module, and lab]
    tracks --> metadata
    modules --> metadata
    labs --> metadata
    tracks --> relationships
    modules --> relationships
    labs --> relationships

    issues[GitHub Issues and Project<br/>assignment and review queue]
    issues -. does not replace .-> source

    sync[Astro content sync<br/>link rewriting and validation]
    intranet[Internal intranet<br/>learner pages and resource maps]
    local[Local-only notebooks and feedback<br/>learner-controlled downloads]

    source --> sync --> intranet
    labs --> local

Radar’s reading of the diagram

What works

  • It correctly identifies three distinct learner-facing package types: tracks, modules, and labs. That matches the project’s established spine.
  • It makes relationships first-class. In particular, the ModuleLabLink idea expresses a real need: a module should identify the lab that supplies its primary practice, while a lab can support more than one module or track.
  • It separates content from the rendered site. That aligns with the current Markdown-first source model and Astro’s role as a renderer.
  • It treats review and governance as visible rather than assuming a polished file is ready for learners. The current lifecycle, learner-availability, owner, and review-status metadata are the beginnings of this.
  • It distinguishes a guide, worked example, downloadable resource, media, assessment, reference, and feedback support. Those are useful vocabulary categories for an eventual inventory, even though the current repository does not yet represent them as typed objects.

What does not describe the current project

  • This is a target-domain model, not the current architecture. Today, packages are Markdown folders with a small amount of YAML frontmatter; the Astro sync script discovers files and renders pages. There is no PackageManifest, PackageContract, AssetBinding, asset registry, or database.
  • The diagram makes each package validate against a complete contract. The project deliberately has not done that yet. A package at Seed, Sketch, Draft, Pilot, or Available needs different evidence; a rigid contract could turn honest incompleteness into noisy exceptions.
  • SlotDefinition and AssetBinding would introduce a second inventory of every file and a new source-of-truth problem: is the authoritative record the Markdown folder, the binding registry, or both? That is a sizeable content-management system, not a small metadata improvement.
  • The broad Asset inheritance tree is more detailed than the team currently needs. It risks making every worksheet, transcript, page, video script, review form, and future external link carry version, visibility, and state fields before there is a demonstrated decision that needs those fields.
  • PublicSiteBuilder is misleading for the present purpose. The site is an internal intranet, and the real implementation is a Markdown-to-Astro content sync. If this responsibility later needs a name, Intranet Content Sync would be more accurate than a public-release builder.
  • PublishedArtifact implies that every package produces a stable, versioned publishing artifact. In reality, many Markdown notes are source, review material, or internal facilitation support; the static site is a rendered view, not a release system for each file.

What is missing from the diagram

  • The two current status dimensions. The project intentionally separates production lifecycle from learner availability. A future model must preserve that distinction, rather than replace both with one generic asset state.
  • Evidence and review ownership. GovernanceRecord is a useful start, but the project also needs an explicit distinction between an open review need, actual evidence, an assigned reviewer, and a completed decision. A review form export is evidence; it is not automatically a status transition.
  • The contributor work queue. GitHub Issues and the project board govern proposals, assignments, and reviews. They are not curriculum source and should not be duplicated into package metadata.
  • The primary-source rule. The repository needs a way to express that a module owns a learning sequence while a related lab owns the canonical activity; Maple Park further demonstrates a source → model → walk-through trail. Relationship names alone do not establish which material is canonical.
  • Provenance, rights, and safety boundaries. Gallery contributions, reconstructed conversations, public-domain images, personal images, audio, and external video links need source/rights and review context. This does not mean all need a universal schema today, but the model does not identify the distinction.
  • Local-only learner data. Lab notebooks and feedback forms deliberately do not automatically store or submit notes. Their browser-only boundary, downloads, and optional handoff behavior matter more than a generic FeedbackSupportAsset type.
  • The actual rendering boundary. Markdown link rewriting, static app asset sync, generated routes, and built-link validation are current architectural responsibilities. They are absent from the diagram even though they create much of the friction contributors encounter.
  • Migration and coexistence. The repository has heterogeneous older packages alongside newer Draft-standard packages. Any future contract needs a compatibility or migration stance; it cannot assume that all existing folders already match one model.

Friction this diagram usefully exposes

The team is currently encountering at least three different questions under the word “package”:

  1. What belongs in a source folder?
  2. What does a learner see and do first?
  3. What evidence is needed before the team calls it ready?

Those questions should remain separate. A single universal manifest might eventually help with the first and second questions, but it cannot decide the third one without real governance rules and human evidence.

Recommendation for the next iteration

Do not implement this class model or a universal manifest now. It would violate the project’s current Markdown-first, no-platform boundary and would prematurely standardize patterns that are still being tested.

Instead, use this document as a discussion tool and derive a much smaller current-state map from the repository:

  1. Name the authoritative source folder and learner entry point for one track, one module, and one lab.
  2. Record only the metadata that is already required and genuinely validated today.
  3. Identify the few repeated relationships that must be machine-checkable: track ↔ module, module ↔ lab, and a package’s primary learner action.
  4. Separate optional assets from required evidence by lifecycle stage, not by a universal asset taxonomy.
  5. Decide whether one narrow manifest is needed only after the inventory shows that Markdown folder discovery and frontmatter cannot carry the agreed rules.

That path gives us an architecture that describes the Lab we actually have, rather than a content platform we may never need.

Open questions for the team

  • Which package facts must be machine-validated now, and which should remain visible prose until the workflow has more evidence?
  • Is a module’s learner path always its primary action, or can a module legitimately start with a related lab?
  • Which supporting artifacts must be present for Draft versus merely named as review needs?
  • When an asset has its own maturity—for example a future video or gallery contribution—does it need an independent status, or is a transparent note in the package enough?
  • What is the smallest relationship vocabulary that lets contributors place a new package without recreating the same ambiguity?

Boundary for this review

This document changes no metadata, templates, validation, rendering, contributor workflow, lifecycle language, or published site. It is a checkpoint for understanding before any architecture decision is proposed.

Source: ops/learning-package-architecture-review.md