Architecture Simulator
A what-if engine that runs against the model itself. The architect picks a target, picks a change, and the simulator colours every downstream casualty by severity. Mitigations are structured. The plan is saved as a hypothesis that can be reopened, cloned, cited from an ADR, or bundled with siblings for an options paper.
Change as a Model Concept
Treating change as a first-class model concept is the same shift NeoArc applies to architecture itself. The current state and the proposed change are both expressed against the same intent graph. Lineage is walked by the same engine that derives projections and serves impact analysis at save time. The simulator does not simulate something separate from the model. It runs the model forward under a hypothesis and reports the consequences.
The simulator is hosted in-place on the architecture map. Activating it does not switch the architect into a different tool. The same canvas, the same nodes, the same edges; the simulator overlays a banner, recolours nodes by impact severity, and animates edges along the lineage. Cancelling the simulator discards everything. Saving freezes the proposal as a hypothesis file in the project.
Three Granularities
The simulator works at three zoom levels. The architect picks the level that matches the change being proposed. The same cascade engine runs at every level, scoped to what is anchored.
Five Change Gestures
The architect picks an action from the simulator banner. The action drives the severity at every downstream consumer.
| Action | Severity | When to Use |
|---|---|---|
| Retirement | High | The target is being removed entirely. Every consumer must be reconciled before the projection or entity is taken down. |
| Deprecation | Medium | The target remains for now but is signalled for replacement. Consumers should plan migration; warnings appear on every downstream artefact. |
| Rename | Medium | The target's identifier changes but its semantics do not. Every consumer must update references; the data and shape stay the same. |
| Type Change | High | The target's shape changes (string to integer, scalar to object, optional to required). Consumers may break at runtime even if names stay the same. |
| Move | Low | The target is reparented or relocated within the model. Consumers that resolve by name will continue to work; tools that follow paths may need updating. |
Trace and Impact Modes
The simulator runs in one of two modes. Trace mode walks lineage as animated dashes without proposing a change, answering 'what depends on this?'. The banner is cyan, the canvas is uncoloured, and edges flow in the chosen direction. Impact mode runs the cascade and colours casualties by severity, answering 'what would break if I did this?'. The banner is red, nodes carry coloured rings, and the property inventory populates at the bottom of the canvas. The architect can switch between the two without losing the target.
Marks and Shims: Structured Mitigations
When the cascade has run, the architect proposes mitigations. A mark-as-fixed is shorthand for 'we will handle this' and shields the node and everything downstream of it. A shim is the structured form of a mitigation: it carries a kind, an anchor, notes, and optional links to existing or proposed artefacts. Shims stack, marks stack, and the cascade re-runs after every edit so the architect always sees the current blast radius.
Property-Level Coverage
Property-level shims do more than shield the row they anchor. The simulator walks the projection mapping graph forward from each property shim and marks every downstream row that consumes the property as covered. This is what makes a single shim on a source field worth more than annotating every consumer separately. The architect proposes one mitigation; the simulator computes which downstream rows it shields, and the property inventory shows them as covered without any further input.
Hypotheses as Durable Artefacts
When the architect saves the simulation, the result is written to .neoarc-studio/hypotheses/<name>.hypothesis.json in the project. The hypothesis carries the change, the marks, the shims, and any links to pages, diagrams, ADRs, or sibling hypotheses. Reopening it replays the simulation: the canvas re-colours, the property inventory rebuilds, every shim is back where the architect left it.
Hypotheses can be cloned. The clone carries the same name, description, and links as a starting point, and the architect edits it into a sibling proposal. Sibling hypotheses are linked to each other through hypothesisLinks, which is how an options paper bundle is expressed: three hypotheses for three options, each pointing at the other two as alternatives.
The Cascade Re-runs After Every Edit
Every mark and every shim triggers a re-simulation. The cascade engine recomputes which nodes are effectively fixed (unreachable after mitigations are applied), which sit behind protection but still have an open path (partial), and which remain in the blast radius. The architect always sees the current state of the proposal, not a static snapshot. This is what closes the loop between proposing a mitigation and seeing whether it actually works.
Where the Simulator's Reach Ends
The simulator does not replace ADRs, options papers, or migration plans. It feeds them. The architect uses the simulator to reason about a change, cites the hypothesis from the ADR, bundles sibling hypotheses for the options paper, and hands the chosen plan to a delivery team that owns the work. The simulator's reach stops at the architecture. Everything beyond is built on top of the technical truth it captures.
Architecture maps visualise the complete data flow from external sources through the canonical model, projection layers, APIs, and UI views on an interactive grid.
How NeoArc Studio verifies that architectural changes correctly propagate across all node types and edge types in the Intent Graph, with automated tests covering every cross-domain scenario.