Architecture model sidecars | RWS Architecture

On this page

Summary
Sidecar Placement
How Capabilities Are Included
Object Types
Top-Level Attributes
Version Attributes
Schedule Attributes
State Values
Provided Capability Attributes
Requirement Attributes
Modeling Workflow
Validation

Summary

Architecture roadmap metadata lives in .model.yaml sidecar files next to, or near, the human-facing Markdown note. The Markdown note remains the narrative source for architects and reviewers; the sidecar is the machine-readable source for capability dependency graphs, portal timeline views, and Gantt-style planning views.

The model is intentionally simple: start with an offering version, declare the capabilities it needs, then work downward until the chain reaches capabilities that are externally available or tracked elsewhere. The availability of an offering is derived from the latest required capability, not from a manually maintained hard timeline.

The portal and validators include sidecars automatically by scanning RWS-ARCH/**/*.model.yaml, excluding inbox, assets, templates, Obsidian configuration, reports, and dependencies. Capabilities are therefore not embedded in the Markdown note or in a central registry. Each capability comes from its own versioned sidecar file, and dependencies are connected by the id, provides.id, and requires.ref fields.

Sidecar Placement

Use the same basename as the Markdown document when the sidecar models that document directly. Offering sidecars live in the service offering catalog:


RWS-ARCH/70-togaf/offerings/clusters-as-a-service-offering.md

RWS-ARCH/70-togaf/offerings/clusters-as-a-service-offering.model.yaml

Capability sidecars currently live next to the SBB note that owns the implementation narrative, even when the sidecar models a capability rather than the SBB itself:


RWS-ARCH/70-togaf/sbb/red-hat-advanced-cluster-management.md

RWS-ARCH/70-togaf/sbb/fleet-hcp-cluster-provisioning.model.yaml

The sidecar document field must point to the Markdown note that owns or explains the modeled item. When multiple capabilities are explained by one SBB note, each capability may have its own .model.yaml file with the same document value. This keeps the dependency graph granular without forcing every capability to become a separate human-facing Markdown note.

This placement is deliberately pragmatic. A capability sidecar under RWS-ARCH/70-togaf/sbb/ means "this capability is explained by this SBB note", not "this capability is itself an SBB". If capability inventory grows beyond implementation-owned slices, introduce a dedicated capability catalog rather than overloading SBB folders indefinitely.

How Capabilities Are Included

Capabilities enter the roadmap through versioned sidecars, not through Markdown body sections. A capability sidecar normally has this shape:


kind: capability

id: capability.cluster-baseline-gitops

title: Cluster Baseline GitOps

document: openshift-gitops.md

owner: team-platform-architecture

domain: platform

organizational_domain: datacenters

versions:

  - version: 0.1.0

    label: Baseline cluster reconciliation

    state: planned

    target_window: 2026-Q3

    confidence: low

    basis: GitOps is the intended reconciliation path, but evidence still needs definition.

    adds:

      - Baseline GitOps reconciliation path for provisioned clusters.

      - Initial ownership boundary for baseline content.

    delivery:

      work_packages:

        - ref: "[wp-09-caas-platform](/vault/n/80-workpackages/wp-09-caas-platform/)"

          role: primary

          scope: Initial CLaaS baseline content and reconciliation delivery.

    provides:

      - id: cluster-baseline-gitops

        label: Cluster baseline GitOps

    requires:

      - ref: capability.dcs-cluster-runtime

        capability: dcs-cluster-runtime

        reason: GitOps control components need a runtime foundation.

The build turns this into graph nodes for the capability object and each version. Requirements become graph edges from the requiring version to the selected dependency version. If a requirement includes capability, validation confirms that the selected dependency version actually provides that capability.

For CLaaS, RWS-ARCH/70-togaf/offerings/clusters-as-a-service-offering.model.yaml is the entry point. Its requires list points to separate capability sidecars such as fleet HCP provisioning, identity access, ingress publication, GitOps baseline, observability baseline, and backup restore baseline.

Object Types

Kind	Meaning	Typical Use
`service_offering`	Consumable service version exposed to users or platform consumers.	CLaaS version that consumers can request.
`capability`	Specific feature or outcome needed by another model item.	Provision HCP clusters with virtualized workers.
`sbb`	Concrete solution building block when modeling the SBB itself is useful.	Product or platform component with its own versioned availability.
`exception`	Temporary non-target lane or exception.	Transitional production exception.

Prefer service_offering and capability first. Add sbb entries only when the SBB itself needs versioned roadmap semantics. A sidecar in RWS-ARCH/70-togaf/sbb/ can still use kind: capability; the path only indicates where the explanatory note lives.

Top-Level Attributes

Every sidecar describes one versioned roadmap object.

Attribute	Required	Allowed Values	Meaning
`kind`	Yes	`service_offering`, `capability`, `sbb`, `exception`	The model object type.
`id`	Yes	Prefix with `offering.`, `capability.`, `sbb.`, or `exception.`	Stable model identifier used by dependencies. Use lowercase letters, numbers, dots, and hyphens.
`title`	Yes	Text	Human-readable name shown in portal views.
`document`	Yes	Relative Markdown filename ending in `.md`	Markdown note that owns or explains the sidecar.
`owner`	Yes	Text	Owning team, role, or architecture group responsible for maintaining the model entry.
`domain`	Yes	Text	Architecture domain used for filtering and grouping.
`organizational_domain`	No	`datacenters`, `networking`, `platforms`, `eup`, `iam`, `security`	Organizational domain owner used for roadmap color coding and accountability views.
`status`	No	Text	Authoring or governance status, for example `draft` or `active`.
`realizes`	No	List of strings	Logical ABBs, capabilities, or architecture concepts implemented by this model object.
`versions`	Yes	List of version objects	Versioned availability and dependency records.
`related_notes`	No	List of strings	Extra Markdown notes relevant to the model object.

Version Attributes

Versions use comparable semantic versions in major.minor.patch format, for example 0.1.0 or 1.0.0. Human labels explain what the version means.

Attribute	Required	Allowed Values	Meaning
`version`	Yes	`major.minor.patch`	Machine-comparable version identifier.
`label`	Yes	Text	Short human label.
`state`	Yes	See State Values	Current availability or execution state.
`target_window`	Yes	`unknown`, `YYYY-Qn`, or `YYYY-Hn`	Expected availability window for this version or capability.
`confidence`	Yes	`low`, `medium`, `high`	Confidence in the target window.
`basis`	Yes	Text	Why this state and target window are currently believed.
`description`	No	Text	Short explanation of what this version represents.
`adds`	No	List of 1-5 short bullets	Human-facing version delta shown in portal hovers.
`schedule`	Yes	Object with `durations` and optional `start_after`	Duration-based planning input used to derive Gantt dates.
`delivery`	No	Object with `work_packages`	Work packages expected to deliver, support, or validate this version.
`timeline`	No	Object with `start` and `target` dates	Deprecated fixed planning dates; prefer `schedule`.
`provides`	No	List of provided capability objects	Capabilities or features made available by this version.
`requires`	No	List of requirement objects	Capabilities or versions that must be available first.

Use adds for concise reviewer-facing bullets that explain what becomes new in this version. Keep adds separate from provides: provides is for machine-readable dependency targets, while adds explains the version increment in plain language.

Use delivery.work_packages to connect a version to delivery scope. Gantt bars link to the primary work package when present, because the work package is the reviewable delivery unit for the block.


delivery:

  work_packages:

    - ref: "[wp-09-caas-platform](/vault/n/80-workpackages/wp-09-caas-platform/)"

      role: primary

      scope: Initial CLaaS provisioning and service readiness.

Allowed work package roles are primary, contributing, dependency, and validation.

Schedule Attributes

The schedule object is required for versions that appear in the roadmap model. It keeps the model dynamic by deriving Gantt dates from dependency availability plus the duration of each state segment.


schedule:

  start_after: 2026-06-01

  durations:

    planned: 20d

    validating: 10d

Use start_after only when a capability has an external earliest-start constraint. When omitted, the generated model starts the version after the latest required dependency is available. Durations use day values such as 10d.

Attribute	Required	Allowed Values	Meaning
`start_after`	No	`YYYY-MM-DD`	Earliest date this version can start, independent of dependencies.
`durations`	Yes	Map of state to day duration	Estimated time spent in each relevant state segment.

The generated timeline used by portal Gantt views is derived from schedule, selected requirements, and any requirement lag values. Fixed timeline fields are retained only as a migration escape hatch and should not be used for new roadmap entries.

State Values

State is about availability or execution, not strategic lifecycle.

State	Meaning
`not_started`	Identified, but no delivery or implementation work has started.
`planned`	Accepted into planning, but not materially underway.
`in_progress`	Implementation, configuration, or design work is underway.
`validating`	Implemented enough for controlled validation or evidence collection.
`available`	Available for the dependency use described by this version.
`blocked`	Cannot progress until a blocker is removed.
`paused`	Deliberately stopped or deferred.
`retired`	No longer valid for active dependency use.

Use available only when downstream dependencies can rely on this version or capability.

Provided Capability Attributes

Each item under provides describes a feature or capability exposed by the version.

Attribute	Required	Allowed Values	Meaning
`id`	Yes	Lowercase identifier	Stable capability identifier within this version, for example `provision-hcp-clusters-with-virtualized-workers`.
`label`	Yes	Text	Human-readable capability name.
`description`	No	Text	What the capability provides and why it matters.

Keep provides small. Add only capabilities that another offering, capability, or SBB needs to depend on.

Requirement Attributes

Each item under requires points to another model object and optionally to a specific provided capability.

Attribute	Required	Allowed Values	Meaning
`ref`	Yes	Existing sidecar `id`	Model object being depended on.
`version_constraint`	No	Semver constraint	Acceptable version range, for example `>=0.1.0 <1.0.0`. Defaults to any version when omitted.
`capability`	No	Capability `id` from the target version's `provides` list	Specific capability needed from the dependency.
`blocks`	No	`availability`, `production`, `scale`, `target`, `none`	What is blocked if the requirement is not available. Defaults to `availability`.
`lag`	No	Quarter lag like `0q` or `1q`	Delay after dependency availability before this version can be treated as available.
`reason`	Yes	Text	Why the requirement exists.

Modeling Workflow

Model top down:

Start with the offering version, for example CLaaS 0.1.0.
List the capabilities the offering needs before it can be available.
Put each modeled capability in its own .model.yaml file so the graph can show it as a separate dependency node.
For each capability, model the provider capability and its own requirements.
Stop when the chain reaches a capability treated as externally available or tracked elsewhere.
Add target_window and confidence to dependencies so the portal can plot the chain.

The timeline should derive offering availability from the latest blocking requirement, plus any explicit lag.

Validation

CI validates sidecars with .schemas/capability-model.schema.json and .scripts/validate-capability-model.js.

Validation checks include:

sidecar YAML shape and allowed field values
unique model version IDs
semver-compatible versions and constraints
resolvable requirement references
required reason text on blocking requirements
high-confidence forecasts not being assigned to immature states
valid timeline date shape and target not earlier than start

The portal graph is generated from the sidecars during npm run build:model.