Archgram Flow

Archgram Flow connects architecture to delivery. Instead of keeping decisions, scope, risks and milestones in separate tools, you attach them to the diagram they describe: an ADR about PostgreSQL belongs to the database node, a risk about a third-party API belongs to the integration it threatens, and a slice belongs to the components it exercises.

Flow is a Pro feature. Turn it on under Settings → Experimental Features → Archgram Flow.

How Flow Works

Work is organised into initiatives. Each initiative has eight sections: Overview, Architecture, Decisions (ADR), Slices, Delivery, RAID, Handoff Pack and Activity. A View as switch narrows them to what a role cares about:

• Product Owner — what we are building and in which order: scope, MVP slices, KPIs and the risks that threaten them
• Solution Architect — how it is built: architecture, decisions, the slices touching each component, and technical risk
• Delivery Manager — when and who: workstreams, milestones, dependencies and the risks that slip dates
• Everything — every section

All views read the same data, so a change one person makes is visible to the others. Assign a person to each role on the Overview, and Flow opens in that person's view by default.

Getting Started

1. Enable Flow in Experimental Features, then open the Flow view from the editor
2. Create an initiative and give it a title
3. In Architecture, link one or more diagrams from your workspace
4. Fill in the Overview and assign the product owner, architect and delivery manager
5. Add decisions, slices, workstreams, milestones and RAID items as the work progresses

Initiatives

An initiative is the delivery container. It captures the why before implementation starts: a description, KPIs and constraints. Its status moves through draft, active, completed and archived. The Overview also shows counts of everything attached to it and holds the role assignments.

Architecture Decision Records

Each ADR records a decision with its context, the decision, the alternatives considered and the consequences. Its status is proposed, approved or deprecated. An ADR can be linked to a node in a diagram so the decision is visible where it applies.

ADR: Use PostgreSQL over DynamoDB for order storage
Status: approved
Linked node: Order Store

Context
  Order data is relational (order → lines → products → inventory) and
  payments need ACID transactions. The team has strong SQL experience.

Decision
  PostgreSQL 15 on RDS Multi-AZ.

Alternatives
  DynamoDB: effectively unlimited scale, but no joins and eventual consistency.

Consequences
  + Strong consistency for payments and stock
  - Plan read replicas for scaleOpen in Archgram

You can also have ADRs drafted from an existing repository with the repository scan.

Linking Nodes to Flow Objects

In an initiative's Architecture section the linked diagram is drawn with overlays. Click a node to select it, then attach existing decisions, slices or RAID items to it, or detach them. Switch the overlay between Decisions, Delivery phase and Risk to see at a glance which components carry the most decisions, which are in which phase, and where the risk sits.

MVP Slices

A slice is a vertical cut through the architecture that delivers a unit of value. Each has a title, a user scenario, acceptance criteria, a phase (MVP, phase 2 or phase 3), a priority you set by moving it up or down the list, and the diagram nodes it touches.

Workstreams

A workstream is a parallel track of delivery, usually a team. Give it a title and a team name, and attach milestones to it. The Delivery section shows workstreams, milestones and dependencies together.

RAID Log

The RAID log tracks risks, assumptions, issues and dependencies, each with a type, a severity (low, medium, high, critical), a status (open, mitigating, resolved, accepted) and a mitigation, and can be linked to a diagram node.

Milestones and Dependencies

A milestone has a target date, a status (pending, on-track, at-risk, completed), a confidence percentage you set as a judgement call, and an exit checklist.

Dependencies link slices, workstreams and milestones: A blocks B means A must finish before B, A needs B means B must finish first, and relates to carries no order. Archgram refuses a dependency that would create a cycle, flags items that are currently blocked, and lets you mark dependencies resolved.

Comments and @Mentions

Initiatives, decisions, slices and other objects have comment threads. Type @ to mention a member; they are notified through the bell in the Flow header. The Activity section lists recent changes.

Flow Files in Git

With Git Sync configured, Flow documents (such as ADRs) can be saved as Markdown files and pushed to your repository alongside the diagrams.

Handoff Pack

The Handoff Pack section compiles the initiative into one document: overview, ADRs, slices, workstreams, milestones, dependencies and the RAID log. Download it as Markdown or JSON, or copy the Markdown. Use it to hand a project to a new team, attach to a steering-committee pack, or archive a phase.

End-to-End Example

1. Intake: the architect creates the initiative "Checkout Service v2", records the problem and the KPI (cut cart abandonment from 12% to under 6%), and links a container diagram.
2. Design: the architect selects the Payment Service node and records ADR "Use Stripe over Adyen" as proposed. The product owner adds slices: Guest Checkout, Saved Cards, Apple Pay, Confirmation Email.
3. Decision: the team approves the ADR. The delivery manager creates the milestone "Payment flow live" at 80% confidence.
4. Build: workstreams "Payment" and "Notifications" are created, and a risk ("Stripe webhook delay over 5s in test") is linked to the Payment Service node.
5. Progress: slices move through phases, the risk is resolved, and the milestone's confidence is raised to 90%.
6. Close: the exit checklist is complete, the milestone is marked completed, and the delivery manager downloads the Handoff Pack for the release ticket.