# jasoncheroske/lab-os architecture

> Architecture diagram of the GitHub repository jasoncheroske/lab-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jasoncheroske/lab-os
- Repository: https://github.com/jasoncheroske/lab-os

## Overview

1. **What this repository is**
   Lab OS is a **source seed** for creating and governing “labs” — structured engineering workspaces that combine architecture intent, implementation reality, evidence, and behavioral policy. It is not a product app; it is a **repository generator plus governance framework**.

2. **Primary architecture goal**
   The repo’s core function is to produce a repeatable lab scaffold that can be initialized from a template, validated against a schema, promoted through maturity stages, and packaged as a release tarball. The architecture is centered on **reproducible repository bootstrapping** rather than runtime request handling.

3. **Main artifact model**
   The lab itself is organized into four major content areas:
   - `intent/` for target architecture
   - `reality/` for implementation mapping
   - `delta/` for gaps between intent and reality
   - `evidence/` for readiness checks and ADR templates
   - `behavior/` for governance policy and signoffs  
   This is the core domain boundary: architecture, execution state, gap analysis, and governance are separated on disk.

4. **Template-to-instance flow**
   The `template/` directory is the canonical starting shape for a new lab. Scripts copy or initialize this structure into a target directory, creating a working lab instance with the same logical substructure. The root-level `lab/` and the example labs under `examples/` demonstrate the expected instantiated result.

5. **Validation boundary**
   `schema/lab.schema.json` defines the structural contract for a lab. The validation scripts enforce that a target lab has the expected shape and metadata before it can be promoted or released. This makes the schema the main guardrail between “files on disk” and “acceptable lab state.”

6. **Lifecycle and promotion flow**
   The repo models a maturity sequence with explicit stage promotion: `experiment -> poc -> pilot -> production`. The `promote-stage.mjs` script advances a lab only when the target stage is valid. That promotion boundary is important because it prevents accidental jumps in governance maturity.

7. **Tooling subsystem**
   The executable logic lives in `scripts/`:
   - initialization/bootstrap
   - validation
   - verification
   - promotion
   - tarball packaging  
   These scripts are the operational layer that turns the documentation and templates into working artifacts. `package.json` wires them into the npm command surface described in the README.

8. **Release packaging path**
   The primary release artifact is an initialized lab tarball. `scripts/build-lab-tar.mjs` creates the distributable archive plus checksum, and the README treats this tarball as the main user-facing output for Phase 1 release. That means the release boundary is file-based distribution, not a hosted service or package registry.

9. **Documentation architecture**
   `docs/` is not incidental; it is a first-class subsystem. It is split into:
   - architecture
   - governance
   - runbooks
   - release
   - ADRs
   - reference
   - backlog  
   This indicates the repo treats documentation as executable context for governance and adoption, not merely background material.

10. **Examples as living fixtures**
   `examples/minimal-lab` and `examples/hybrid-governance-lab` are reference instances used to prove the framework works in different complexity levels. They function as architectural fixtures: one minimal, one more policy-heavy. The validation matrix in the README explicitly uses them as regression targets.

11. **Tests and quality gate**
   `tests/generation.test.mjs` is the main automated check for generation behavior. Combined with validation commands in the README, the repo’s quality strategy is to verify that generated labs are structurally correct and that release artifacts are reproducible.

12. **Operational and editor integration**
   The `.cursor/` rules and skills directory provide optional editor-assisted bootstrap support, but they are not required for the repo to function. The important point is that the same initialization and verification path works through CLI or editor automation, so the architecture is tool-agnostic at the workflow level.

13. **Overall data flow**
   The main flow is:
   **template + schema + scripts → initialized lab directory → validation against schema → promotion through maturity stages → tarball release**.  
   Documentation and examples feed back into this flow by defining expected structure, governance policy, and release readiness criteria.

14. **What to diagram**
   An accurate architecture diagram should show:
   - the **source seed repo** as the control plane
   - `template/`, `schema/`, and `scripts/` as the core engine
   - generated lab instances as the output plane
   - `docs/` as governance and operating knowledge
   - `examples/` and `tests/` as verification fixtures
   - release tarball generation as the external distribution boundary

Main entry points: [`lab`](https://github.com/jasoncheroske/lab-os/tree/main/lab) (Lab instance), [`scripts`](https://github.com/jasoncheroske/lab-os/tree/main/scripts) (Scripts), [`docs`](https://github.com/jasoncheroske/lab-os/tree/main/docs) (Docs), [`schema/lab.schema.json`](https://github.com/jasoncheroske/lab-os/blob/main/schema/lab.schema.json) (Lab schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Plane"]
  node_root(("lab-os<br/>source seed"))
  node_lab_yaml["Lab manifest<br/>instance metadata<br/>[lab.yaml]"]
  node_schema["Lab schema<br/>contract schema<br/>[lab.schema.json]"]
end

subgraph group_lab_model["Lab Model"]
  node_template["Template<br/>scaffold"]
  node_lab_instance["Lab instance<br/>generated workspace"]
  node_intent["Intent<br/>target architecture"]
  node_reality["Reality<br/>implementation map"]
  node_delta["Delta<br/>gap analysis"]
  node_evidence["Evidence<br/>readiness checks"]
  node_behavior["Behavior<br/>governance policy"]
end

subgraph group_tooling["Tooling"]
  node_scripts["Scripts<br/>tooling"]
  node_init_lab["Init lab<br/>bootstrap<br/>[init-lab.mjs]"]
  node_validate_lab["Validate<br/>validator<br/>[validate-lab.mjs]"]
  node_promote_stage["Promote stage<br/>maturity gate<br/>[promote-stage.mjs]"]
  node_build_tar["Build tarball<br/>release packager<br/>[build-lab-tar.mjs]"]
end

subgraph group_knowledge["Knowledge Base"]
  node_docs["Docs"]
end

subgraph group_verification["Verification"]
  node_examples["Examples<br/>fixtures"]
  node_tests["Tests<br/>generation checks"]
end

subgraph group_distribution["Distribution"]
  node_release_tar[("Release tar<br/>distribution artifact")]
end

node_root -->|"seeds"| node_template
node_root -->|"governs"| node_schema
node_root -->|"operates via"| node_scripts
node_root -->|"documents"| node_docs
node_root -->|"proves with"| node_examples
node_root -->|"verifies with"| node_tests
node_template -->|"materializes"| node_lab_instance
node_lab_yaml -->|"describes"| node_lab_instance
node_lab_instance -->|"contains"| node_intent
node_lab_instance -->|"contains"| node_reality
node_lab_instance -->|"contains"| node_delta
node_lab_instance -->|"contains"| node_evidence
node_lab_instance -->|"contains"| node_behavior
node_scripts -->|"executes"| node_init_lab
node_scripts -->|"executes"| node_validate_lab
node_scripts -->|"executes"| node_promote_stage
node_scripts -->|"executes"| node_build_tar
node_validate_lab -->|"checks against"| node_schema
node_promote_stage -->|"gates by"| node_behavior
node_build_tar -->|"produces"| node_release_tar
node_examples -.->|"mirror"| node_lab_instance
node_tests -.->|"regressions for"| node_template
node_tests -.->|"asserts"| node_schema
node_docs -.->|"defines"| node_schema
node_docs -.->|"guides"| node_behavior
node_docs -.->|"supports"| node_release_tar

click node_lab_yaml "https://github.com/jasoncheroske/lab-os/blob/main/lab.yaml"
click node_schema "https://github.com/jasoncheroske/lab-os/blob/main/schema/lab.schema.json"
click node_template "https://github.com/jasoncheroske/lab-os/tree/main/template"
click node_lab_instance "https://github.com/jasoncheroske/lab-os/tree/main/lab"
click node_intent "https://github.com/jasoncheroske/lab-os/tree/main/lab/intent"
click node_reality "https://github.com/jasoncheroske/lab-os/tree/main/lab/reality"
click node_delta "https://github.com/jasoncheroske/lab-os/tree/main/lab/delta"
click node_evidence "https://github.com/jasoncheroske/lab-os/tree/main/lab/evidence"
click node_behavior "https://github.com/jasoncheroske/lab-os/tree/main/lab/behavior"
click node_scripts "https://github.com/jasoncheroske/lab-os/tree/main/scripts"
click node_init_lab "https://github.com/jasoncheroske/lab-os/blob/main/scripts/init-lab.mjs"
click node_validate_lab "https://github.com/jasoncheroske/lab-os/blob/main/scripts/validate-lab.mjs"
click node_promote_stage "https://github.com/jasoncheroske/lab-os/blob/main/scripts/promote-stage.mjs"
click node_build_tar "https://github.com/jasoncheroske/lab-os/blob/main/scripts/build-lab-tar.mjs"
click node_docs "https://github.com/jasoncheroske/lab-os/tree/main/docs"
click node_examples "https://github.com/jasoncheroske/lab-os/tree/main/examples"
click node_tests "https://github.com/jasoncheroske/lab-os/blob/main/tests/generation.test.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root,node_lab_yaml,node_schema toneBlue
class node_template,node_lab_instance,node_intent,node_reality,node_delta,node_evidence,node_behavior toneAmber
class node_scripts,node_init_lab,node_validate_lab,node_promote_stage,node_build_tar toneMint
class node_docs toneRose
class node_examples,node_tests toneIndigo
class node_release_tar toneTeal
```

## Components

### Control Plane

Repository-level source seed, contract, and orchestration

- **lab-os**: source seed · Repository that generates and governs lab workspaces
- [Lab manifest](https://github.com/jasoncheroske/lab-os/blob/main/lab.yaml): instance metadata · Root lab configuration and metadata · `lab.yaml`
- [Lab schema](https://github.com/jasoncheroske/lab-os/blob/main/schema/lab.schema.json): contract schema · Structural contract for acceptable lab shape · `schema/lab.schema.json`

### Lab Model

Canonical lab structure and instantiated examples

- [Template](https://github.com/jasoncheroske/lab-os/tree/main/template): scaffold · Canonical starting shape for new labs · `template`
- [Lab instance](https://github.com/jasoncheroske/lab-os/tree/main/lab): generated workspace · Root instantiated lab structure · `lab`
- [Intent](https://github.com/jasoncheroske/lab-os/tree/main/lab/intent): target architecture · Desired architecture and design intent · `lab/intent`
- [Reality](https://github.com/jasoncheroske/lab-os/tree/main/lab/reality): implementation map · Observed implementation and mapping state · `lab/reality`
- [Delta](https://github.com/jasoncheroske/lab-os/tree/main/lab/delta): gap analysis · Gaps between intent and reality · `lab/delta`
- [Evidence](https://github.com/jasoncheroske/lab-os/tree/main/lab/evidence): readiness checks · Readiness evidence and ADR templates · `lab/evidence`
- [Behavior](https://github.com/jasoncheroske/lab-os/tree/main/lab/behavior): governance policy · Governance policy and signoffs · `lab/behavior`

### Tooling

Scripts and commands that generate, validate, and promote labs

- [Scripts](https://github.com/jasoncheroske/lab-os/tree/main/scripts): tooling · CLI automation for init, validate, verify, promote, and package · `scripts`
- [Init lab](https://github.com/jasoncheroske/lab-os/blob/main/scripts/init-lab.mjs): bootstrap · Initializes lab directories from the template · `scripts/init-lab.mjs`
- [Validate](https://github.com/jasoncheroske/lab-os/blob/main/scripts/validate-lab.mjs): validator · Checks lab structure against the schema · `scripts/validate-lab.mjs`
- [Promote stage](https://github.com/jasoncheroske/lab-os/blob/main/scripts/promote-stage.mjs): maturity gate · Advances lab maturity through allowed stages · `scripts/promote-stage.mjs`
- [Build tarball](https://github.com/jasoncheroske/lab-os/blob/main/scripts/build-lab-tar.mjs): release packager · Creates distributable lab tarball and checksum · `scripts/build-lab-tar.mjs`

### Knowledge Base

Documentation that defines architecture, governance, and operating guidance

- [Docs](https://github.com/jasoncheroske/lab-os/tree/main/docs): governance docs · Architecture, governance, runbooks, release, ADR, and reference documentation · `docs`

### Verification

Fixtures and tests that prove generation and release behavior

- [Examples](https://github.com/jasoncheroske/lab-os/tree/main/examples): fixtures · Reference minimal and governance-heavy lab instances · `examples`
- [Tests](https://github.com/jasoncheroske/lab-os/blob/main/tests/generation.test.mjs): generation checks · Automated checks for generation behavior · `tests/generation.test.mjs`

### Distribution

Packaged release artifacts and boundaries

- **Release tar**: distribution artifact · Packaged lab archive for distribution

## Connections

- lab-os → Template: seeds · Repository template defines the starting structure
- lab-os → Lab schema: governs · Schema defines the valid lab contract
- lab-os → Scripts: operates via · Scripts implement repository workflows
- lab-os → Docs: documents · Docs describe architecture and governance
- lab-os → Examples: proves with · Examples demonstrate expected instantiated labs
- lab-os → Tests: verifies with · Tests validate generation behavior
- Template → Lab instance: materializes · Template is copied into an instantiated lab
- Lab manifest → Lab instance: describes · Manifest attaches metadata to the lab instance
- Lab instance → Intent: contains · Intent captures target architecture
- Lab instance → Reality: contains · Reality captures implementation mapping
- Lab instance → Delta: contains · Delta captures gaps and mismatches
- Lab instance → Evidence: contains · Evidence captures readiness checks and ADRs
- Lab instance → Behavior: contains · Behavior captures governance policy and signoffs
- Scripts → Init lab: executes · Bootstrap script initializes lab instances
- Scripts → Validate: executes · Validation script checks against schema
- Scripts → Promote stage: executes · Promotion script advances maturity stages
- Scripts → Build tarball: executes · Packaging script builds release artifact
- Validate → Lab schema: checks against · Validation enforces the lab contract
- Promote stage → Behavior: gates by · Promotion depends on governance maturity
- Build tarball → Release tar: produces · Build creates the distributable archive
- Examples → Lab instance: mirror · Examples act as reference lab instances
- Tests → Template: regressions for · Tests exercise generation from the scaffold
- Tests → Lab schema: asserts · Tests confirm generated structure matches contract
- Docs → Lab schema: defines · Architecture docs explain the lab contract
- Docs → Behavior: guides · Governance docs define policy and maturity
- Docs → Release tar: supports · Release docs describe packaging and launch readiness
