Archally Blueprint Schema

YAML-based schema for digital system modeling — a domain-first multi-method specification format covering domain design, business rules, value streams, governance, and organizational alignment in a single machine-readable format.

The Problem

Architecture knowledge fragments across wikis, slide decks, whiteboard photos, Confluence pages, and tribal memory. When a team needs to make a change decision — split a service, add a new context, evaluate a migration — they spend days reconstructing context that should already be explicit. Documentation drifts from code within weeks. New team members spend months absorbing knowledge that could be structured and navigable.

The cost is not missing documentation. It is fragmented truth.

The Approach: System Cartography

Archally treats software architecture the way cartographers treat territory — by surveying it methodically, representing it at multiple scales, layering concerns into separate planes, and marking what remains unknown.

What is a Blueprint?

A blueprint is a single formal model of a digital system — one source that captures what the system does, why it exists, and how it's proven. It replaces scattered artifacts with a structured, validated, version-controlled specification:

• Design Plane (what and how): bounded contexts, aggregates, commands, events, queries, business rules, data models, stories, UI screens, quality attributes
• Governance Plane (why and proof): goals, risks, decisions, test cases, capabilities, value streams, milestones, organizational ownership
• Metamodel (shared vocabulary): typed ID references, versioning, cross-layer traceability

One model, many outputs

A single blueprint can drive multiple generated artifacts — OpenAPI specs, AsyncAPI contracts, PRD documents, Event Storming boards, capability maps, context diagrams — all from the same source. When the model changes, every output stays consistent. No semantic drift between your documentation, your contracts, and your architecture diagrams.

Built for humans and AI agents

Every schema field carries a machine-readable description. AI agents consume blueprints as structured domain context via MCP servers — not retrieval over documents, but deterministic graph queries against a validated formal model. The same blueprint that onboards a new team member also grounds an AI agent's reasoning about the system.

Local-first, version-controlled

Blueprints are plain YAML files in your Git repository. No cloud upload required, no vendor platform, no infrastructure. Your domain models — which encode your bounded contexts, business rules, competitive decisions, and organizational structure — stay under your control. Validate locally, review in pull requests, deploy with your existing workflow.

Quick Start

1. Create a .blueprint/v2.8/ directory in your project:

my-project/
  .blueprint/v2.8/
    blueprint.yaml
    orders/
      concepts.yaml
      domain.yaml

2. Write a minimal blueprint (two files, one concept):

# blueprint.yaml
version: "1.0.0"
name: "My Service"

# orders/concepts.yaml
version: "1.0.0"
concepts:
  - id: CN001
    name: "Order"
    stereotype: aggregate-root
    description: "A customer's purchase request."

3. Validate. Clone this repository once, then point the validator at your model:

git clone https://github.com/Archally/blueprint-schema.git
cd blueprint-schema && npm install
npm run validate -- ../my-project/.blueprint/v2.8

Architecture

METAMODEL (cross-cutting) — typed IDs · versioning · evidence chains · ownership · code references

block-beta
  columns 2

  block:design
    columns 1
    dh["DESIGN PLANE — What & How"]
    dp["Slower change · concrete · higher epistemic completeness"]

    block:cs
      columns 1
      cs_h["concepts.yaml"]
      block:cs_e
        Concept
        Actor
        Enumeration
        Association
      end
    end

    block:ds
      columns 1
      ds_h["domain.yaml"]
      block:ds_e
        Command
        Event
        Query
        Document
        Error
        Question
      end
    end

    block:rs
      columns 1
      rs_h["rules.yaml"]
      block:rs_e
        Rule
        Transition
      end
    end

    block:ss
      columns 1
      ss_h["story.yaml"]
      block:ss_e
        Story
        Activity
        us2["User Story"]
        uc2["Use Case"]
      end
    end

    block:as2
      columns 1
      as_h["arch.yaml"]
      block:as_e
        Context
        Service
        Contract
        Dependency
      end
    end

    block:ms
      columns 1
      ms_h["models.yaml"]
      block:ms_e
        Model
      end
    end

    block:qs
      columns 1
      qs_h["quality.yaml"]
      block:qs_e
        Metric
        KPI
        SLO
        SLA
        Security
        Compliance
        Resilience
      end
    end

    block:uis
      columns 1
      us_h["interactions.yaml"]
      block:us_e
        Screen
        Action
        Navigation
      end
    end

    block:dys
      columns 1
      dy_h["dynamics.yaml"]
      block:dy_e
        Parallelism
        Ordering
        rc2["Race Condition"]
      end
    end

    block:rgs
      columns 1
      rg_h["infrastructure.yaml"]
      block:rg_e
        Resource
      end
    end
  end

  block:governance
    columns 1
    gh["GOVERNANCE PLANE — Why & Proof"]
    gp["Faster change · exploratory · lower epistemic completeness"]

    block:mos
      columns 1
      mo_h["motivation.yaml"]
      block:mo_e
        Goal
        ng2["Non-Goal"]
        Risk
        Assumption
        to2["Trade-Off"]
        Inquiry
      end
    end

    block:des
      columns 1
      de_h["decisions.yaml"]
      block:de_e
        Decision
        bd2["Business Decision"]
      end
    end

    block:cas
      columns 1
      ca_h["capability.yaml"]
      block:ca_e
        Capability
      end
    end

    block:tcs
      columns 1
      tc_h["test-cases.yaml"]
      block:tc_e
        tc2["Test Case"]
        ff2["Fitness Function"]
      end
    end

    block:ors
      columns 1
      or_h["organization.yaml"]
      block:or_e
        Party
        Department
        Team
      end
    end

    block:ros
      columns 1
      ro_h["roadmap.yaml"]
      block:ro_e
        Milestone
      end
    end

    block:vss
      columns 1
      vs_h["value-stream.yaml"]
      block:vs_e
        vs2["Value Stream"]
      end
    end
  end

  style dh fill:#2b6cb0,color:#fff,stroke:none
  style dp fill:#2b6cb0,color:#cbd5e0,stroke:none
  style gh fill:#2f855a,color:#fff,stroke:none
  style gp fill:#2f855a,color:#c6f6d5,stroke:none
  style cs_h fill:#1e4e8c,color:#fff,stroke:none
  style ds_h fill:#1e4e8c,color:#fff,stroke:none
  style rs_h fill:#1e4e8c,color:#fff,stroke:none
  style ss_h fill:#1e4e8c,color:#fff,stroke:none
  style as_h fill:#1e4e8c,color:#fff,stroke:none
  style ms_h fill:#1e4e8c,color:#fff,stroke:none
  style qs_h fill:#1e4e8c,color:#fff,stroke:none
  style us_h fill:#1e4e8c,color:#fff,stroke:none
  style dy_h fill:#1e4e8c,color:#fff,stroke:none
  style rg_h fill:#1e4e8c,color:#fff,stroke:none
  style mo_h fill:#1a5c35,color:#fff,stroke:none
  style de_h fill:#1a5c35,color:#fff,stroke:none
  style ca_h fill:#1a5c35,color:#fff,stroke:none
  style tc_h fill:#1a5c35,color:#fff,stroke:none
  style or_h fill:#1a5c35,color:#fff,stroke:none
  style ro_h fill:#1a5c35,color:#fff,stroke:none
  style vs_h fill:#1a5c35,color:#fff,stroke:none

The Design Plane captures established knowledge — domain vocabulary, rules, operations, and architecture that changes deliberately. The Governance Plane captures evolving knowledge — goals, risks, assumptions, and decisions that shift as understanding deepens. Evidence chains (discovery_stage, certainty, evidence[]) track how governance entities mature from hypothesis to confirmed.

See the full schema reference for ID patterns, traceability map, and schema evolution history.

Usage Modes

Blueprint Schema supports different modeling approaches depending on your situation:

Greenfield — New System

Start from scratch with a Minimal Viable Blueprint (MVB):

1. Identify bounded contexts and aggregate roots
2. Model the primary command → event causal chains
3. Add rules, stories, and test cases for the happy path
4. Iterate: extend with value objects, error paths, governance, quality

Start small (5-20 entities), validate, then grow through phases. See the Modeling Guide for phase details, decision trees, and anti-patterns. If you need a non-technical capture guide for workshops, business users, or AI handoff, start with the Blueprint Handoff Atlas and its umbrella PDF.

Brownfield — Existing System

Model an existing codebase by analyzing what's already built:

1. Enumerate domain aggregates from code directories
2. Assign DDD roles (aggregate root, entity, value object) from behavioral signals
3. Group CRUD variants into semantic operations
4. Model the discovered structure, linking entities to source via code_refs

The code is the source of truth for the design plane. Specs describe intent; code describes reality. See the Modeling Guide for the full Phase 0 protocol.

Iterative Modeling

Blueprints grow through four phases:

Each phase has entrance criteria and reports which generators (OpenAPI, AsyncAPI, PRD, Event Storming) can produce useful output from the current model.

graph LR
    P1["Phase 1\nMVB\n5-20 entities"]
    P2["Phase 2\nDetail\n20-80 entities"]
    P3["Phase 3\nGovernance\n80-200 entities"]
    P4["Phase 4+\nDynamics\n200+ entities"]

    P1 -->|"+ value objects\n+ error catalog\n+ models"| P2
    P2 -->|"+ arch contracts\n+ quality SLOs\n+ value streams"| P3
    P3 -->|"+ parallelism\n+ migrations\n+ full tests"| P4

    style P1 fill:#2b6cb0,color:#fff
    style P2 fill:#2b6cb0,color:#fff
    style P3 fill:#2f855a,color:#fff
    style P4 fill:#4a5568,color:#fff

Knowledge Gathering

Use blueprints as a discovery tool:

• Questions (QN001) model what knowledge a domain slice should provide. Unanswered questions (answered_by: []) reveal domain gaps — the most valuable artifact for backlog prioritization.
• Inquiries (INQ001) capture temporary governance concerns during analysis.
• Evidence chains on goals, risks, and decisions link assertions to supporting data — so governance claims are substantiated, not asserted.

Best Practices

1. MVB-first, not completeness-first. Capture intent, produce a small coherent blueprint, iterate. A focused 15-entity model that validates cleanly beats a 200-entity hairball.

2. Multiple small files over monoliths. The loader merges all files of the same schema type within a slice. Seven 100-line files reveal structure better than one 700-line file.

3. Single authoritative location. Every fact has one source: causal links live in domain.yaml (produces/reacts_to), story steps are a convenience view validated against domain links.

4. Business names in the model, technical names in code_refs. Blueprint operations use business language; code_refs bridge to the implementation.

5. Defer aggressively. Explicitly note what's deferred and why. Quality metrics, UI screens, and org hierarchy are Phase 3 — don't model them before the domain skeleton is stable.

6. Convention over enforcement. Prefer documented conventions with validator warnings over hard schema constraints for emergent patterns.

For the full set of practices, anti-patterns, decision trees, and reference direction rules, see the Modeling Guide. For file naming, ID conventions, and directory layout, see File Conventions.

Schema Files

Full entity ID patterns, traceability map, and schema evolution history: Schema Reference. File naming and layout rules: File Conventions.

Browse the schemas by version — each schema/ version folder has its own README index (Design / Governance planes + the cross-cutting metamodel and migration schemas).

Read the schema without the JSON — the generated Blueprint Schema Atlas projects the schema into a human-readable layer map, entity catalog, relationship map, and a structural changelog. It is regenerated from schema truth (never hand-edited), so it cannot drift from the metamodel.

Capture blueprint knowledge without reading the schema — the Blueprint Handoff Atlas explains how non-technical contributors should describe entities, relations, processes, screens, risks, and other layer knowledge so a technical person or AI agent can transform it into YAML. For workshop/offline use, see the committed PDF set.

Tools

Three tools ship with the schema — validate, build models, and check semantics:

They run from a clone of this repository. npm install is enough for the validator, which is plain
JavaScript and carries the schemas with it; the model builder and the semantic checker are
TypeScript and need npm run build first.

Validator

Schema validation (Ajv, draft-2020-12) + cross-file reference integrity + gap warnings.

npm run validate -- .blueprint/v2.8

See tools/validator/README.md for options and exit codes.

Model Builder

Loads blueprint YAML files and produces a typed in-memory graph — 55 entity types and 43 relation types. Available as a library and as a CLI that writes model.json.

# CLI - produce model.json
node tools/model-builder/dist/cli.js .blueprint/v2.8 --output model.json --pretty

# Library - import in TypeScript, from a workspace or a `file:` dependency on this clone
import { buildBlueprintModel, loadFromDirectory } from '@archally/blueprint-schema/model';

See tools/model-builder/README.md for API, type definitions, and architecture.

Semantic Checker

Configurable rule engine that catches modeling issues schema validation cannot detect. Extensible via custom RuleDefinition functions and .blueprint-lint.yaml configuration.

npm run check -- .blueprint/v2.8

Ships with 93 built-in rules (3 error, 61 warn, 29 info):

activity-fork-without-gateway · activity-steps-reverse-causal-edge · activity-steps-without-causal-edge · activity-without-entry-operation · aggregate-root-signals · assumption-unplaced · broker-ref-target-not-a-broker · capability-kind · capability-nested-deeper-than-two-levels · capability-realized-nowhere · contract-broker-id-superseded · contract-operation-missing-channel-address · contract-operation-missing-exchange · dangling-relation-endpoint · decision-asserted-without-evidence · decision-option-without-pros-cons · dependency-direction-disagreement · dispatch-with-exchange · empty-context · environment-config-key-not-declared · environment-named-not-declared · event-placed-with-producer-capability · event-transport-without-contract · events-with-produces · evidence-source-credentials · exchange-missing-payload · feature-user-stories-exclusive · feature-user-stories-mismatch · fitness-function-unattached · goal-not-advanced · goal-requires-cycle · implementation-as-is-without-code-refs · implementation-to-be-with-code-refs · imports-cycle · imports-target-not-library · inprocess-consume-without-provide · inprocess-dispatch-without-provider · inprocess-provide-without-consume · inprocess-reaction-unreached · kpi-without-metric · leverage-point-no-address · leverage-point-no-strategic-intent · message-channel-mismatch · message-queue-unread · missing-causal-links · missing-exchange-binding · model-without-purpose · model-without-represents · nav-via-action-screen-disagrees · objective-without-measurement · operation-exposed-by-many · operation-outside-every-contract · operation-realizes-two-capabilities · org-interaction-diverges-from-architecture · org-interaction-underived · org-interaction-unverifiable · orphan-entities · owner-name-matches-declared-unit · party-parts-disagree · payload-model-unbound · payload-schema-unresolved · process-end-state-unattached · process-end-state-unreachable · process-listed-order-against-causality · process-starts · requirement-confirmed-without-evidence · requirement-unverified · requirement-without-objective · restated-coupling · sent-event-without-receiver · service-system-is-an-organization · service-without-system · shared-document-read-without-writer · shared-document-write-without-reader · shared-store-without-common-resource · slo-without-metric · story-without-event · test-case-act-not-validated · test-case-given-carries-notes · translation-target-not-internal · unanswered-questions · unbound-operation · unbound-question · undeclared-exchange · undescribed-event · unevidenced-dependency · untested-rules · use-case-step-action-operation-disagrees · use-case-step-action-screen-disagrees · user-story-use-case-back-reference · user-story-without-acceptance-criteria · uses-restates-contract · uses-target-is-library

See tools/semantic-checker/README.md for rule reference, configuration, and custom rule API.

Schema Atlas

Generates the Blueprint Schema Atlas — a human-readable, regenerable projection of the JSON Schema (layer map, entity catalog, relationships, examples, structural changelog) with provenance on every page.

npm run atlas          # regenerate docs/schema-atlas/**
npm run atlas:check    # drift check (CI-friendly)

See tools/schema-atlas/README.md for the overlay contract, fail/warn/skip policy, and governance.

Blueprint Handoff Atlas

Non-technical handoff guides for capturing Blueprint knowledge in plain language before it is transformed into YAML.

npm run guides:pdf      # regenerate docs/handoff-guides/pdf/**
npm run guides:check    # drift check for committed PDFs

Start with the umbrella guide, the umbrella PDF, or browse the full PDF directory.

Editor setup

Opened as a folder in VS Code, this repository's .vscode/ settings give every blueprint file kind
and every contract kind its own icon (Material Icon Theme)
and validate blueprint files against the schema (YAML).
VS Code offers to install both extensions.

To work on your own model beside this repository in one window, start from the workspace template
.vscode/blueprint-schema.code-workspace. In a
multi-root window VS Code reads the icon settings and yaml.schemas from the workspace file, not
from each folder's .vscode/settings.json, so the template carries them.

1. Set the second folder's path to the repository that holds your product's .blueprint/ model.
   A relative path resolves against the workspace file's location: the placeholder ../../my-project
   is a my-project clone beside this one, as in the Quick Start. To keep this clone unchanged, copy
   the template elsewhere first and set both folders' paths.
2. Open it with File > Open Workspace from File.

If your team already has a .code-workspace file, copy the template's settings entries
(workbench.iconTheme, yaml.schemas and the two material-icon-theme.* keys) into it and name this
repository's folder blueprint-schema, because the yaml.schemas paths start with that name.

An entry for the same file name in your user material-icon-theme.files.associations wins over the
workspace one, so keep such an entry identical or remove it.

AI agent kit

The repository carries a blueprint-modeling kit for AI coding agents: a blueprint-modeler agent,
fifteen method skills and two commands, /blueprint-new and /blueprint-check-all, for Claude
Code, Codex and Cursor. It needs no Archally CLI and no MCP server. Open this folder in your agent's
host after npm install and npm run build; docs/ai-agent-kit.md has the
quick start for each host, how to check that it works, and how to use the kit in another project.

Example

A working e-commerce example with 3 bounded contexts (catalog, orders, payments) is included in examples/ecommerce/. Run npm run validate:examples to verify it.

Versioning

This package follows SemVer:

• Major (3.0.0): breaking schema changes
• Minor (2.7.0): new optional fields or entity types
• Patch (2.6.1): documentation, clarification, validator fixes

Ecosystem

Blueprint Schema is the open foundation of the Archally platform.

Archally's approach: One formal model drives everything. Instead of maintaining separate documents for architecture, contracts, governance, and onboarding — teams build one blueprint that generators consume to produce OpenAPI specs, AsyncAPI contracts, PRD documents, Event Storming views, and more. The model is the single source of truth; generated artifacts never drift because they're derived, not hand-maintained.

For AI-augmented teams: Archally MCP servers expose blueprint models as structured grounding for AI agents — deterministic graph queries against a validated domain model, not retrieval over unstructured documents. Agents get typed entities, traced relationships, and governance constraints at inference time. The same model that serves human understanding serves machine reasoning.

The schema itself is Apache 2.0-licensed and can be used independently of Archally tooling. The value-add reference tooling (model-builder, semantic-checker, renderer, schema-update) is source-available under the Functional Source License - free for internal, educational, and professional-services use, but not for building a competing product. See License.

Archally Pro

Commercial tools that consume this schema — available at archally.pro:

Contributing

Issues and discussions are welcome. For schema change proposals, please open an issue describing the use case before submitting a PR — schema changes affect all downstream consumers. Contributions require a DCO sign-off (git commit -s) and are accepted under the terms in CONTRIBUTING.md.

License

This repository is dual-licensed — see LICENSE for the authoritative map. Copyright 2026 Adam Walkowski.

For a commercial license covering a Competing Use, contact [email protected]. "Archally" and "Blueprint" are trademarks — see TRADEMARKS.md.