Skip to content

gds_viz.architecture

Generate a Mermaid flowchart from a GDSSpec.

Renders an architecture-level view with blocks grouped by role or tag, entity cylinders, and dependency wires.

Parameters:

Name Type Description Default
spec GDSSpec

The GDS specification to visualize.

 required
group_by str | None

Tag key to group blocks by. None groups by GDS role.

 None
show_entities bool

If True, render entity cylinders with state variables.

 True
show_wires bool

If True, render dependency edges from wirings.

 True
theme MermaidTheme | None

Mermaid theme — one of 'default', 'neutral', 'dark', 'forest', 'base'. None uses the default ('neutral').

 None

Returns:

Type Description
str

Mermaid flowchart diagram as a string.
Source code in packages/gds-viz/gds_viz/architecture.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def spec_to_mermaid(
    spec: GDSSpec,
    *,
    group_by: str | None = None,
    show_entities: bool = True,
    show_wires: bool = True,
    theme: MermaidTheme | None = None,
) -> str:
    """Generate a Mermaid flowchart from a GDSSpec.

    Renders an architecture-level view with blocks grouped by role or tag,
    entity cylinders, and dependency wires.

    Args:
        spec: The GDS specification to visualize.
        group_by: Tag key to group blocks by. None groups by GDS role.
        show_entities: If True, render entity cylinders with state variables.
        show_wires: If True, render dependency edges from wirings.
        theme: Mermaid theme — one of 'default', 'neutral', 'dark', 'forest',
               'base'. None uses the default ('neutral').

    Returns:
        Mermaid flowchart diagram as a string.
    """
    lines = [theme_directive(theme), "flowchart TD"]
    query = SpecQuery(spec)

    # Class definitions
    lines.extend(classdefs_for_all(theme))

    # Render grouped blocks
    if group_by is not None:
        sg_styles = _render_tag_groups(lines, spec, group_by)
    else:
        sg_styles = _render_role_groups(lines, query, spec)

    # Entity cylinders
    if show_entities:
        _render_entities(lines, spec, query)

    # Dependency wires
    if show_wires:
        _render_wires(lines, spec, query)

    # Subgraph background styling
    lines.extend(subgraph_style_lines(sg_styles, theme))

    return "\n".join(lines)