curriculum-project-hub/docs/adr/0007-engineering-file-as-directory-tree.md

ADR 0007: The Engineering File Is A Directory Tree On Disk

Status

Accepted — for the on-disk decision below. The concrete layout conventions are deliberately left open; see Open Questions / Deferred.

Grounds the abstract premise ADR-0006 relied on. ADR-0006 established that rich content needs a virtual path and that the engineering file therefore constitutes a path-structured virtual file system — but it deliberately did not say what that path structure is physically. This ADR fixes that: it is a real directory tree on a real file system.

Context

ADR-0006 showed that a rich-content (content) value cannot be free-floating Typst source: it must be a first-class file with a virtual path so that click-to-jump (spans) and relative imports work. That leaves a choice for the physical form of the engineering file: a packed/opaque archive, a database blob, or a plain directory tree.

The decisive constraint is who edits the engineering file: a coding agent (Claude) collaboratively with teachers (ADR-0005's premise), and ordinary tools. An agent works best when it can read and modify files directly and use existing tooling (grep, find, diff, version control) over plain files in plain directories. A packed or database form would force a custom access layer for every such operation.

The developer's earlier prototype already had this shape implicitly — segments/, examples/, lemmas/ directories with per-item files — which is the directory tree in embryo, not a crude stand-in.

Decision

The on-disk form of an engineering file is a directory tree on a real file system.

• A content field's virtual path (ADR-0006) is a real relative path within that directory tree. The compiler's World maps virtual paths to the actual files in the tree; no synthetic/in-memory file system is needed.
• Relative imports inside rich content resolve relative to the importing file's real position in the tree — which is exactly the import boundary ADR-0006 pinned ("within the engineering file, plus @package"). This ADR gives that boundary its physical basis: "within the engineering file" = "within this directory tree".

This keeps the engineering file legible to agents and to off-the-shelf tooling, and makes the relationship between content fields and their sources directly inspectable on disk.

Consequences

• The engineering file is a directory of plain text/Typst files: directly greppable, diffable, version-controllable, and editable by an agent without a bespoke access layer.
• World is a thin mapping from the directory tree; virtual path = relative path removes any need to invent or maintain a separate virtual file system.
• The engineering file remains self-contained on disk: its import closure is the tree itself plus published packages (ADR-0006), so it can be moved, copied, or archived as a directory without dangling references to sibling lessons.
• This is the physical representation of ADR-0005's abstract Lesson (an ordered sequence of typed elements); how that ordered structure is encoded into the directory is a separate question (below), not implied by "it's a tree".

Open Questions / Deferred

• Layout conventions — the concrete directory layout is not fixed here. Specifically deferred: the manifest file (name, location, what it holds); how element instances are arranged in the tree and how their order (ADR-0005's Lesson is an ordered sequence) is encoded; naming/organization of rich-content .typ files. This is the on-disk encoding of ADR-0005's Lesson and warrants its own ADR — kept separate so this one fixes only "it is a directory tree", not "how the tree is arranged".