From system maps to live practice: Building Midflight Canvas

An engineer opens a system diagram and sees services, databases, and dependencies. A practice begins, the first symptom appears, and the diagram is suddenly incomplete. It does not show what the engineer checked, which hypothesis failed, or why the final mitigation was safe.

Midflight exists to help engineers practice that work before a similar incident happens in production. We needed a surface that could begin with architecture, absorb live investigation, and end with a lesson another person could inspect. That surface became Canvas.

The gap between a diagram and a drill

Production incidents reward recovery. They leave little room for an experienced responder to explain why one signal mattered and another did not. Tabletop exercises provide time to discuss those decisions, but they do not reproduce system behavior. Technical labs reproduce behavior, but often lead the learner through a known procedure.

Architecture tools solve a different part of the problem. They preserve components and relationships. They rarely preserve the evolving investigation on top of that structure. Postmortems capture the conclusion later, after the uncertainty has been compressed.

Canvas had to satisfy four requirements:

One graph with two operating modes

We considered separate products for diagramming and investigation. That would have produced two collaboration systems, two histories, and a synchronization problem at the exact point where the learner needs continuity. Instead, Canvas uses one versioned graph with two explicit purposes.

Troubleshooting as a mind map

Troubleshooting mode organizes the primary path as a mind map. A symptom leads to hypotheses. Hypotheses lead to checks and evidence. Evidence supports or contradicts a cause. A mitigation remains incomplete until the learner records verification.

This structure gives the investigation direction without reducing it to a checklist. The graph can branch, retain alternatives, and attach logs, metrics, commands, notes, and system components where they influenced a decision.

Architecture as a layered model

Architecture mode uses free placement. Services, databases, queues, clients, external systems, and boundaries become typed nodes. Dependencies record protocol, data flow, authentication, and trust crossings. Nodes can also record ownership, environment, criticality, data classification, provenance, and review state.

The metadata model separates edge, runtime, data, and control layers. Observability and security cross those layers. The model is structured enough to find missing owners or unauthenticated trust crossings, while free placement remains available for the context a reviewer needs.

Purpose is stored with the Canvas. Changing it creates a versioned, checkpointed copy. An architecture review cannot silently rewrite a troubleshooting record into a different kind of artifact.

Mermaid without a second diagram

Text is often the fastest way to express a system relationship. Visual editing is often the fastest way to inspect one. Supporting both introduced an authority problem: if Mermaid and the visual Canvas were independent renderers, they could disagree.

We chose one visible renderer and one graph. React Flow renders the Canvas. ELK owns automatic layout. Mermaid flowchart and graph source is parsed into the same versioned node and edge operations used by direct manipulation.

Synchronization works in both directions. A valid Mermaid edit can add, update, delete, and arrange graph objects. Visual changes can be serialized back to compact Mermaid. The apply preview identifies Canvas-only fields—such as comments, attachments, owners, and evidence links—that Mermaid cannot represent.

We rejected Mermaid SVG as a second interactive surface. That would have duplicated selection, accessibility, collaboration, and history behavior. Unsupported Mermaid families can remain as source, but they do not become editable Canvas nodes. Invalid source stays in a local draft and cannot replace the last valid shared graph.

Making the model operational without making it executable

A live practice needs real processes, network behavior, telemetry, and controlled failure. It is tempting to treat the architecture Canvas as a deployment specification and create Kubernetes objects from every box and line. We rejected that design.

A collaborative Canvas contains incomplete ideas, external systems, review annotations, and evidence. An ordinary diagram edit must not gain infrastructure authority. Executable behavior belongs to a validated, immutable Scenario Version.

The Scenario’s resource and relationship model compiles into a bounded runtime plan. A worker creates an isolated namespace, ResourceQuota, LimitRange, workload identity, default-deny network policy, explicit relationship policies, configuration, services, workloads, and controlled faults. Browser routes request desired state; they do not construct or apply manifests.

Readiness is based on live workload, service, endpoint, and event state. Midflight does not replace a failed live environment with simulated evidence. Ending or expiring the practice schedules namespace cleanup while the Practice record and Canvas evidence remain durable.

The live practice loop

When the runtime becomes ready, its metrics, logs, events, and bounded terminal output appear beside the investigation. The learner can attach a specific signal to a hypothesis, record an action and its safety condition, then verify whether the system changed as expected.

Practice completion binds the final Canvas snapshot before scoring. Returning to a completed Practice opens that immutable record. Continued investigation happens in a linked editable Canvas. This keeps the evaluated attempt explainable without preventing later exploration.

The first large-Canvas test failed

The graph also had to remain usable under density and collaboration. We tested a production-mode build with a staircase workload. One browser opened increasingly dense Canvases. We then increased concurrent users. Each step had to pass before the next began.

The first run exposed two independent limits. At 10 users, server requests competed for database connections during notification startup. At 1,000 nodes and 2,000 connections, moving one node could make the browser measure the whole graph again.

We reduced notification startup pressure and stopped the repeated whole-graph measurement. The final local test opened the 1,000-node, 2,000-connection Canvas in 10 Chromium sessions. All sessions joined within the test budget, and node movement stayed within the browser frame budgets.

The full workload, budgets, excluded runs, and before-and-after results are documented in How we made a 1,000-node Midflight Canvas work for 10 people. The measurements come from a local release build with the server and browsers on one computer. They do not establish current production latency.

What the graph preserves

Canvas begins with a map or a question. During practice it becomes a record of observations, uncertainty, evidence, action, and verification. Afterward, the exact graph supports a debrief and a reviewable Agent Skill.

Architecture, execution, and learning remain connected, but they do not collapse into one authority. Canvas owns the reasoning graph. Scenario owns executable meaning. Practice owns the attempt and its score. The runtime owns bounded execution. That separation lets the graph become operational while ordinary collaboration stays safe.