Skip to main content

Architectural Decision Guide

"Every architectural decision belongs somewhere. Constitutional governance begins by placing each decision in the correct layer."

Purpose

This guide defines how architectural decisions are governed throughout the ZAYAZ platform.

Not every architectural change belongs in a Constitution.

Not every implementation decision requires an Architectural Decision Record (ADR).

This guide establishes the decision hierarchy that preserves architectural clarity while allowing continuous evolution.

The Four Layers of Governance

Architectural decisions belong to one of four governance layers.

                    Constitution
                          │
                          ▼
             Constitutional ADR (CADR)
                          │
                          ▼
                 Architectural ADR
                          │
                          ▼
            Canonical Specification

Each lower layer must comply with the layers above it.

Layer 1 — Constitution

A Constitution defines architectural principles that are expected to remain valid for many years.

Constitutions answer questions such as:

  • What principles govern the platform?
  • What architectural invariants must always hold?
  • What authority governs a domain?
  • What concepts are constitutional?
  • What terminology is normative?

Constitutions intentionally avoid implementation details.

Examples​

Create or amend a Constitution when introducing:

  • a new architectural invariant;
  • a new constitutional principle;
  • a new governance model;
  • a platform-wide architectural constraint;
  • a new constitutional domain.

Example​

Adding Replay Profiles (EXACT, BANDED, RECORDED) as a platform capability required the Replay Constitution.

Layer 2 — Constitutional ADR (CADR)

A Constitutional ADR records why a constitutional change was made.

A CADR captures:

  • architectural motivation;
  • considered alternatives;
  • trade-offs;
  • constitutional implications;
  • approved decision.

CADRs preserve constitutional lineage.

Examples​

Suitable topics include:

  • introducing a new Constitution;
  • changing constitutional authority;
  • evolving replay governance;
  • introducing new constitutional terminology.

Layer 3 — Architectural ADR

Architectural ADRs document significant implementation or architectural decisions that do not change constitutional principles.

Examples include:

  • selecting PostgreSQL over another database;
  • introducing a new computation engine;
  • choosing a message protocol;
  • adopting GraphQL.

Architectural ADRs shall never redefine constitutional principles.

Layer 4 — Canonical Specification

Canonical specifications define implementation.

They describe:

  • engines;
  • APIs;
  • events;
  • CSI contracts;
  • database structures;
  • workflows;
  • algorithms;
  • replay semantics.

Specifications implement constitutional principles.

They do not establish them.

Decision Matrix

Proposed ChangeGovernance Artifact
New platform principleConstitution
New architectural invariantConstitution
New constitutional terminologyConstitutional Lexicon
Constitutional rationaleConstitutional ADR
New architecture patternADR
Database schemaCanonical Specification
REST APICanonical Specification
Replay manifest fieldsCanonical Specification
Frontmatter schemaDocumentation Constitution
Pipeline orderingConstitution + Canonical Specification
AI operating rulesAI Constitution

Decision Flow

Architectural Question
          │
          ▼
Does it change architectural principles?
          │
     ┌────┴────┐
     │         │
    Yes       No
     │         │
     ▼         ▼
 Constitution  Does it change architecture?
                  │
             ┌────┴────┐
             │         │
            Yes       No
             │         │
             ▼         ▼
            ADR   Specification

Constitutional Amendments

A Constitution may only be amended when the proposed change:

  • affects multiple modules;
  • introduces a new invariant;
  • modifies constitutional authority;
  • changes governance;
  • changes platform terminology;
  • changes replay philosophy;
  • changes architectural ownership.

Routine implementation improvements shall not amend Constitutions.

Constitutional ADR Workflow

Architectural Problem
          │
          ▼
Discussion
          │
          ▼
Draft Constitutional ADR
          │
          ▼
Architectural Review
          │
          ▼
Constitution Amendment
          │
          ▼
Canonical Specifications Updated
          │
          ▼
Documentation Lint
          │
          ▼
Implementation

Implementation shall never precede constitutional approval where constitutional change is required.

AI Agent Decision Rules

Before modifying the repository, AI agents shall determine which governance layer is affected.

If the change introduces:

  • a new invariant;
  • a new constitutional concept;
  • a new authority model;
  • a new governance principle;

the AI agent shall recommend constitutional review rather than silently modifying specifications.

AI agents shall not create constitutional concepts without explicit approval.

Examples

Example 1​

Proposal

Add a new replay mode.

Governance

  • Replay Constitution
  • Replay Profile Specification
  • Canonical Specification updates

Example 2​

Proposal

Change the Trust Score formula.

Governance

  • Scoring Constitution (if principles change)
  • Score Governance Specification
  • Trust Scoring Specification

Example 3​

Proposal

Add a new CSI message.

Governance

Canonical Specification only.

Example 4​

Proposal

Rename an ontology identifier.

Governance

Ontology Constitution plus applicable Canonical Specifications.

Example 5​

Proposal

Add support for a new REST endpoint.

Governance

Canonical Specification.

Anti-Patterns

The following are architectural anti-patterns.

Constitutional Inflation​

Creating constitutional rules for implementation details.

ADR Inflation​

Creating ADRs for routine engineering decisions.

Specification Drift​

Changing implementation without updating the governing specification.

Constitutional Drift​

Allowing specifications to diverge from constitutional principles.

Parallel Authority​

Creating multiple documents that claim authority over the same concept.

Relationship to Documentation Governance

The Documentation Constitution governs:

  • document quality;
  • frontmatter;
  • linting;
  • identifiers;
  • generated artifacts.

The Architectural Decision Guide governs:

  • where architectural decisions belong;
  • how architectural changes evolve;
  • which governance artifact shall be created.

Governance Summary

QuestionArtifact
What principles govern the platform?Constitution
Why was the principle introduced?Constitutional ADR
Why was an architectural solution selected?ADR
How is it implemented?Canonical Specification

Constitutional Principle

The stability of ZAYAZ depends not only on making good architectural decisions, but on placing every decision in the correct governance layer.

Constitutions establish enduring architectural law.

Constitutional ADRs preserve the reasoning behind that law.

Architectural ADRs document significant implementation decisions.

Canonical Specifications define how the platform operates.

Together these four layers create a governance model in which principles remain stable, implementation remains flexible, and every architectural decision remains traceable.



GitHub RepoRequest for Change (RFC)