The Fractal Module Model: ERP Root to TypeScript Leaf
New here? ValidKeep governs regulated software with linked atomic files in Git and deterministic npx validkeep verify (no LLM in the audit path). Optional ysbuild helps author specs; verify is the impartial gate either way.
Start with the ecosystem map for the platform stack (assurance profile, landscape profile, CLI, ValidKeep Hub). Then read the atomic model ($D_x$, $R_x$, $C_x$, $L_x$) if notation like $C_x$ is unfamiliar. Operational Qualification (OQ) and Performance Qualification (PQ) are explained in their own articles.
The repository is one fractal tree of governed modules. The balance law ($O_x = C_x$), trace chain ($CODE \rightarrow L_x \rightarrow C_x \rightarrow O_x$), and OQ and PQ split apply at $M_0$, $M_{0.2}$, and $M_{0.2.1}$ alike. What changes is the material inside the boundary, not the algebra defined in the atomic model.
Container vs leaf modules
- Container modules (often near the monorepo root, ERP-scale): $CODE$ is manifests, workflows, landscape config. $L_x$ describes topology and delegates through $D_i$ and sliced $B_i$.
- Leaf modules (deep directories, TypeScript services): $CODE$ is application source. $L_x$ holds algorithms and PQ probe placement; $C_x$ is a small exported surface.
Fractal depth rule
Document at the abstraction level of the module directory you are in. At a package root, $C_x$ describes scripts, CLI entrypoints, and public API shape. At a leaf, $C_x$ lists exported handlers; $B_x$ lists imports and services that code in that folder actually uses. The notation is identical; the zoom level changes.
Three practical consequences
- Requirements find their level. Stakeholder rules ($R_x$) belong in the lowest module that can own them. Root $D_x$ stays thin; domain experts inject finance rules into the finance submodule.
- Slicing at boundaries. Parents author child mandates ($D_i$), grant narrowed tool slices ($B_i$), and integrate child interfaces ($C_i$). Capabilities grow abstract ascending; authorized tools grow specific descending.
- Plug-and-play modules. Whole directories can hoist to peers or demote to children with $C_x$, OQ cases, and PQ probes largely intact. What rewires is who sets $D_x$ and who grants $B_x$.
Fractal patterns in practice
High Assurance architecture guidance encodes recurring shapes. The two below matter most when decomposing a monorepo:
Requirement peel-away (avoid root hoppers)
Stakeholder rules ($R_x$) belong in the lowest module that can own them. A root requirements hopper (everything in one monolithic $R_x$ chapter) fails fractal delivery: leaf code changes but the root binder never tracks them.
During decomposition or CR scoping, peel a fragment that belongs in child $M_{0.2}$: remove the duplicate heading upstream, re-author under child *.rx.md, and update trace joins. npx validkeep verify fails if two copies claim the same rule ID or if OQ loses its join target. Root $D_x$ stays thin delegation posture only.
Opaque vs transparent parent $C_x$
Parent modules choose one of two legitimate capability shapes:
- Opaque: composed API hides child boundaries. OQ targets parent $C_x$; children may have separate integration tests.
- Transparent: parent re-exports child surfaces with minimal wrapping. OQ often delegates to children; parent $C_x$ must list re-exports explicitly for verify routing.
If the parent adds behavior beyond routing, prefer opaque. If the parent is mostly a folder convention, prefer transparent with peel-away $R_x$ to children. Document the choice in $L_x$.
Other patterns: static artifacts (LICENSE, config) are CODE with trace joins; tool demand flows bottom-up into parent $B_x$ grants; OQ stays at $C_x$ only while PQ targets $L_x$ under load (see dedicated OQ and PQ articles).
An end-to-end test package, doc generator, or auth service is not a special lifecycle phase; it is another module that borrows upstream tools as $B_x$ and publishes its own $C_x$ to siblings.