Spectrion treats diagrams as working artifacts, not as disposable images.

The goal is not just to draw a picture. The goal is to create a persistent, editable, inspectable artifact that can explain a system, link back to source files, evolve over time, and help the agent reason about future changes.

In Spectrion, a diagram is not the final product. It is the visual layer of a deeper artifact model.

From Images to Artifacts

A regular generated image answers one question:

What does this look like?

A Spectrion diagram should answer more:

What is this component?
Where does it live in the codebase?
How does execution pass through it?
What changed between versions?
How can the agent use this map to make the next change safely?

That is why Spectrion stores diagrams as artifacts with source, rendered output, metadata, and revision history.

Diagram Artifacts

The first layer is the DiagramArtifact.

It is responsible for the reliable rendering workflow:

• diagram source;
• syntax validation;
• render output;
• sanitized SVG;
• PNG preview;
• versioned storage;
• export;
• future revision from the existing source.

A diagram artifact may contain files like:

architecture.dot
architecture.svg
architecture.png
manifest.json

or:

runtime-loop.mmd
runtime-loop.svg
runtime-loop.png
manifest.json

The important point is that the source is preserved. The agent should not regenerate a diagram from scratch every time the user asks for a change. It should revise the existing artifact.

For example:

Add an approval gate before tool execution.

Spectrion should load the existing diagram source, patch it, validate it, render a new version, and return a short summary of what changed.

That is the difference between a toy image generator and a real runtime artifact.

Why PNG Is Not Enough

PNG is useful for previewing. It is not enough for work.

A PNG cannot reliably tell the agent:

• which block is ToolExecutor;
• which source file defines it;
• which edges represent runtime flow;
• which components changed between versions;
• which execution trace passed through it.

That is why Spectrion keeps multiple layers:

architecture.png          # visual preview
architecture.svg          # vector render
architecture.mmd/.dot     # editable source
architecture.graph.json   # semantic graph
trace-map.json            # trace-to-node mapping
summary.md                # human-readable explanation

Together, these files make the diagram usable by both humans and agents.

Interactive Architecture Artifacts

The second layer is the InteractiveArchitectureArtifact.

This is not just a rendered diagram. It is a semantic map of a system.

It can store:

• system components;
• relationships between components;
• node descriptions;
• source references;
• related files;
• trace mapping rules;
• version history;
• architecture summaries;
• exportable evidence bundles.

The boundary is important:

DiagramArtifact shows structure visually.
InteractiveArchitectureArtifact gives structure meaning.
RunTraceArtifact records execution.
Overlay shows execution on top of structure.

Architecture artifacts should not store raw executions directly. They store the map of the system. Execution traces live separately as RunTraceArtifacts and can be overlaid when needed.

The Semantic Graph Layer

An SVG only knows about shapes and text. It does not know what a runtime component is.

Spectrion adds architecture.graph.json so every important block becomes structured data:

{
  "id": "tool_executor",
  "label": "ToolExecutor",
  "kind": "runtime_component",
  "description": "Dispatches tool calls, applies policy, and routes calls to the correct tool runtime.",
  "source_refs": [
    {
      "path": "Agent/Tools/ToolExecutor.swift",
      "symbol": "ToolExecutor"
    }
  ],
  "tags": ["tools", "policy", "execution"]
}

This makes the architecture usable as a navigation and reasoning layer.

The user can ask:

Explain ToolExecutor.

Spectrion does not need to guess from the image. It can load the graph node, source refs, related traces, and summary, then produce a grounded explanation.

Trace Overlay

The most powerful extension is runtime trace overlay.

The user can ask:

Show how the last request moved through the runtime.

Spectrion can map trace events onto architecture nodes:

User Message
-> AgentRuntime
-> Context Builder
-> Provider Stream
-> ToolExecutor
-> Diagram Tool
-> Artifact Store

That turns architecture from a static diagram into a visual debugger.

Instead of reading raw logs alone, the user can see the execution path on top of the system map.

Why GraphViz Matters

Mermaid is a strong default for simple diagrams:

• small flowcharts;
• task flows;
• simple sequence diagrams;
• lightweight documentation.

For full architecture maps, GraphViz is usually a better default.

It handles:

• larger graphs;
• many edges;
• clusters;
• service boundaries;
• database layers;
• backend/frontend/data-flow maps;
• architecture layouts with more stable spacing.

Mermaid remains useful, but full project architecture should prefer GraphViz unless the user explicitly asks for another engine.

This also prevents common Mermaid failures such as subgraph/node ID collisions, invalid chained edges, and layout collapse on dense architecture maps.

Source and Engine Rules

Diagram engines must stay strict:

• Mermaid source goes to Mermaid.
• GraphViz DOT source goes to GraphViz.
• PlantUML source must be valid @startuml ... @enduml.
• Structurizr source must be valid workspace { ... } DSL.
• Markdown fences should be stripped before rendering.
• Mermaid subgraph IDs and node IDs must not collide.

For Mermaid, a safe convention is:

sg_* for subgraph IDs
n_*  for node IDs

For GraphViz, clusters should be explicit:

subgraph cluster_backend {
  label="Backend";
  api;
  worker;
  database;
}

The renderer should reject invalid source with recoverable errors. The agent can then repair the source and render again.

Security and Privacy

Architecture diagrams can contain sensitive information:

• internal service names;
• database names;
• file paths;
• security boundaries;
• provider flows;
• approval logic;
• runtime events;
• infrastructure topology.

Spectrion uses strict defaults:

• SVG is sanitized;
• PNG is the safe preview format;
• source is saved separately;
• public renderers are avoided;
• rendering goes through a trusted Spectrion backend;
• raw trace payloads are redacted by default;
• interactivity is implemented in the UI, not inside the SVG.

Interactive behavior should not be embedded as executable SVG logic. The safer model is:

rendered image + sidecar JSON + UI overlay

The SVG or PNG displays the structure. The sidecar files provide meaning.

How It Feels in the Product

A user can say:

Draw the full architecture of this project.

Spectrion should:

1. inspect the project;
2. identify components and flows;
3. build a semantic graph;
4. choose the best diagram engine;
5. render the diagram;
6. save source, SVG, PNG, graph metadata, and summary;
7. show an architecture artifact card;
8. open the Architecture Viewer.

The viewer can expose:

Preview | Source | Explain | Trace | History

Preview

Shows the rendered architecture.

Source

Shows the editable diagram source.

Explain

Explains selected components using graph metadata and source refs.

Trace

Overlays a selected runtime trace on top of the architecture.

History

Shows versions, summaries, and diffs.

Multi-Layer Architecture Maps

A full architecture map should provide the system overview first.

But real systems often need deeper layers:

• service-level architecture;
• module-level architecture;
• data-flow diagrams;
• database/schema diagrams;
• runtime execution paths;
• deployment topology;
• integration maps.

Spectrion should support progressive deepening.

The first map gives the user the full system shape. Then the user can ask:

Expand the backend service.

or:

Show how data reaches the database.

or:

Show weak points in this architecture.

The agent should use the existing architecture artifact as context instead of starting from zero. This makes the map a working memory for the project.

Evidence Bundles

Architecture artifacts can be exported as evidence bundles:

architecture.svg
architecture.png
architecture.dot
architecture.graph.json
trace-map.json
summary.md
diff.json

This is useful for:

• pull requests;
• technical documentation;
• bug reports;
• audits;
• onboarding;
• architecture reviews;
• implementation planning.

The artifact becomes proof of work, not just a chat answer.

Product Value

The real value is not that Spectrion can draw diagrams.

The value is that Spectrion can turn architecture into a living artifact.

Users can:

• inspect systems visually;
• understand components;
• connect diagrams to code;
• trace execution paths;
• update architecture after code changes;
• export documentation;
• use the map as context for future agent work.

That changes the role of diagrams from decoration to infrastructure.

Final Principle

The core idea is:

Diagram Artifacts show structure.
Interactive Architecture Artifacts show structure, meaning, and execution.

In other words:

Spectrion turns architecture into a living, inspectable, traceable artifact.

That is what makes diagrams in Spectrion more than visual output. They become part of the agent runtime workspace.