Skip to main content

Architecture Standards

Architecture Standards turn the Documents workspace into a reviewed source of truth for engineering standards, Architecture Decision Records (ADRs), and Requests for Change (RFCs). The module keeps the human-facing discussion and the machine-readable enforcement contract together: teams write standards in Markdown, add structured standard_item blocks where automation is needed, and let Qarion generate reviewable artifacts for repositories and delivery pipelines.

Use this module when you need to:

  • Publish standards that should guide implementation and review.
  • Record ADRs that explain significant architectural decisions.
  • Run RFCs before changing a standard, architecture, or delivery practice.
  • Generate or roll out configuration artifacts such as linter, pre-commit, CI/CD, or repository policy files.
  • Track standards history, exceptions, and Git-backed diffs in one place.

Workspace Model​

Each space has an Architecture Standards workspace with seeded sections for:

  • Standards - current engineering, data, platform, and architecture rules.
  • ADRs - accepted decisions and their context.
  • RFCs - open or closed proposals that collect discussion before a decision.

Standards pages use the same authoring lifecycle as regular Documents pages: draft, comment, submit, review, publish, and revise. Published pages are the current source of truth. Draft pages remain visible as in-progress work until they are submitted and published.

Revision history is retained for every page. When generated artifacts, validation results, or exceptions point back to a standard, they include source page and revision metadata so reviewers can understand exactly which standard produced the output.

Standard Items​

Standard items are the core automation unit. They are small YAML blocks embedded inside a human-readable standards page. The surrounding Markdown should explain the rationale, examples, and operating guidance. The standard_item block captures the structured contract that Qarion can search, retrieve, validate, and compile into artifacts.

kind: standard_item
id: python.ruff-tooling
title: Python projects use Ruff with Python 3.11 defaults
statement: Python code must use Ruff for formatting, linting, import sorting, and Python 3.11 compatibility.
severity: error
applies_to: ["python", "pyproject.toml"]
tags: ["python", "ruff", "formatting", "linting"]
rule:
  type: pyproject.ruff
  line_length: 88
  indent_width: 4
  target_version: py311
artifact_targets: ["ruff", "pyproject", "pre-commit"]
examples:
  compliant:
    - "tool.ruff.line-length = 88"

Standard Item Fields​

FieldPurpose
kindMust be standard_item.
idStable item identifier, for example python.ruff-tooling.
titleShort human-readable name.
statementThe rule or expectation to apply.
severityinfo, warning, or error. Legacy labels such as high normalize to the closest supported severity.
applies_toTechnologies, paths, file types, or components in scope.
tagsSearch and grouping labels.
ruleStructured rule details used by validation or artifact generation.
artifact_targetsTarget artifact families such as ruff, eslint, pre-commit, github-actions, or helm.
examplesOptional examples grouped by label.

Keep IDs stable after publication. If a standard is replaced, publish a new revision or a new item and explain the migration path in the page.

Constraint Validation​

Use standard_constraint blocks when a standard should validate a repository configuration file. Validation currently supports pyproject.toml, frontend/eslint.config.js, .pre-commit-config.yaml, and Makefile.

kind: standard_constraint
target: pyproject.toml
path: tool.ruff.line-length
operator: equals
value: 88
severity: error
description: Python formatting should use the repository Ruff line length.

Validation results include whether the check passed, the actual value, the expected value, whether the target file exists, and the source page revision that produced the constraint.

RFCs and Polls​

RFCs are proposal documents. They do not approve a change by themselves. Once an RFC is accepted, the accepted change should be reflected in a published Standard or ADR.

For RFCs that require a vote, describe the voting rules directly in the RFC body before the poll. For example:

## Voting rules

- Voting window: 5 business days.
- Eligible voters: platform architecture team and service owners.
- Passing threshold: at least 60% approve and no unresolved security objection.
- Tie breaker: the architecture owner decides after recording rationale.

```poll
id: POLL_ID
```

Polls can be single-choice or multi-choice, can inherit page access, and can grant direct view, vote, or edit permissions to users and teams. Editors can close polls manually and inspect voter breakdowns when poll permissions allow it.

Diagrams​

Architecture Standards pages support both Mermaid and editable Draw.io diagrams. Use Mermaid for lightweight diagrams that should stay close to the Markdown source:

Use Draw.io diagrams when the diagram needs richer visual editing. Attach or insert the Draw.io diagram from the document editor, then keep the surrounding text clear enough that reviewers can understand the decision without opening the diagram editor.

Standards Artifacts​

Architecture Standards can generate configuration artifacts from published standards:

  • Deterministic artifacts come from standard_artifact blocks embedded in a standards page.
  • AI previews draft artifacts from standard_item blocks and page context.
  • Deterministic validation checks run before users apply AI proposals.
  • Applied artifacts are stored as page attachments and can also be written to a managed standards artifact repository.
  • Rollout preview and apply actions compare managed artifacts against selected repositories and can create provider merge requests.

Review generated artifacts before applying them, especially when they affect linting, pre-commit, CI/CD, repository policy, deployment, or security files.

Git and Repository Rollout​

Qarion does not need to replace your operational Git provider. Existing GitHub, GitLab, Bitbucket, Azure DevOps, or other deployment repositories can remain the source for builds and releases.

Use the managed standards artifact repository as a governance and review surface:

  1. Generate or preview artifacts from a standards page.
  2. Review the proposed files and validation checks.
  3. Preview the managed repository diff.
  4. Roll out selected artifacts to target repositories.
  5. Review and merge provider merge requests when supported.

This keeps architecture governance linked to source standards while still working with the delivery process your engineering teams already use.

Exceptions​

When a repository, component, path, or asset cannot comply with a standards item, file an exception from the standards inventory. Exceptions capture:

  • Scope, such as paths, assets, or components.
  • Reason and business justification.
  • Optional expiry date.
  • Review decision and reviewer notes.
  • Source page and revision metadata.

Exception statuses are pending, approved, rejected, cancelled, revoked, and expired. Active exceptions remain linked to the standard item and are marked stale if the source standard revision changes.

  1. Draft an RFC when the team needs discussion before changing architecture or delivery practice.
  2. Add diagrams, examples, and poll voting rules when they help reviewers decide.
  3. Publish an ADR when the decision is accepted.
  4. Update or create the Standard with one or more standard_item blocks.
  5. Preview AI or deterministic artifacts from the standard.
  6. Review validation checks and save only the artifacts you want.
  7. Preview repository diffs and roll out through merge requests.
  8. File exceptions for scoped non-compliance and review them before expiry.