Skip to content
ArchNGN

Design Checks

A design check grades a proposed change against your architecture: the standards you have recorded, the compliance frameworks you have applied, the metamodel your account permits, and the current-state structure your connectors discovered.

It runs from a pipeline through the REST API, from an AI coding agent through the MCP server, or from a terminal. The verdict cites what it was judged against, so a developer told “no” also learns why.

Adding it to a pipeline

Section titled “Adding it to a pipeline”

GitHub Actions

permissions:
  contents: read
  security-events: write     # so findings land on the diff

steps:
  - uses: actions/checkout@v4
    with: { fetch-depth: 0 }

  - uses: archngn/archngn-app/integrations/github-action@main
    with:
      token: ${{ secrets.ARCHNGN_TOKEN }}
      diff-against: origin/${{ github.base_ref }}
      artifacts: |
        openapi=openapi.yaml

security-events: write is the line worth getting right: with it, every finding is annotated on the offending line of the pull request through code scanning, which is the difference between a check people read and one they scroll past.

Templates for GitLab CI and Azure DevOps work the same way, and anywhere else:

pipx install archngn-check
archngn check --artifact terraform_plan=plan.json --diff-against origin/main

You do not describe your architecture to it

Section titled “You do not describe your architecture to it”

The check reads the artifacts your build already produces.

ArtifactWhere it comes fromWhat it establishes
OpenAPI specyour spec fileendpoints, and whether each is authenticated
Terraform planterraform show -json tfplanwhat the change provisions — and what changes, since a plan states actions
SBOMCycloneDX or SPDXdependencies
Kubernetes / Composeyour manifestsworkloads, and the services they are configured to call
Git diff--diff-against origin/mainline numbers — the only artifact that has them

Send the ones you have. An artifact that fails to parse becomes a warning on the result, never a failed build: one bad input out of five must not stop the gate, but you are told the check graded less than you sent.

Matching the change to the right system

Section titled “Matching the change to the right system”

The highest-value thing you can supply is an identity signal — a repository URL, a container image reference, a cloud resource id. The repository URL is detected automatically from every supported CI platform.

With one, the change is graded against that system’s recorded owners, criticality and existing integrations. Without one, it is graded on the change alone, and the result says so.

What it looks at

Section titled “What it looks at”

Four deterministic evaluators, in order:

  1. Registry resolution — is this component in the model? If not, that is itself worth knowing: code that is about to deploy and has never been registered.
  2. Metamodel conformance — does the change introduce a type or relationship your account’s model does not permit?
  3. Rule conformance — the compliance frameworks you have applied, run over the change as if it had landed.
  4. Structural drift — a new dependency on a system you have decided to retire, a second integration style between systems that already integrate, a new link into a more critical system with nothing governing it, or the removal of a link something critical depends on.

Findings are limited to what the change is answerable for. Pre-existing gaps elsewhere in the registry belong in the conformance report, not in somebody’s build.

Three depths

Section titled “Three depths”
fast     every commit          blocking gate, no AI, milliseconds
deep     every pull request    + an AI pass over your written standards
review   release or nightly    the full design review document

fast is the four evaluators above. No AI, no token cost, and it runs even when your monthly allowance is exhausted.

deep adds one bounded AI pass that reads the standards nobody encoded as a rule — which is most of them.

Deep findings are always advisory. They report at their assessed severity and can move a verdict to warn, never to fail. An AI in the blocking path would make a build non-reproducible: the same commit passing on Tuesday and failing on Wednesday. The useful consequence is that turning deep on cannot break a pipeline that fast was already passing.

review queues a full Design Review and produces a document in the workspace. It returns immediately with an id to poll; there is no verdict, because the output is a document rather than a judgement.

See Usage for what each costs.

Passing and failing

Section titled “Passing and failing”

Your pipeline sets the blocking threshold — severity is our judgement, blocking is your policy. Start at high.

A failing check is still a successful request. The verdict is in the response body and in a header; the HTTP status is not the verdict. A pipeline that cannot tell “your architecture is wrong” from “the gate is unreachable” ends up ignoring both.

Two categories never block at any threshold: findings from a framework you applied in advisory mode, and findings you have waived.

Waivers

Section titled “Waivers”

The gate will be wrong eventually. The honest response is a waiver, not switching the step off.

archngn waive \
  --rule structure.dependency-on-retiring-system \
  --subject legacy-core \
  --reason "Cutover to the replacement is scheduled for Q4, tracked in ARCH-412." \
  --days 90

Three things keep a waiver honest, and none is optional:

  • A reason is required, and short ones are refused. A suppression nobody can explain later is one nobody can review.
  • An expiry is required — 90 days by default. A permanent waiver is an undocumented architecture decision that outlives everyone who understood it.
  • The finding still appears in every result, marked as waived. It leaves the verdict and nothing else.

Waiving needs the check:waive scope, or the equivalent capability in the console — Account Admin by default. The person a gate blocks should not also be the person who can unblock it unobserved. Creating and revoking a waiver are both recorded in the audit log.

History in the console

Section titled “History in the console”

Design Checks in the left sidebar shows recorded checks for the active workspace: when, which component, which commit, the findings with the standards they cited, and the waivers in force.

Recording is opt-in per run. A per-commit gate fires dozens of times a day per repository, so ask for it on the runs worth keeping — a nightly deep check, a release gate, an audit answer.

Reading the history needs only workspace read access: a developer should be able to see why their build was blocked without an admin in the loop.

Section titled “Related”