CS-01documentation

BDOS v3: enterprise documentation architecture

A model-driven systems documentation platform

JSON Schema
MkDocs
Python
Git

canonical models: 146
system domains: 14
where: Blue Devil Development, 2025 to present

01 problem

Operational knowledge lived in scattered documents. Onboarding was slow, recovery depended on whoever remembered the system, and engineering standards conflicted from one document to the next.

02 solution

I defined the requirements, designed the architecture, and built a platform that holds 146 canonical models across 14 domains. Each model is validated against a JSON Schema, documentation is generated rather than hand-edited, and architecture decision records live in the same pipeline.

03 impact

Every core domain, including recovery procedures, is covered by one validated structure. Validation rejects unapproved structural changes, so the documentation cannot drift from the system it describes.

How it is organized

Source models are YAML. Each one is checked against its schema before anything is built, and the build output is never edited by hand. That rule is the whole point: a document a person can edit freely is a document that will eventually disagree with the system.

bdos.v3/
├── domains/            14
├── models/             146 canonical
│   └── *.yaml  ──►  schema.json   ✓ valid
├── adrs/               decision records
└── build/              generated, never hand-edited

exhibit: model tree

Testing and MkDocs integration run in the same pipeline as the models, so a change that breaks the documentation site fails before it merges.

sources

BDOS v3, Blue Devil Development, 2025 to present