Architecture diagrams and playback

chartforgex architecture v1 describes a system and the request flows that run through it in one text block: typed nodes, groups and boundaries, labelled connections, and use cases whose ordered steps carry their request and response payloads. The parser produces an ordinary TopologyChart, so the same model drives:

• the static diagram (SVG, PNG, static HTML);
• the interactive player: step list, previous/play/next, a scrubber, keyboard keys, the active step's payload, and the matching sequence diagram kept in step, drawn in the topology's visual language (node cards with icons, subtitles and status dots as participants, groups as participant bands, neutral message lines with label pills, dashed replies, and the critical colour only for failed calls);
• one highlighted frame per step (SVG or PNG), a step-by-step visual story (SVG, PNG, GIF, APNG, HTML);
• a terminal drawing that text output and ConsoleMonster share.

The idea of playing request flows over an architecture diagram comes from Proschi. ChartForgeX keeps its own grammar style (one statement per line, key:value attributes, end-closed blocks) and has no load or cost simulation.

Example

```chartforgex architecture v1 {#orders title="Order flow"}
direction right

user client "Customer"
group backend "Backend"
  service api "Orders API"
  database db "Orders DB" status:healthy
end

client -> api "HTTPS"
api -> db "SQL"

usecase create "Create an order"
  client -> api "POST /orders" json {
    "sku": "A1",
    "quantity": 2
  }
  api -> db "INSERT order"
  db --> api "1 row"
  api --> client "201 Created" json { "id": 42 }
end
```

Two complete examples ship with the gallery and the tests: ad-replication.md (an attribute change replicating across two AD sites, plus a site-link failure) and tierbridge-file-journey.md (a file crossing from a Tier 2 share to a Tier 0 share through inspection, quarantine and approval).

Statements

Node types: node (generic), user/person/actor, team, client/app/application, service/api/function, server/host/vm, database/db, storage/share/bucket, queue/topic/bus, gateway/proxy/firewall, network, cloud/external, endpoint/device/workstation, process/job/worker, certificate, site/location, hub. Each maps to a TopologyNodeKind, which chooses the node's icon; icon:<id> picks any icon from the built-in catalog.

Arrows in a connection must be separate words (a -> b), so ids may contain hyphens.

Steps and payloads

A step travels over the connection that joins its two nodes, in either direction, so a response over api -> db is written db --> api. A step between nodes that no connection joins adds a dashed connection and reports CFXA006.

A payload follows the label: json {...}, xml <...>, text "...", or a bare {, [ or < (read as JSON or XML). A JSON payload may span several lines; it continues until its brackets balance, and its indentation is kept relative to the closing bracket.

Diagnostics

The parser reports every problem with its line and column and keeps going. Codes are stable:

The CLI writes them as warning CFXA006(12): ..., and the VS Code extension shows them on the line with the code.

Rendering from the command line

chartforgex-markup render renders one diagram. It reads Markdown with fences, or a file without fences as one architecture diagram (for example orders.cfx).

chartforgex-markup render ./orders.md                                  # text drawing plus the list of use cases
chartforgex-markup render ./orders.md --scenario create --step 2       # text with step 2 highlighted and its payload
chartforgex-markup render ./orders.md --format png --output orders.png
chartforgex-markup render ./orders.md --format png --scenario create --step all --output ./frames
chartforgex-markup render ./orders.md --format html --output orders.html

--format is text, svg, png or html, or comes from the --output extension. --columns sets the preferred text width (default 120), --ascii chooses ASCII borders, arrows and status markers, and --diagram <id> picks one diagram from a file with several. Authored labels and payloads are not transliterated. Text output covers architecture, topology and flow diagrams. HTML opens the interactive player; add ?scenario=<id>&scenarioStep=<n> to the page URL to open a step (zero-based).

From C#

var chart = new MarkupArchitectureParser().Parse(markdown).Document!;

var scenario = chart.ResolveScenario("create");          // source, target, label and payload per step
var sequence = chart.ToSequenceArtifact("create");       // the matching sequence diagram, as topology-style cards
var frame = chart.PrepareScenarioStep("create", 1);      // step 2 highlighted, same layout as chart.Prepare()
File.WriteAllBytes("step-2.png", frame.ToPng());

var page = chart.ToInteractiveHtmlPage(new TopologyRenderOptions { ActiveScenarioId = "create" }
    .WithHtmlScenarioPanel()
    .WithHtmlScenarioSequence());

var story = chart.ToScenarioStory("create");             // ChartForgeX.Stories: one scene per step
File.WriteAllBytes("create.gif", story.Prepare().ToGif());

var layout = TopologyCellLayout.Create(chart.Prepare(), new TopologyCellLayoutOptions { MaximumColumns = 100 });
Console.WriteLine(layout.Paint(TopologyCellPaintOptions.ForStep(scenario.Steps[1])).ToText());
Console.WriteLine(scenario.ToText(1));

Sequence interchange preserves participant cards, their subtitle and icon/status colours, and message-caption pill paint when exported to JSON and restored with ToSequenceArtifact().

On the ToInteractiveHtmlPage page with WithHtmlScenarioSequence(), the topology and the sequence diagrams share one type scale. Each fits the column while that costs at most an eighth of its size; past that it keeps its text size and scrolls inside its own frame, so a phone shows readable text instead of a thumbnail. Pages with zoom, export or fullscreen controls, or the selection panel, keep the fitted view.

Scenarios built in code use the same model: AddMessageStep(edgeId, TopologyScenarioInteraction.Response, "201", reverse: true) and WithPayload(json, TopologyScenarioPayloadFormat.Json) on a step.

While a step plays on the interactive page, its edge's arrow points the way the step travels: a response, or any step sent from the edge's target, shows the arrowhead at the caller's end, and the next step or a reset restores the drawn arrow. Edges drawn with arrows at both ends, or none, are left as drawn. The payload route and step titles name the interaction (request, message, response, failed call) with the page's localized HtmlChartText.Scenario* messages.

Interactive keys

When the scenario panel has focus: n or Right for the next step, b or Left for the previous one, p to play or pause, r or Home to restart, e or End for the last step.

Terminal drawing

TopologyCellLayout projects a detached prepared topology into terminal cells. Automatic grouped diagrams reuse compound ranking with compact region sizes, then route around the cell boxes and group captions. Authored positions, waypoints, ports and focused views retain their prepared geometry. Scenario steps and fitted output keep the same terminal node and group positions. Group boundaries keep one blank row above and below their content. Warning and critical connection labels take priority over healthy labels when space is limited. A failed step ends with ✕ (x in ASCII), matching the legend.

Paint returns a TopologyCellCanvas whose cells carry their glyph, role (node border, label, edge, arrow, group border, legend), element id, status and emphasis (highlighted, dimmed, focused, failed). ToText() gives plain text; terminal hosts such as ConsoleMonster map these cells to their own styles. TopologyCellPaintOptions takes live node values and statuses, a focused node and the active step. Node names, subtitles and live values occupy separate rows; ReservedValueWidth reserves horizontal room for values before painting. CompactToFit can omit subtitles and shorten node names while retaining operational edge-label priority. Wide diagrams can remain wider than MaximumColumns, which is a preferred width rather than a clipping boundary.

Automatic cell routing has bounded grid and search work. If a search cannot complete, a projected route is retained only when it still attaches to the final boxes and clears nodes, group borders and captions. Otherwise creation reports which edge could not be routed, rather than returning a detached or misleading connection.