Archgram Flow: Closing the Gap Between Architecture and Delivery

There is a gap in every software delivery that nobody talks about clearly. On one side sits the architecture: a set of diagrams, decisions, and design documents that explain what is being built and why. On the other side sits delivery: a backlog, a RAID log, a milestone plan, and a set of status updates. These two worlds coexist in separate tools, updated by different people, and they drift apart almost immediately.

The architect who designed the event-driven checkout is not the person marking the "Kafka Integration" ticket as Done in Jira. The delivery manager tracking the milestone does not know that the ADR for the message broker was superseded last week. The product owner prioritising slices cannot see which architecture components each slice requires — so scope decisions are made blind.

Archgram Flow exists to close this gap.

The Core Idea: Everything Belongs to a Node

The insight behind Flow is straightforward. Every delivery artefact — every decision, every risk, every scope item — is ultimately about some part of the architecture. An ADR about database choice belongs to the database node. A RAID risk about a third-party payment gateway belongs to the payment service container. A scope slice that delivers user registration exercises the Auth Service, the User Store, and the email notification path.

If you anchor every delivery artefact to the diagram node it describes, two things happen. First, the architecture diagram becomes a navigable knowledge map rather than a static image. Click any node and you immediately see every decision that shaped it, every risk associated with it, and every scope slice that touches it. Second, the delivery data becomes spatially grounded. When the delivery manager says "the payment integration is at risk", everyone can point to the same box on the same diagram and understand the blast radius.

How Flow Is Structured

Flow is organised around three roles and a lifecycle that moves from problem definition through design and delivery to handoff.

Initiatives

Everything starts with an Initiative — a named delivery container that captures the problem before any implementation begins. An Initiative holds the problem statement ("checkout abandonment is 12%, we need it below 6%"), the success criteria, the constraints (budget, regulatory, timeline), and the linked architecture diagrams. It is not a requirements document. It is the delivery context that every subsequent artefact inherits.

Creating the Initiative first forces the team to agree on the problem before agreeing on the solution. The architecture diagrams are attached once the context is clear — not before.

Architecture Decision Records, Linked to Nodes

ADRs in Flow are not stored in a folder or a wiki page. They are anchored to diagram nodes. When an architect right-clicks the "Order Service" container and selects Add Decision, the resulting ADR is permanently linked to that component. The ADR carries context, options considered, the decision made, and its consequences. It moves through a status workflow: Proposed → Under Review → Approved → Superseded.

Every time an engineer wants to understand why the Order Service uses PostgreSQL instead of DynamoDB, they click the node. They do not search Confluence, ask a senior engineer, or hope the decision was captured in a Slack thread. The answer is there, linked to the thing it describes.

When GitHub Sync is active, each Approved ADR is automatically committed to the repository as a Markdown file in MADR format:

# ADR-003: Use PostgreSQL over DynamoDB for order storage

Status: Approved
Date: 2026-02-14
Linked node: Order Service

## Context
Order data has complex relational structure. We need ACID transactions
for payment and stock updates. Team has deep SQL expertise.

## Options Considered
| Option     | Pros                          | Cons                           |
|------------|-------------------------------|--------------------------------|
| PostgreSQL | ACID, rich queries, team skill | Vertical scaling ceiling       |
| DynamoDB   | Unlimited scale, managed       | No joins, eventual consistency |

## Decision
PostgreSQL 15 on RDS Multi-AZ. Migrate to Aurora if write load exceeds 10k/s.

## Consequences
+ Strong consistency for payments and inventory
+ Team productive immediately
- Read replicas required at scale; set CPU alert at 60%

This means ADRs travel with the code. A developer reading the Order Service source in their IDE can find the decision file in the same repository. No tool-switching, no login required.

MVP Slices and the Slice Board

Slices are the product owner's view of delivery. A Slice is a vertical cut through the architecture that delivers a unit of user or business value — from UI to database. It is intentionally coarser than a user story. One slice might encompass a sprint of work. The goal is to track the delivery of value, not task completion.

Each Slice is linked to the diagram nodes it exercises. When the PO hovers a Slice on the board, the corresponding nodes light up in the architecture diagram. Scope decisions become architectural decisions — visible to everyone in the same view.

Slices are prioritised as MVP (must-have), Valuable (should-have), or Deferred. The MVP set defines the minimum architecture needed for first delivery.

RAID Log, Spatially Grounded

Every delivery has risks, assumptions that need validating, issues that have surfaced, and dependencies on other teams. Flow's RAID log captures all four — and links each item to the diagram node it affects.

A risk about the reliability of a third-party identity provider is linked to the Identity Provider node in the C4 container diagram. When someone asks "which parts of the architecture are exposed to this risk?", the answer is one click away. When the risk is resolved, it is archived — but retained in the Handoff Pack.

Milestones with Confidence Scores

Flow replaces binary milestone tracking (hit/missed) with confidence scoring. A milestone carries a 0–100% confidence score, updated weekly by the delivery manager. A milestone at 70% confidence two weeks out says "we are on track, but there are known risks". A milestone that drops from 85% to 45% in one update tells the story of a week that went wrong — before it becomes a missed date.

Unresolved high-impact RAID items automatically suggest a confidence reduction. The DM decides whether to accept the suggestion. The confidence history is charted and included in the Handoff Pack.

The Handoff Pack

The Handoff Pack is what a completed Flow cycle produces. It is a single ZIP archive containing every artefact a new team needs to understand, operate, and continue building the system — without meetings.

handoff-checkout-v2/
├── README.md                    ← AI-generated narrative
├── architecture.svg             ← Final architecture diagram
├── architecture.mmd             ← Mermaid source
├── decisions/
│   ├── adr-001-stripe-over-adyen.md
│   ├── adr-002-async-order-confirmation.md
│   └── adr-003-postgresql-over-dynamodb.md
└── delivery/
    ├── slices.md                ← MVP slices + AC
    ├── raid.md                  ← Full RAID log
    └── milestones.md            ← Timeline + confidence history

The README is written by AI using the Initiative context, ADR narratives, and delivery data. It reads like an architecture handover document — not a data dump. A new engineer can read it in 20 minutes and understand what was built, why the key decisions were made, what risks were managed, and what the recommended next steps are.

A Concrete Example: Checkout Service Delivery

Here is a condensed walkthrough showing how Flow runs through a real delivery cycle:

• Week 0, Monday — Initiative created. Architect creates the "Checkout Service v2" Initiative with the cart abandonment KPI. Attaches a C4 container diagram generated in Archgram. Invites PO and DM.
• Week 0, Wednesday — Design. Architect uses AI Generate to produce a sequence diagram for the payment flow. Right-clicks the Payment Service node, creates ADR-001: "Use Stripe over Adyen" (Proposed). PO creates four Slices on the Slice Board: Guest Checkout, Saved Cards, Apple Pay, Order Confirmation Email.
• Week 1 — Decisions. ADR-001 reviewed and moved to Approved. ADR-002 created: "Async order confirmation via SQS". DM creates Milestone M1: "Payment flow live" at Week 6, confidence 75%. First RAID risk logged: "Stripe test environment webhook delay", linked to the Payment Service node.
• Weeks 2–5 — Build. Slices updated weekly. Stripe risk resolved (moved to Archived). ADR-002 approved. DM updates M1 confidence to 90% in Week 5 after both core slices move to Done.
• Week 6 — Close. All four Slices are Done. Exit criteria met: load test passed at 500 rps, security review signed off, runbook written. DM generates Handoff Pack. AI writes the README in 40 seconds. Pack is attached to the release ticket and archived in the repository.

Who Benefits Most from Flow

Flow is most valuable in organisations where multiple roles collaborate on the same delivery, where architectural decisions have medium-to-long term consequences, and where handoffs between teams or phases are common. This typically means:

• Platform and shared-service teams — where what is built today becomes another team's dependency tomorrow
• Programme-level delivery — multiple teams, multiple workstreams, complex dependencies
• Regulated environments — financial services, healthcare, government — where audit trails of architectural decisions are mandatory
• Consulting and SI engagements — where the Handoff Pack is literally the deliverable at project close

For solo engineers or small teams building internal tools, the simpler diagrams-as-code workflow (without Flow) is usually sufficient. Flow adds the most value when there is coordination cost — multiple stakeholders, parallel workstreams, and a need for a durable record of why things were built the way they were.

Getting Started

Flow is available on Archgram Pro. To start:

• Open the editor and click Flow in the left sidebar
• Click New Initiative
• Write the problem statement before drawing any diagrams
• Attach an existing diagram or generate one with AI
• Start creating ADRs by right-clicking diagram nodes

The full reference guide — covering every Flow object, role-based workflows, GitHub integration, and the Handoff Pack format — is available in the Archgram Flow documentation.