Automatic Architecture Diagrams

Automatic Architecture Diagrams

Aura Tracker GCP can turn live project discovery into a display-ready Mermaid, Graphviz DOT, or SVG architecture diagram. The feature is read-only and belongs to the default archgraph module.

Ask naturally:

"Show my production architecture."

"Show my production architecture as Graphviz."

"Generate an SVG diagram of the whole project, grouped by region."

The MCP host should select gcp_generate_architecture_diagram; Mermaid is the default output.

---

Enable the Module

The module is enabled when all modules are loaded. To select it explicitly:

GCP_PROJECT_ID=my-project ./aura-tracker-gcp --modules archgraph

The diagram generator uses the same read-only discovery APIs and IAM permissions as Architecture Graph.

---

Production Scoping

The default request is deliberately production-scoped. A resource is treated as a production seed only when it has:

• an env, environment, or stage label whose value is prod or production; or
• an exact GKE namespace of prod or production.

Connected entrypoints, dependencies, and shared infrastructure are then included up to the requested traversal depth. Explicitly labelled resources from another environment are retained only when needed to show a relationship and are reported in the response warnings.

If no production seeds can be identified, the tool returns needs_scope and any environment candidates it discovered. It does not silently expose the whole project. Add consistent labels, pass a specific environment, or set whole_project: true explicitly.

---

Tool: gcp_generate_architecture_diagram

Parameter	Required	Default	Description
project_id	no	default environment	Environment alias or configured project ID to discover
environment	no	production	Environment label or namespace to select
whole_project	no	false	Include every environment instead of selecting one
format	no	mermaid	mermaid, graphviz, or svg
regions	no	all	Restrict discovery to one or more GCP regions
direction	no	LR	LR for left-to-right or TB for top-to-bottom
group_by	no	auto	auto, region, cluster, namespace, or none
max_depth	no	2	Relationship traversal depth, from 1 to 10
max_nodes	no	80	Render cap; hard maximum is 200
min_confidence	no	0.65	Minimum inferred-edge confidence, from 0 to 1
include_external	no	false	Include inferred endpoints outside the project
lookback_hours	no	168	Trace and mesh evidence window, from 1 to 720 hours

The structured response includes status, format, MIME type, source, scope decisions, discovered/rendered/omitted counts, warnings, partial collection errors, and generation time.

Possible statuses:

Status	Meaning
complete	The requested scope was discovered and rendered
partial	A diagram was rendered, but one or more GCP collectors reported an error
needs_scope	The default or requested environment could not be identified safely
empty	The scope was valid, but no resources matched it

---

Output Formats

Mermaid

Mermaid source is returned in a fenced mermaid block and needs no server-side renderer. It is a good default for chat clients, Markdown, GitHub, and documentation systems that support Mermaid.

Graphviz DOT

Graphviz source is returned in a fenced dot block. DOT generation is built in and does not require Graphviz to be installed.

SVG

SVG is rendered server-side with Graphviz dot and returned as an embedded image/svg+xml resource. The SVG is size-limited, parsed, and rejected if it contains scripts, embedded foreign content, event handlers, links, or external resource references.

The official container includes Graphviz. For a local binary install, put dot on PATH or set:

GRAPHVIZ_DOT_PATH=/usr/local/bin/dot

If Graphviz is unavailable, request Mermaid or Graphviz DOT source instead.

---

More Examples

Production, default Mermaid

"Show my production architecture for my-project."

Specific environment and region

"Draw the staging architecture in us-central1, top to bottom."

Small dependency view

"Show production with at most 40 nodes and one level of dependencies."

Explicit whole-project view

"Generate a Graphviz diagram for the whole project, grouped by region."

Include external endpoints

"Diagram production and include external services it calls."

---

Determinism, Limits, and Privacy

• Nodes, edges, groups, and generated aliases are sorted for stable output.
• Low-confidence inferred Graphviz and Mermaid relationships use a dashed style.
• The default 80-node cap keeps diagrams readable; the hard cap is 200.
• Discovery errors are returned alongside partial diagrams instead of being hidden.
• Ambiguous telemetry names are skipped unless cluster/location/namespace provenance identifies one unique node.
• VPC Flow Logs and resource IAM policies are not collected as diagram-edge evidence; the tool does not fabricate those relationships.
• The normal anonymization chain also scrubs Mermaid, DOT, embedded SVG text, and structured diagram output when anonymization is enabled.
• Diagram generation never changes GCP resources.

For the underlying resource and relationship model, cache behavior, APIs, and IAM requirements, see Architecture Graph.