Architecture
The desired structure of the DotNaos platform and the rules that keep it trustworthy.
Architecture is the Git-backed source of truth for the desired DotNaos system. The model stays intentionally coarse: it records stable responsibilities, ownership, hierarchy, and meaningful relations without duplicating implementation details from every repository.
Explore the system
Open the full-page graph to browse the current architecture.yaml visually. Selecting a node reveals its owner, parent, relations, and linked documentation.
The hosted graph is a validated snapshot of architecture.yaml from the site build. During local development it watches the checkout directly, so edits appear without publishing a package or rebuilding another repository.
Sources of truth
| Concern | Source |
|---|---|
| Node identity, hierarchy, ownership, relations | architecture.yaml |
| Explanations, workflows, contributor guidance | MDX pages in content/docs |
| Link between both | Stable architectureId frontmatter |
The join is validated before a build: an MDX page without an ID, two pages using the same ID, or a page referencing a stale YAML node fails with a direct error.
State model
architecture@main = desired state
repo@ref/.architecture/manifest.yaml = observed state
observed(base) -> observed(head) = implementation migration
desired - observed = remaining architecture gap