Way of Working — RWS Architecture Vault

🛠️ Way of Working

How We Document, Decide, and Not Make a Total Mess

This document explains how the RWS Architecture Vault works, what goes where, and how notes evolve over time. If you follow this, the vault stays clean. If you ignore it, the vault quality degrades quickly.

Vault landing page: <span class="wikilink wikilink-unresolved" title="unresolved: ../index">RWS Architecture Vault</span>.

1. Purpose of the Vault

The vault is the canonical source of truth for:

• how the RWS platform works
• why it evolved the way it did
• what decisions shaped it
• what facts it depends on
• what external sources influence us

It is not a wiki, not a dumping ground, and not optional.

Everything in the vault must be:

• structured
• validated
• linkable
• readable
• justified

This is enforced through CI. If your note fails validation, fix the note before merge.

1.1 Quick Workflows (Start Here)

If you do not want to read the full document first, start with these workflow cards:

• New capability -> finalized architecture
• Change existing architecture -> deprecate safely
• Draft architecture first -> refine incrementally
• Architecture promotion checklist
• Fact definition and boundary

Then return here for full governance detail.

2. Folder Structure (The Map)

The vault is organized into clear, rigid domains:

.config/           # Quartz config overrides

.schemas/          # JSON schemas (frontmatter validation) at repo root

.scripts/          # CI validators at repo root

RWS-ARCH/

  00-inbox/        # raw ideas, drafts, unvalidated junk

  10-topics/       # investigations + knowledge topics

  20-architecture/ # stable system designs

  30-decisions/    # ADRs (architecture decisions)

  40-facts/        # permanent truths + definitions

  50-sources/      # summaries of vendor/external material

  60-principles/   # cross-domain principles that constrain architecture

  70-togaf/        # TOGAF view (ABB/SBB mapping notes)

  80-workpackages/ # implementation work package view

  assets/          # diagrams, vendors, rendered SVGs, PDFs

  _templates/      # templates for all note types

2.1 00-inbox/ — The Chaos Buffer

This is the only place where mess is allowed.

Use it for:

• random drafts
• meeting notes
• raw imports
• “just thinking out loud”
• quick scratch notes (not validated like real notes)

But nothing should live here. If your idea is older than 2 weeks in 00-inbox/, you’ve abandoned it. Archive it, promote it, or delete it.

3. Templates (Use the Right Damn One)

Every note must use a matching template from _templates/.

If you're unsure which template to use, use this rule of thumb:

“If I don’t know what the hell this is yet → topic-investigation.md.”

4. Content Types (The Core Set)

Topic Naming Rules

To keep investigation notes clearly separated from knowledge notes, all Topic files must follow strict naming rules:

Investigation Topics

Files must end with -investigation.md.

Format (folder/domain alignment is CI-enforced for validated types): topic-<slug>-investigation.md

Examples: topic-storage-ceph-investigation.md topic-bgp-peering-investigation.md

Knowledge Topics

Files must NOT have the investigation suffix.

Format (folder/domain alignment is CI-enforced for validated types): topic-<slug>.md

Examples: topic-storage-backend.md topic-networking-topology.md

Work Package Naming

When a topic tracks a work package, use the full prefix:

Format: topic-work-package-<id>-<slug>.md

Examples: topic-work-package-17-devops-acceleration.md topic-work-package-10-finops-governance.md

Why This Matters

• File naming shows maturity immediately.
• CI validators enforce correctness.
• Promotion from investigation -> knowledge becomes explicit.

4.1 Topic — Investigation

Folder: 10-topics/ Template: _templates/topic-investigation.md Frontmatter: type: topic, subtype: investigation Filename rule: Must end with -investigation.md.

Use when:

• you are researching
• comparing options
• collecting problems
• exploring unknowns
• forming hypotheses
• you don’t know the final shape yet

An investigation topic must contain:

• a clear summary / problem statement
• context (what triggered this, where it lives in the platform)
• active work (what you’re actually doing)
• open questions
• links to related topics / ADRs / architecture notes

You close an investigation when:

• the main questions are answered
• the content is either obsolete or distilled into knowledge / ADR / architecture

Closing an investigation topic means setting it's status to "closed".

4.2 Topic - Knowledge

Folder: 10-topics/ Template: _templates/topic-knowledge.md Frontmatter: type: topic, subtype: knowledge Filename rule: Must NOT include the -investigation.md suffix.

Created when an investigation matures and:

• the unknowns are mostly gone
• the content becomes reusable knowledge
• it explains something others need to understand
• it no longer changes every five minutes

Use topic-knowledge when you’d happily point a new engineer to it to explain:

• “What is our storage backend setup?”
• “How do we use Ceph in this platform?”
• “What’s our basic approach to AI workloads?”

These notes should:

• describe current state
• link to ADRs that shaped it
• link to architecture notes that depend on it
• be kept reasonably up to date (not perfect, just not obviously wrong)

4.3 ADR — Architecture Decision

Folder: 30-decisions/ Template: _templates/decision.md (MADR-style) Frontmatter: type: adr ID, title, status, dates

Create an ADR when:

• a non-trivial choice must be made
• there are alternative options with trade-offs
• the outcome affects the architecture, operations, or risk profile
• future-you or future-someone will absolutely ask “why did we pick this?”

Characteristics of a good ADR:

• Atomic: one decision per ADR. No kitchen-sink “everything about networking.”
• Traceable: links to the topic(s) that fed it and the architecture it impacts.
• Permanent: ADRs are never deleted, only superseded.
• Honest: explicitly lists pros, cons, rejected options, and consequences.

File naming convention (required):

• 30-decisions/<area>/adr-001-storage-backend.md
• 30-decisions/<area>/adr-002-networking-physical-connectivity.md

Rules:

• filename pattern must be adr-ID-SLUG.md (lowercase slug)
• ID in filename must exactly match frontmatter id
• frontmatter title must start with ADR-ID (for navigation clarity)

Where OpenShift runtime decisions are grouped under the platform hierarchy, use 30-decisions/platform/ with domain: platform.

4.4 Architecture Note

Folder: 20-architecture/ Template: _templates/architecture.md Frontmatter: type: architecture

Use an architecture note when:

• a design is mature enough to be explained to others
• diagrams exist or are being stabilized
• implementers or operators need a canonical description
• multiple ADRs and topics converge into a coherent subsystem

Architecture notes should:

• explain *what* the system/subsystem is
• show *how* it fits into the wider platform
• link back to ADRs and topics that justify design choices
• include ## Applicable Principles (CI-enforced for type: architecture under 20-architecture/) and link 60-principles/ notes (or document justified exceptions)
• use "Principles Coverage" on index/landing pages (type: index) to map domain scope to relevant principles
• contain diagrams in assets/diagrams/... with rendered versions in assets/rendered/...

These are not meeting notes. This is the “what we actually built / will build” description.

4.4.1 Domain Assignment (CI-Enforced)

For type: topic, type: architecture, and type: adr, CI enforces folder/domain alignment:

• 10-topics/{domain}/... must use domain: {domain}
• 20-architecture/{domain}/... must use domain: {domain}
• 30-decisions/{domain}/... must use domain: {domain}

OpenShift runtime content now lives in the Platform hierarchy, so runtime topics, architecture notes, and ADRs in those paths use domain: platform.

Use domain: openshift for OpenShift-focused references/summaries/index facets that are outside those enforced path rules.

4.5 Principles

Folder: 60-principles/ Template: _templates/principle.md Frontmatter: type: principle

Use a principle note when:

• it constrains or guides multiple domains (cross-domain)
• architecture notes should explicitly show how they adhere to it
• domain-specific details belong in "Per-Domain Implementation" subsections

Principle notes must:

• state intent clearly (what this principle optimizes for)
• list scope and applicability (including applies_to_domains)
• provide per-domain guidance in a single note

Principles in other notes

• Use a ## Applicable Principles section in architecture notes and topic knowledge notes to list the principles that constrain that note (CI-enforced for type: architecture under 20-architecture/ and type: topic + subtype: knowledge under 10-topics/).
• Use a ## Principles Coverage section in index notes (domain landing pages) to describe which principles apply in that domain and link to them.

4.6 Facts

Folder: 40-facts/ Template: _templates/fact.md Frontmatter: type: fact, validated via fact.schema.json

A fact is a stable, durable truth about the platform.

Facts are not "anything we wrote down".

Important boundary:

• ADR = why we decided (context, alternatives, consequences).
• Fact = stable truth used as reusable constraint across notes.

An accepted ADR does not automatically become a fact note.

Use fact-definition-and-boundary as the canonical decision aid for when to promote information into 40-facts/.

Use a fact note when:

• it’s true across the platform
• it changes rarely
• it’s foundational to multiple designs and decisions
• many notes need to point at it instead of rephrasing it

Examples:

• “Ceph is the backing storage for all OpenShift clusters.”
• “Identity and RBAC are centrally managed by X.”
• “All customer workloads must be isolated per tenant via Y.”

Facts can evolve (you add more detail over time) but should not flip-flop. When a fact changes meaningfully, either:

• update it and note it in a revision history section, or
• mark it deprecated and create a new, corrected fact.

4.7 Sources

Folder: 50-sources/ Template: (e.g. _templates/source.md if/when you add one)

A source is a human-written summary of external material:

• vendor PDFs and “high level design” docs
• standards and specifications
• contracts and SOWs
• external architecture references

Patterns:

• Raw file (PDF, PPT, etc.) → assets/vendors/...
• Human summary → 50-sources/<vendor>-<thing>.md
• Then referenced from topics, ADRs, architecture notes, and facts.

This keeps vendor sludge out of your main content while still making it discoverable and referenced.

5. Lifecycle (Promotion Path of Knowledge)

Roughly, things evolve like this:

Topic-Investigation

        ↓

Topic-Reference

        ↓

    (sometimes)

        ↓

        ADR

        ↓

 Architecture

        ↓

       Fact

Do Not Delete Notes — Change Status Instead

The vault preserves architectural history.

You do NOT delete:

• old investigations
• superseded ADRs
• outdated architecture notes
• deprecated facts

Instead, update the status field (by type, as enforced by schemas):

• topic investigations → closed
• topic knowledge notes -> deprecated (when no longer current)
• principles → deprecated
• architecture notes → archived
• facts -> deprecated
• ADRs → superseded

Deleting removes traceability and breaks link history. Changing status preserves history without cluttering active navigation.

5.1 Investigation -> Knowledge

Promote when:

• the main questions are answered
• you’re explaining more than exploring
• others will need this info again
• the note is no longer “live debugging” the world

Usually this means:

• keep the investigation as a historical trail (status: closed)
• create or update a topic-knowledge with clean, stable information
• link the knowledge note back to the important investigation(s) if useful

5.2 Knowledge -> ADR

Promote when:

• a decision must be made
• options exist with meaningful trade-offs
• the choice changes architecture, operations, or risk

The knowledge topic provides context, the ADR captures the choice and consequences.

5.3 ADR → Architecture

Promote into architecture when:

• ADRs define the structure of a system/subsystem
• diagrams and flows start to stabilize
• people need “the full picture” in one place

Architecture notes aggregate what we decided and how it fits together.

5.4 Architecture → Fact

Some statements inside architecture notes deserve to be pulled out as standalone facts when:

• they are platform-wide truths
• you want a single canonical statement to point others at

You then:

• move that statement into 40-facts/<something>.md
• link from architecture / topics / ADRs to that fact note

6. Writing Rules (Non-Optional)

6.1 Valid frontmatter only

Frontmatter is validated by CI using JSON Schema. If it fails, your PR fails. Fix the frontmatter — don’t hack around it.

6.2 Use templates

Templates exist to avoid chaos. If your note doesn’t fit any template, your note is probably wrong, not the system.

6.3 No placeholders

Finalized notes must not contain:

• TODO
• TBD
• REPLACE_ME
• <some placeholder text>

The validator will yell at you. And it should.

If the content is not ready, keep it in 00-inbox/ or mark the status clearly and don’t pretend it’s done.

6.4 Everything must link

If a note has zero inbound links, that’s suspicious:

• Either it’s a draft → move to 00-inbox/
• Or you forgot to link to it from somewhere meaningful
• If it’s truly obsolete and only lives in 00-inbox/, it may be deleted

Deletion is only allowed in RWS-ARCH/00-inbox/. Everywhere else, keep the note and update status (see section 5).

6.5 Diagrams

Rules:

• Source diagrams: assets/diagrams/...
• Rendered images (SVG/PNG): assets/rendered/...
• Diagrams linked from architecture notes and topics via wikilinks or markdown image links.

6.6 Vendor docs

Rules:

• Raw PDFs/etc: assets/vendors/...
• Human summary: 50-sources/...
• Other notes link to the summary, not directly to the PDF, unless you really need to.

6.7 Logical structure, not diary mode

This vault is not:

• your personal thought stream
• a chronological dump
• “2025-11-12-storage-thoughts-3-final-FINAL.md”

Put things where they belong:

• exploratory → 10-topics (investigation)
• stable explanation -> 10-topics (knowledge)
• choice → 30-decisions (ADR)
• system → 20-architecture
• durable truth → 40-facts
• external summary → 50-sources

7. Example: How a Note Evolves

A concrete example using storage:

Step 1 — You’re confused about storage

Create:

• 10-topics/storage/topic-storage-backend-investigation.md (investigation)

Capture:

• what you don’t know
• what you’re testing
• options you’re considering
• open questions

Step 2 — You figure out the essentials

Create:

• 10-topics/storage/topic-storage-ceph-investigation.md (investigation)

Capture:

• how Ceph is used
• pools, tenants, access patterns
• operational constraints
• links to relevant vendor docs in 50-sources/ or assets/vendors/

Step 3 — A real decision is needed

Create:

• 30-decisions/storage/adr-001-storage-backend.md

Capture:

• context and problem statement
• decision drivers
• considered options
• chosen option
• pros/cons and consequences

Link back to:

• topic-storage-backend
• topic-storage-ceph

Step 4 — Architecture now depends on this

Update:

• 20-architecture/platform/openshift-concept-overview.md

Capture:

• how the storage backend fits into the overall platform
• which clusters depend on it
• integration points with ODF, backup, etc.
• diagrams that show the layout

Step 5 — Some truths become universal

Update or create:

• 40-facts/storage-backend.md (for example)

Capture:

• “The RWS platform uses a dedicated Ceph platform (ODF external mode) as the primary storage backend for OpenShift clusters.”
• other stable truths that many notes should reference

8. Governance Baseline and Trend Updates

The vault publishes governance trend deltas in CI from .reports/visibility-dashboard.* using baseline values from .vault/governance-baseline.json.

When to update baseline values:

• after a planned structural milestone is merged (not during incidental content PRs)
• when you intentionally reset the target operating baseline for governance health

How to update safely:

1. Run npm run validate:all and confirm CI-equivalent checks are clean.
2. Use current visibility metrics as the candidate baseline values.
3. Update .vault/governance-baseline.json in a dedicated governance/scaffolding PR.
4. Mention why the baseline is being reset in the PR description.

Do not casually overwrite the baseline in normal content PRs; that destroys trend signal.

9. Collaborative Pull Request Workflow

Use small branches and focused PRs so review stays useful.

Before opening a PR:

• run npm run sync:eira and commit any generated alignment changes
• run npm run validate:all
• run npx markdownlint --config .markdownlint.yaml --ignore-path .markdownlintignore "RWS-ARCH/**/*.md"
• run npm run build:portal

During review:

• the Forgejo CI Gate is blocking and must be green before merge
• CI uploads .reports/ so reviewers can inspect validator outputs
• the job summary contains the consolidated CI Review Report
• comment /review on the PR when an OpenCode review report is useful
• resolve blocking review findings before merge; discuss non-blocking findings explicitly

10. Final Words

This vault is designed to be:

• structured
• validated
• linkable
• navigable
• automated
• sane

Follow this Way of Working and everything stays clean.

Ignore it, and you create entropy. CI will fail the PR until the issues are resolved.

Your move.