Principles

Principles are the normative rules your architecture practice has agreed to follow. They answer the question: "Why did we build it this way?" A principle like "All integrations run through the API gateway" explains — and governs — hundreds of downstream decisions. In Northwise, principles are first-class entities with a lifecycle, an owner, enforcement levels, and traceable links to the elements they govern and the decisions that reference them.

What it does

• Stores architecture principles with code (INT-03), statement, rationale, and scope
• Tracks lifecycle (draft → proposed → approved → deprecated / superseded) with a full version history
• Records enforcement level (advisory, should, must) so assessments know how hard to penalise violations
• Links principles to Landscape elements (which applications are governed by this principle?) and to ADRs (which decisions reference it?)
• Detects gaps: principles without an enforcement level, approved principles not reviewed in > 12 months, and principles with no linked elements
• Supports supersession — retire an old principle and link it to the new one that replaces it

When to use it

• You are documenting your first set of architecture standards before running a Plumbline assessment
• A technology choice was made — you want to record why and which principle drove it
• You're reviewing whether your principles are still current (the "mark reviewed" action updates the staleness clock)
• You want to trace from a principle to every application component that must comply with it

How it works

Anatomy of a principle

| Field | Purpose | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Code | Short identifier, e.g. INT-03. Auto-suggested (next in prefix sequence) but editable. Unique per tenant. | | Statement | The normative sentence. One clear imperative. | | Rationale | Why this rule exists. The context that makes the rule make sense. | | Scope domains | Which parts of the estate this principle applies to. Multi-value, free-form. | | Enforcement level | advisory (guidance only), should (default expected, deviations need justification), must (mandatory — Plumbline flags any violation). | | Owner | The architect accountable for keeping this principle current. | | Tags | Free-form, multi-value. Useful for grouping (e.g., security, integration, data). | | Status | Where the principle is in its lifecycle. | | Last reviewed | When an architect last confirmed this is still valid. Stale = > 12 months ago. |

Lifecycle

All principles start as draft. Promote to proposed to flag it for review with the team. Promote to approved to make it authoritative — Plumbline assessments only evaluate against approved principles. When a principle is superseded by a better-worded version, use the Supersede action: the old principle becomes read-only and shows a banner pointing to the new one.

draft ↔ proposed → approved → deprecated
                 ↘ superseded (via Supersede action only)

Every transition is recorded in the history tab with the actor, timestamp, and an optional reason.

Linking to Landscape elements

The Linked Elements tab on a principle detail page shows which elements the principle governs. Two link types:

• Governed by — this element must comply with the principle. A Plumbline assessment will check for compliance.
• Exemplifies — this element is a good example of the principle in practice. Useful for documentation.

You can also link from the other direction: the Linked Principles tab on an element in Landscape.

Linking to ADRs

When a decision was made because of a principle (or against it), link them. The Referencing ADRs tab on a principle shows every ADR that cited it. The Referenced Principles tab on an ADR shows every principle it was based on.

This traceability makes the "why" of any architectural decision auditable: Principle → ADR → Element.

Supersession

When a principle needs a complete restatement (not just a word-change), use Supersede with new principle. A new draft opens pre-filled with the same scope, tags, and domain. When you save the new one at proposed or above, the old one transitions to superseded automatically, links back to the new, and becomes read-only.

Configuration options

There is no per-tenant configuration for Principles beyond the fields on each principle itself. The staleness threshold (default: 12 months) is configurable in Settings → Organisation.

Common workflows

• Running your first Plumbline assessment → you need at least 5 approved principles with enforcement levels set. See Your first week.
• Capturing a decision from a principle → from the principle detail page, click Capture decision to open a new ADR pre-linked to this principle.
• Finding principles without enforcement levels → the Standards overview flags this as a gap; clicking the card drops you into a pre-filtered list.

Related