Diff: architecture/six-tier-sovereignty-matrix.es
From a27c430 to a27c430
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "The six-tier sovereignty matrix" | title: "The six-tier sovereignty matrix" |
| slug: six-tier-sovereignty-matrix | slug: six-tier-sovereignty-matrix |
| category: architecture | category: architecture |
| type: concept | type: concept |
| quality: complete | quality: complete |
| status: active | status: active |
| audience: vendor-public | audience: vendor-public |
| bcsc_class: public-disclosure-safe | bcsc_class: public-disclosure-safe |
| language_protocol: PROSE-TOPIC | language_protocol: PROSE-TOPIC |
| last_edited: 2026-05-15 | last_edited: 2026-05-15 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| paired_with: six-tier-sovereignty-matrix.es.md | paired_with: six-tier-sovereignty-matrix.es.md |
| short_description: "The six-tier sovereignty matrix organises every directory in the PointSav monorepo by purpose, not by language or compile format — six fixed prefixes (app-, asset-, moonshot-, os-, service-, system-) that make the repository self-documenting and enforce dependency hygiene by convention." | short_description: "The six-tier sovereignty matrix organises every directory in the PointSav monorepo by purpose, not by language or compile format — six fixed prefixes (app-, asset-, moonshot-, os-, service-, system-) that make the repository self-documenting and enforce dependency hygiene by convention." |
| cites: [] | cites: [] |
| --- | --- |
| The PointSav monorepo organises every directory by purpose, not by programming language or compile format. Each directory at the repository root belongs to one of six tiers — `app-`, `asset-`, `moonshot-`, `os-`, `service-`, or `system-` — identified by a fixed prefix. A contributor reading the prefix knows immediately what layer a directory operates at without opening a file. This article covers the six tiers, the decision rule for classifying new directories, the kebab-case constraint that makes the taxonomy portable across operating systems and container registries, and the legacy names the taxonomy supersedes. | The PointSav monorepo organises every directory by purpose, not by programming language or compile format. Each directory at the repository root belongs to one of six tiers — `app-`, `asset-`, `moonshot-`, `os-`, `service-`, or `system-` — identified by a fixed prefix. A contributor reading the prefix knows immediately what layer a directory operates at without opening a file. This article covers the six tiers, the decision rule for classifying new directories, the kebab-case constraint that makes the taxonomy portable across operating systems and container registries, and the legacy names the taxonomy supersedes. |
| ## The six tiers | ## The six tiers |
| Every directory at the monorepo root falls into one of the following tiers: | Every directory at the monorepo root falls into one of the following tiers: |
| | Tier | Prefix | Purpose | Example components | | | Tier | Prefix | Purpose | Example components | |
| |---|---|---|---| | |---|---|---|---| |
| | 1 — Application | `app-` | User-facing surfaces — the personality cartridges that define how a job looks and feels | `app-console-input`, `app-mediakit-marketing`, `app-orchestration-command` | | | 1 — Application | `app-` | User-facing surfaces — the personality cartridges that define how a job looks and feels | `app-console-input`, `app-mediakit-marketing`, `app-orchestration-command` | |
| | 2 — Asset | `asset-` | Non-code resources — fonts, icons, 3D models, design tokens, brand assets | `asset-brand-pointsav`, `asset-brand-wcp` | | | 2 — Asset | `asset-` | Non-code resources — fonts, icons, 3D models, design tokens, brand assets | `asset-brand-pointsav`, `asset-brand-wcp` | |
| | 3 — Moonshot | `moonshot-` | Research and development experiments not yet promoted to production | `moonshot-gpu` | | | 3 — Moonshot | `moonshot-` | Research and development experiments not yet promoted to production | `moonshot-gpu` | |
| | 4 — OS | `os-` | Operating-system compositions — the runtime containers that load other components | `os-console`, `os-totebox`, `os-orchestration` | | | 4 — OS | `os-` | Operating-system compositions — the runtime containers that load other components | `os-console`, `os-totebox`, `os-orchestration` | |
| | 5 — Service | `service-` | Background business-logic daemons | `service-slm`, `service-content`, `service-email`, `service-people` | | | 5 — Service | `service-` | Background business-logic daemons | `service-slm`, `service-content`, `service-email`, `service-people` | |
| | 6 — System | `system-` | Foundational technology — drivers, networking, foundation utilities | `system-foundation`, `system-driver-network`, `system-audit` | | | 6 — System | `system-` | Foundational technology — drivers, networking, foundation utilities | `system-foundation`, `system-driver-network`, `system-audit` | |
| The word "library" is explicitly retired as a category label. It describes how code is compiled, not what it does. | The word "library" is explicitly retired as a category label. It describes how code is compiled, not what it does. |
| ## The rule of purpose | ## The rule of purpose |
| A new directory is classified by its purpose, not its format. The decision is short: | A new directory is classified by its purpose, not its format. The decision is short: |
| | Question | Tier | | | Question | Tier | |
| |---|---| | |---|---| |
| | Does it talk to the computer — date parsing, networking, math, filesystem? | `system-*` | | | Does it talk to the computer — date parsing, networking, math, filesystem? | `system-*` | |
| | Does it talk to the user's life — contacts, email, photos, accounting? | `service-*` | | | Does it talk to the user's life — contacts, email, photos, accounting? | `service-*` | |
| | Does it define the look and feel for a specific job? | `app-*` | | | Does it define the look and feel for a specific job? | `app-*` | |
| | Is it a non-code resource — a font, an icon, a design token? | `asset-*` | | | Is it a non-code resource — a font, an icon, a design token? | `asset-*` | |
| | Is it speculative research not yet committed to production? | `moonshot-*` | | | Is it speculative research not yet committed to production? | `moonshot-*` | |
| | Does it compose other components into a runtime container? | `os-*` | | | Does it compose other components into a runtime container? | `os-*` | |
| ## Why the prefix discipline scales | ## Why the prefix discipline scales |
| Three structural advantages emerge from the taxonomy: | Three structural advantages emerge from the taxonomy: |
| | Advantage | Effect | | | Advantage | Effect | |
| |---|---| | |---|---| |
| | Discoverability | A new contributor reading a directory name knows immediately what layer it operates at without opening a file | | | Discoverability | A new contributor reading a directory name knows immediately what layer it operates at without opening a file | |
| | Dependency hygiene | `app-*` may depend on `service-*` and `system-*`; `service-*` may depend on `system-*`; `system-*` has no upward dependencies — cyclic dependencies are mechanically impossible | | | Dependency hygiene | `app-*` may depend on `service-*` and `system-*`; `service-*` may depend on `system-*`; `system-*` has no upward dependencies — cyclic dependencies are mechanically impossible | |
| | Composition over inheritance | An operating system is an `os-*` composition that loads `app-*` cartridges and connects to `service-*` daemons; the OS contains no feature-specific code | | | Composition over inheritance | An operating system is an `os-*` composition that loads `app-*` cartridges and connects to `service-*` daemons; the OS contains no feature-specific code | |
| This is the filesystem-level expression of composition over inheritance: the OS is a generic engine; the application is the personality. | This is the filesystem-level expression of composition over inheritance: the OS is a generic engine; the application is the personality. |
| ## Strict kebab-case | ## Strict kebab-case |
| All six tiers use lowercase ASCII with hyphens. Capital letters are not permitted. The constraint holds across Docker registries, case-sensitive Linux filesystems, case-insensitive macOS filesystems, and DNS subdomains. | All six tiers use lowercase ASCII with hyphens. Capital letters are not permitted. The constraint holds across Docker registries, case-sensitive Linux filesystems, case-insensitive macOS filesystems, and DNS subdomains. |
| | Form | Status | Reason | | | Form | Status | Reason | |
| |---|---|---| | |---|---|---| |
| | `os-totebox` | Canonical | Lowercase kebab-case | | | `os-totebox` | Canonical | Lowercase kebab-case | |
| | `Totebox-OS` | Not permitted | Mixed case creates phantom drift across operating systems | | | `Totebox-OS` | Not permitted | Mixed case creates phantom drift across operating systems | |
| | `Totebox_OS` | Not permitted | Underscores are not standard in repository or container names | | | `Totebox_OS` | Not permitted | Underscores are not standard in repository or container names | |
| | `toteboxos` | Not permitted | Loses readability without a delimiter | | | `toteboxos` | Not permitted | Loses readability without a delimiter | |
| Uppercase is preserved only for a small set of root-level operational files — `README`, `LICENSE`, `CLAUDE.md`, `AGENT.md` — where the convention predates the kebab-case rule. | Uppercase is preserved only for a small set of root-level operational files — `README`, `LICENSE`, `CLAUDE.md`, `AGENT.md` — where the convention predates the kebab-case rule. |
| ## Name supersession | ## Name supersession |
| The taxonomy took several generations to settle. Earlier names appear throughout the source archive and are normalised when content is migrated: | The taxonomy took several generations to settle. Earlier names appear throughout the source archive and are normalised when content is migrated: |
| | Earlier name | Current canonical | | | Earlier name | Current canonical | |
| |---|---| | |---|---| |
| | `lib-pointsav-*` | `package-*` (shared libraries) | | | `lib-pointsav-*` | `package-*` (shared libraries) | |
| | `software-pdfs`, `software-wordprocessing` | `app-workplace-pdfs`, `app-workplace-wordprocessor` | | | `software-pdfs`, `software-wordprocessing` | `app-workplace-pdfs`, `app-workplace-wordprocessor` | |
| | `console-people`, `node-console-people` | `app-console-people` | | | `console-people`, `node-console-people` | `app-console-people` | |
| | `sys-marketing`, `sys-knowledge`, `sys-distro` | `app-mediakit-marketing`, `app-mediakit-knowledge`, `app-mediakit-distribution` | | | `sys-marketing`, `sys-knowledge`, `sys-distro` | `app-mediakit-marketing`, `app-mediakit-knowledge`, `app-mediakit-distribution` | |
| | `fleet-infrastructure-*`, `gateway-interface-*`, `route-network-admin` | `app-infrastructure-onprem` / `-leased` / `-cloud`, `app-orchestration-command`, `app-network-admin` | | | `fleet-infrastructure-*`, `gateway-interface-*`, `route-network-admin` | `app-infrastructure-onprem` / `-leased` / `-cloud`, `app-orchestration-command`, `app-network-admin` | |
| ## See also | ## See also |
| - [[os-family-overview]] — the eight operating systems composed using the `os-*` tier | - [[os-family-overview]] — the eight operating systems composed using the `os-*` tier |
| - [[three-layer-architecture]] — the three-layer arrangement of vendor, customer, and operator that the monorepo sits within | - [[three-layer-architecture]] — the three-layer arrangement of vendor, customer, and operator that the monorepo sits within |
| - [[five-stage-supply-chain]] — how the monorepo's verified commits reach production deployments | - [[five-stage-supply-chain]] — how the monorepo's verified commits reach production deployments |