The Solution Architect's Guide to Archgram Flow

Architecture decisions have a half-life problem. The decision that shaped a system three years ago is perfectly rational in context — but the context is gone. The architect who made it has moved on. The trade-offs that were explicit in the original discussion exist only in someone's memory. When the next architect looks at the same system, they see the consequences but not the reasoning — and they either repeat the same analysis from scratch or make a conflicting decision without realising there was a prior one.

Architecture Decision Records solve this problem. But only when they are findable, linked to the thing they describe, and maintained as the architecture evolves. Most ADR implementations fail at all three — they live in a folder, disconnected from the diagram, and become stale as soon as the design changes.

Archgram Flow changes this by anchoring ADRs to diagram nodes. This article covers how solution architects use Flow — from creating decisions to evolving them over time to producing the architectural record that survives the delivery.

Creating ADRs Anchored to Diagram Nodes

The core workflow is simple: right-click any node in your architecture diagram and select Add Decision. The ADR is immediately linked to that node. It inherits the node's label and the diagram's context. You fill in the rest.

A complete ADR has five sections:

• Context — what forces made this decision necessary? What constraints existed?
• Options Considered — at least two alternatives, each with pros, cons, and estimated cost or complexity
• Decision — what was chosen and the primary reasoning (not just "it was the best option")
• Consequences — positive outcomes, technical debt introduced, follow-up actions required
• Status — Proposed | Under Review | Approved | Superseded

The options table is the most important part and the most often skipped. An ADR that only records what was chosen — without recording what was rejected and why — is half an ADR. The future architect reading it cannot evaluate whether the constraints that drove the decision still apply.

# ADR-002: Async Order Confirmation via SQS

Status: Approved
Date: 2026-02-21
Linked node: Order Service → Notification Service

## Context
Order confirmation emails were causing p95 latency of 4.2s on the checkout
endpoint because the email provider (SendGrid) added 2–3s to the synchronous
call. Our NFR requires checkout p95 < 1s.

## Options Considered
| Option              | Pros                          | Cons                            |
|---------------------|-------------------------------|----------------------------------|
| Async via SQS       | Checkout unblocked; retryable | Adds SQS, increases complexity  |
| Sync with timeout   | Simple                        | Degrades UX; still fails NFR    |
| Remove confirmation | No latency impact             | Unacceptable — regulatory risk  |

## Decision
Publish order confirmation events to SQS. Notification Service consumes
and sends emails asynchronously. Retry policy: 3 attempts, 30s backoff.

## Consequences
+ Checkout p95 reduced from 4.2s to 0.8s (NFR met)
+ Notification failures no longer affect order completion
- Dead letter queue monitoring required (added to RAID log as operational dependency)
- Engineers unfamiliar with SQS will need onboarding (1 day estimate)

ADR Status Workflow

ADRs move through a lifecycle. The status is not cosmetic — it drives what appears in the diagram, what gets committed to GitHub, and what the Handoff Pack includes.

• Proposed — draft; visible in Flow but not yet committed to GitHub. Others can comment.
• Under Review — formally open for review. The architect has shared it with the team and is gathering feedback.
• Approved — decision is final. Archgram commits the ADR as a Markdown file to the configured GitHub branch.
• Superseded — a later decision replaced this one. The ADR is kept in full (including the content of the superseding ADR reference) and is included in the Handoff Pack for historical context.

Moving an ADR to Superseded — rather than deleting it — is essential. The original decision and the forces that drove it remain part of the architectural record. Future engineers need to understand why the original choice was made to evaluate whether the superseding decision remains valid.

Using AI to Generate and Evolve Diagrams

Archgram Flow sits on top of Archgram's core diagramming and AI capabilities. As an architect you can:

• Generate the initial diagram with AI — describe the system in plain English ("a C4 container diagram for a checkout service with React SPA, Node.js API, PostgreSQL, Redis cache, SQS notification queue, and Stripe payment integration") and generate a complete, structured diagram in seconds
• Refine with AI — after generating, use AI Refine to add technology labels, improve layout, or add missing relationships
• Generate sequence diagrams alongside containers — the C4 container diagram is the structural view; sequence diagrams for key flows (checkout, authentication, notification) live in the same workspace and can be linked from ADRs
• Use AI to draft ADR content — from the ADR editor, click AI Assist to generate a draft based on the linked node and the Initiative context. Review, edit, and approve.

GitHub Sync: ADRs Alongside the Code

When GitHub Sync is active, every ADR that reaches Approved status is automatically committed to the repository:

docs/decisions/
├── adr-001-stripe-over-adyen.md
├── adr-002-async-order-confirmation.md
└── adr-003-postgresql-over-dynamodb.md

The files are in MADR format and committed with a structured message:docs(adr): ADR-002 Async order confirmation via SQS [approved].

Developers reading the codebase can find the decisions without leaving their IDE. PR reviews can reference ADR files directly. If the architecture is reviewed in a compliance audit, the decisions are version-controlled and auditable.

When an ADR is superseded, the file is updated in the next commit — with aSuperseded-by header pointing to the replacing ADR — rather than deleted. The history of the decision is preserved in both Archgram and Git.

NFR Guardrails and Review Gates

Non-functional requirements — latency, availability, scalability thresholds — can be attached to diagram nodes as guardrails. When a new ADR affects a node with an NFR attached, Flow surfaces the guardrail in the ADR editor as a reminder:

⚠ NFR guardrail on linked node: API Gateway
• Latency: p95 < 200ms end-to-end
• Availability: 99.9% per calendar month
• Scalability: must handle 2000 rps without horizontal scaling changes

This decision affects the above node. Confirm consequences section
addresses NFR impact before moving to Under Review.

Review gates work similarly. An architect can require that any ADR affecting a specific node (e.g. the database) must be reviewed by the Head of Data Engineering before moving from Under Review to Approved. The gate appears as a required approver on the ADR status transition.

Maintaining the Architectural Record Over Time

The value of ADRs compounds. A system with five ADRs is helpful. A system with fifty ADRs — each linked to a node, each recording what was rejected and why — is a knowledge asset. Here is how to maintain that record as the system evolves:

• One ADR per decision, not per sprint. If a sprint introduces three unrelated architectural choices, create three ADRs. Bundling decisions into one ADR makes both harder to find and harder to supersede individually.
• Update the diagram when the architecture changes. A superseded ADR whose linked node no longer exists in the diagram is a signal that the diagram needs updating. Keep diagram and decisions in sync.
• Link new ADRs to old ones when they supersede them. TheSuperseded-by and Supersedes fields in MADR format create a navigable decision chain — visible in both Archgram and GitHub.
• Archive, never delete. A deleted ADR is lost context. A Superseded ADR is part of the architectural story.

What the Architect Contributes to the Handoff Pack

At the end of a Flow cycle the architect's work is collected into:

• architecture.svg and architecture.mmd — the final diagram
• decisions/adr-*.md — every ADR in MADR format, including Superseded ones
• The NFR guardrails and review gates record (appended to the README)

The AI-generated README section for architecture is written from the ADR set — it summarises the key decisions, the alternatives that were rejected, and the technical debt that was consciously accepted. Review it before finalising the pack; it reads well and usually needs only minor edits.

Getting Started as a Solution Architect

• Create the Initiative and write the problem statement before generating any diagrams
• Generate the initial C4 context and container diagrams using AI — it takes minutes
• Create your first ADR by right-clicking a node — even if it is Proposed and not yet agreed
• Populate the Options table thoroughly; this is what makes the ADR valuable six months later
• Enable GitHub Sync so Approved ADRs land in the repository automatically
• Set NFR guardrails on nodes with hard latency or availability requirements

Full reference documentation is at Archgram Flow.