15 Lines of Declarative Python

from drawlib.diagrams.architecture import (
    ArchitectureDiagram, GcpIcon, Node, NodeGroup, PhosphorIcon,
)
from drawlib.styles import Styles

d = ArchitectureDiagram(
    node_style=Styles.Primary,
    node_text_style=Styles.DarkBold,
    edge_style=Styles.DarkBold,
    edge_text_style=Styles.Dark,
    node_card_style=Styles.Neutral,
)
vpc = d.add(NodeGroup("Production Cloud VPC", padding=7), (26, 8))
client = d.add(Node("Web Client", width=18, height=16, icon=PhosphorIcon.GLOBE), (8, 42))
gw = vpc.add(
    Node("API Gateway", width=20, height=16, icon=GcpIcon.CLOUD_API_GATEWAY,
         card_style=Styles.PrimaryFlat, text_style=Styles.WhiteBold),
    (16, 34),
)
sql = vpc.add(Node("Cloud SQL", width=20, height=16, icon=GcpIcon.CLOUD_SQL), (54, 50))
bq = vpc.add(Node("BigQuery", width=20, height=16, icon=GcpIcon.BIGQUERY), (54, 18))

d.connect(client, gw, label="HTTPS")
gw.fork([sql, bq], at_x=58, padding=1.5)
d.draw()

• Auto-Bounding Containers: NodeGroup wraps child nodes automatically.
• Smart Orthogonal Edges: .connect() and .fork() clip cleanly at node boundaries.

1. Canvas Lifecycle

from drawlib.canvas import clear, save, setup
from drawlib.shapes import rectangle
from drawlib.styles import Styles

clear()
setup(width=100, height=70)
rectangle((50, 35), width=40, height=20,
          style=Styles.PrimaryFlat,
          text="Centered at (50, 35)",
          text_style=Styles.WhiteBold)
save("diagram.svg")

2. Core Spatial Rules

• Bottom-Left Origin (0, 0): X increases rightward (0 → width); Y increases upward (0 → height).
• Center-Anchored Primitives (cx, cy): Shapes (rectangle, circle, cylinder, rhombus, etc.) and icons are anchored at their geometric center (cx, cy), making horizontal (cy equal) and vertical (cx equal) alignment trivial.
• Z-Order Layering Discipline: Draw background containers first, entity shapes second, connector lines third, and foreground badges/text last.
• 10–15% Safe Perimeter Margin: Keep outer margins clear so labels and arrowheads never clip.

Two Ways to Enable the Coordinate Grid

1. CLI Flag (-g / --grid) — Recommended

   • Render any Python script or embedded Markdown diagram with a temporary coordinate ruler overlay:

   # Preview a standalone script with grid
   uv run drawlib show arch.py -g -o preview.png
   
   # Preview an embedded Markdown diagram with grid
   uv run drawlib show docs_src/index.md arch.png -g -o preview.png
   

2. Programmatic setup(..., grid=True)

   • Turn on the grid directly inside setup() during interactive layout design:

   setup(width=100, height=65, grid=True, grid_xpitch=10, grid_ypitch=10)
   

Why the Grid Matters

• Zero Guesswork: Immediately see that Client sits at (25, 30), Gateway at (52, 30), and DB at (78, 30).
• Multimodal AI Anchor: Allows AI coding agents to read exact (x, y) coordinates directly from the rendered image.

5 Directed Block Arrows + Speech Callouts

from drawlib.shapes import (
    arrow, arrow_arc, arrow_l, arrow_polyline, arrow_u, bubblespeech,
)
from drawlib.styles import Styles

# 1. Straight block arrow (supports embedded shaft text)
arrow((10, 66), (48, 66), tail_width=4, head_width=9,
      head_length=6, style=Styles.PrimaryFlat,
      text="Data Transfer", text_style=Styles.WhiteBold)

# 2. L-shaped & U-turn block arrows (with rounded elbow r)
arrow_l((25, 42), width=26, height=18, tail_width=3.5,
        head_width=8, head_length=6, style=Styles.SecondaryNeutral.patch(shape_r=4))
arrow_u((68, 42), width=24, height=20, tail_width=3.5,
        head_width=8, head_length=6, style=Styles.BlueNeutral.patch(shape_r=4))

# 3. Circular arc & multi-segment polyline block arrows
arrow_arc((25, 16), width=22, height=18, angle_start=180,
          angle_end=20, tail_width=3, head_width=7, style=Styles.PrimaryNeutral)
arrow_polyline([(52, 10), (66, 10), (66, 22), (88, 22)],
               tail_width=3, head_width=7, head_length=5, style=Styles.Neutral.patch(shape_r=3))

• Note: arrow() supports embedded text; for arrow_l, arrow_u, arrow_arc, and arrow_polyline, place external text() labels alongside the shaft.

7 Connector Primitives & Arrowheads

from drawlib.lines import (
    line, line_arc, line_bezier1, line_bezier2,
    line_curved, lines, lines_curved,
)
from drawlib.styles import Styles

# 1. Straight line & orthogonal polyline
line((10, 70), (45, 70), arrow_head="->", style=Styles.DarkBold)
lines([(55, 65), (72, 65), (72, 75), (90, 75)],
      arrow_head="->", style=Styles.PrimaryBold)

# 2. Curved arc spline (bend) & filleted polyline (r)
line_curved((10, 44), (45, 44), bend=0.35,
            arrow_head="<->", style=Styles.PrimaryBold)
lines_curved([(55, 38), (72, 38), (72, 52), (90, 52)],
             r=4.0, arrow_head="->", style=Styles.DarkBold)

# 3. Quadratic/Cubic Beziers & Elliptical Arcs
line_bezier1((10, 16), (45, 16), cp=(27, 30),
             arrow_head="->", style=Styles.SecondaryBold)
line_bezier2((55, 10), (90, 24), cp1=(72, 10), cp2=(72, 24),
             arrow_head="->", style=Styles.BlueBold)

• Arrowhead Options: "" (none), "->" (forward), "<-" (reverse), "<->" (bidirectional).
• Filled vs. Stick Heads: Customize via style.patch(line_arrow_head_fill=True, line_arrow_head_scale=22).

1. Horizontal & Vertical Text Primitives

from drawlib.fonts import Font, FontFile, FontMonoSpace, FontRoboto, FontSourceCode
from drawlib.styles import Styles
from drawlib.text import text, text_vertical

# Anchor alignment via halign & valign
text((20, 60), "Left Anchor",
     style=Styles.DarkBold.patch(halign="left"))
text((80, 60), "Right Anchor",
     style=Styles.DarkBold.patch(halign="right"))

# Built-in font families & custom TTF/OTF files
text((50, 40), "Roboto Bold",
     style=Styles.PrimaryBold.patch(text_font=FontRoboto.ROBOTO_BOLD))
text((50, 25), "Custom FontFile(.ttf)",
     style=Styles.AccentBold.patch(text_font=FontFile("brand.ttf")))

# Vertically stacked characters
text_vertical((12, 30), "TIER", style=Styles.MutedBold)

2. Automatic SVG @font-face Bundling

• When compiling slides or docs with .svg diagrams, Drawlib automatically copies required .ttf/.otf font files into _assets/fonts/ and injects @font-face rules so browsers and PDF exports render identically anywhere.

1. Dual Icon Engine (phosphor & gcp)

from drawlib.icons import gcp, phosphor
from drawlib.images import Dimage, image
from drawlib.styles import Styles

# Vector Phosphor icons (5 weights: thin, light, regular, bold, fill)
phosphor.cpu((20, 65), width=12, style=Styles.PrimaryBold)
phosphor.database((45, 65), width=12, style=Styles.PrimaryFlat)

# Official Google Cloud architecture icons (multi-color PNGs)
gcp.compute_engine((20, 40), width=14, style=Styles.Neutral)
gcp.cloud_sql((45, 40), width=14, style=Styles.Neutral)

2. Bitmap Manipulation with Dimage

• Load external .png/.jpg/.webp assets or capture sub-diagrams in memory via get_dimage_from_code().
• Chain non-destructive effects: .grayscale(), .sepia(), .invert(), .brightness(), .blur(), .mosaic(), .trim(), and .make_transparent().

image((30, 15), width=16, image="_assets/linux.png")
image((65, 15), width=16, image=Dimage("_assets/linux.png").grayscale())

1. Systematic Styles.<Color><Variant> Matrix

from drawlib.styles import Colors, Styles, get_intermediate_colors

# Always import PascalCase Styles & Colors!
hero = Styles.PrimaryFlat              # Saturated focal point
card = Styles.PrimaryNeutral           # Soft tinted-neutral card
base = Styles.Neutral                  # Calm slate/white baseline
zone = Styles.MutedDashed              # Container boundary

# Immutable overrides via .patch()
custom = Styles.PrimaryBold.patch(line_width=3.0, text_size=12)

# Smooth color interpolation for gradients & heatmaps
ramp = get_intermediate_colors(Colors.Primary, Colors.Secondary,
                               num=3, include_ends=True)

2. The 50%+ Neutral Baseline Rule

• Avoid Rainbow Chaos: Never fill every node with competing saturated colors (PrimaryFlat, WarningFlat, DangerFlat, PurpleFlat).
• Ground 50%+ in Calm Neutrals: Use Styles.Neutral, Styles.PrimaryNeutral, Styles.SecondaryNeutral, Styles.BlueNeutral for standard components, reserving Styles.PrimaryFlat / Styles.AccentFlat (text_style=Styles.WhiteBold) strictly for 1–2 focal hero nodes.

10 High-Level Structured Components (drawlib.smartarts)

Instead of manually calculating polygon vertices and text offsets, drawlib.smartarts automates layout geometry for 10 essential diagram patterns:

Unified 4-Phase Component Lifecycle

1. Instantiate: Configure default style and text_style tokens.
2. Register (add(..., show=True)): Returns a mutable item reference.
3. Mutate in Place: Toggle item.show = False or patch item.style across animation frames without shifting layout coordinates.
4. Render (draw(xy, scale=1.0)): Uniformly scales shapes, strokes, and fonts around xy.

Linear Stages vs. Continuous Iterations

1. ChevronProcess — Phased Pipelines

• Interlocking Geometry: Automatically computes chevron tip angles (corner_angle=60.0) and uniform item widths across total width.
• Clean Entry Edge: flat_left_end=True renders the first stage as a flat-backed pentagon while subsequent stages interlock seamlessly.
• Dual-Line Labels: Each stage supports a primary text heading and a secondary description subtitle with independent style overrides.

2. Cycle — Circular & Radial Workflows

• Trigonometric Orbit: Distributes N nodes ("circle", "rectangle", or "none") evenly around orbit radius starting from start_angle=90.0 (12 o'clock).
• Curved Arc Connectors: Connects steps with circular arc arrows (arrow_type="arc") and configurable arrow_color_mode ("monochrome", "match_source", "match_target").
• Central Command Hub: Calling cycle.set_center(...) places a central hub node inside the orbit for radial governance or SRE command loops.

Structured Card & Layer Components

1. BoxList — Directional Card Sequences

• Aligns sequential cards along "left", "right", "bottom", or "top" orientations.
• Ideal for status badges, KPI ribbons, and linear step stacks.

2. GridLayout — Multi-Span Architecture Matrices

• Bottom-Left Indexed: (col=0, row=0) starts at the bottom-left cell; rows increment upward (+y) and columns increment rightward (+x).
• Cell Spanning: Any item can span multiple columns and rows (position=(col, row), width=w, height=h) to model full-width ingress/platform layers alongside multi-column microservice cells.
• Outer Container: Optional outer_style (including shape_r) wraps the entire matrix in a dashed or solid boundary.

3. Pyramid — Proportional Tiered Hierarchies

• Slices a triangular pyramid into an apex triangle and progressive trapezoidal tiers.
• Supports direction="bottom" (upright) or "top" (inverted funnel) and order="vertex_to_base" or "base_to_vertex".

Two Complementary Tree Engines

1. TreeNode — Directory & Package Hierarchies

• Top-Left Anchored: Steps downward row-by-row with crisp orthogonal ├ and └ connector lines.
• Cascading Root Styles: Set text_style, line_style, and margins once on the root TreeNode; all descendants inherit them automatically.
• Custom Icon Attachments: Use TreeNode.register_drawing_item(...) and .set_drawing_item(name) to prepend or append Phosphor icons (phosphor.folder, phosphor.file_py, phosphor.file_code).

2. MindMapNode — Two-Pass Radial & Org Trees

• Pass 1 (Bottom-Up Measurement): Recursively measures exact subtree bounding heights and widths so branches never collide.
• Pass 2 (Orthogonal Routing): Routes right-angled junction lines from the center root node across all 4 directions (branch="left", "right", "top", "bottom").
• Flexible Node Shapes: Mix "ellipse", "rectangle", and borderless "none" leaf labels.

Tabular Precision & Vector Syntax Highlighting

1. Table — Fine-Grained Matrix Styling

• Flexible Sizing: draw(xy, width, height, data) distributes columns evenly, while draw_flexible(xy, column_widths, row_heights, data) gives exact per-column and per-row dimensions.
• Zebra & Cell Highlighting:
  • set_style_cell_evenodd(even_color, even_text_style, odd_color, odd_text_style) applies alternating row stripes.
  • set_style_cell(background_color, text_style, rows=[...], columns=[...]) highlights specific SLA breaches or target cells.
• Selective Borders: set_style_border(top=..., top2=..., bottom=..., between_rows=...) controls perimeter and inner rules independently.

2. SourceCode — Vector Code Containers

• Renders Pygments-tokenized code directly onto the canvas as crisp vector glyphs and rounded containers (show_linenum=True).
• Built-in themes ("dark", "monokai", "default", "google", "monochrome") and CJK-aware monospace fonts (font_lang="en" | "ja").

Why Built-In Vector Charts Beat External Plotting Tools

Traditional workflows force you to plot charts in Matplotlib/Excel, export PNGs, and paste them next to architecture diagrams—resulting in mismatched fonts, blurry raster scaling, and broken visual alignment.

4 Pillars of drawlib.charts

1. First-Class Canvas Coexistence: Charts render directly onto the Drawlib canvas at any (x, y) coordinate. You can draw connector arrows directly from an architecture microservice node to a live telemetry BarChart or PieChart.
2. Deterministic Bounding Layout: Explicit width, height, and radius parameters guarantee predictable margins without layout drift.
3. Nice Numbers & Logarithmic Axes: Axis(scale="linear" | "log") automatically computes human-readable tick steps ($1, 2, 5 \times 10^k$) or base-10 powers ($10^k$) with custom formatters (format="{:.1f}M", unit="ms").
4. Animation-Ready (show & draw_ratio): Toggle series.show = False without rescaling axes, or animate draw_ratio (0.0 -> 1.0) along "bottom_to_top" or "left_to_right".

Cartesian Data Visualization

1. BarChart — Grouped, Stacked & Log Scales

• Supports orientation="vertical" | "horizontal" and bar_mode="group" | "stack".
• Rounded bar tip corners (bar_r=0.8), direct value labels (value_format="{:.0f}M"), and linear or logarithmic (scale="log") axes.

2. LineChart — Linear Polylines & Smooth Splines

• Set smooth=True for cubic-like spline interpolation or smooth=False for exact vertex segments.
• Per-series line_style ("solid", "dashed", "dotted"), line_width, and point_shape ("circle", "square", "none").

3. AreaChart — Cumulative & Overlapping Streams

• mode="stack" layers series cumulatively to show total volume breakdown; mode="overlap" renders semi-transparent overlapping polygons (fill_alpha=0.35).
• Shared fluent helpers across all three: configure_x_axis(...), configure_y_axis(...), and standalone draw_legend(xy, ...).

Proportions, Trade-Offs & Correlations

1. PieChart — Solid Pies & KPI Donuts

• Set hole_ratio=0.5 (up to 0.9) with center_text to render executive KPI donut rings.
• Supports per-slice outward emphasis (explode=2.5) and automatic label suppression on tiny wedges ($<4%$).

2. RadarChart — Multi-Axis Trade-Off Polygons

• Evaluates 3+ symmetric dimensions radiating from a central origin (grid_shape="polygon" | "circle").
• Ideal for comparing architectural trade-offs (e.g., Microservices vs. Monolith across Scalability, Latency, Reliability, Operability, and Velocity).

3. ScatterChart — XY Plots & 3D Bubbles

• Plots continuous (x, y) coordinates or 3-tuple (x, y, radius) bubbles across dual independent linear or log axes.
• Combine named add_series(...) clusters with individually labeled benchmark points via chart.add(xy, label=...).

Declarative Project Schedules as Code

Maintaining engineering roadmaps in external spreadsheet or GUI tools makes version control diffs impossible. GanttChart models schedules directly in Python:

Core Schedule Building Blocks

• add_section(name): Full-width horizontal divider bands that group tasks by workstream or team.
• add_task(name, start, end, style, progress=...):
  • start and end accept column names ("Apr") or continuous floating-point column indices (1.5 = middle of 2nd column).
  • progress (0.0 to 1.0) renders a two-tone completion fill bar with percentage text (progress_text_style).
• add_milestone(name, at, style): Renders a diamond milestone marker at exact timeline coordinate at.
• add_dependency(from_task, to_task): Routes orthogonal finish-to-start dependency arrows between tasks.
• add_marker(at, style, label="Today"): Draws a vertical status line across all rows.

Purpose-Built Engines with Shared Architecture

Unlike black-box text-to-diagram tools (PlantUML, Mermaid) that scramble your layout whenever a label changes, drawlib.diagrams combines deterministic coordinate placement with intelligent boundary & wire automation:

4 Shared Architectural Guarantees

1. Center & Icon Coordinate Anchoring: Passing xy=(x, y) to d.add(...) anchors the exact geometric center of the card or icon—ensuring aligned nodes always connect with perfectly straight horizontal or vertical wires.
2. Universal Connectable Protocol: Nodes, groups, entities, classes, states, and Junction waypoints share dynamic boundary clipping, start_side/end_side port selection, and smart "orthogonal" / "direct" / curved bend routing.
3. Layout-Preserving show=True/False: Hiding any node (node.show = False) automatically hides its connected edges and dangling fork() stems while keeping NodeGroup bounds, swimlanes, and lifeline spacing 100% locked.
4. Uniform draw(xy, scale=1.0): Scales the entire diagram proportionally around bottom-left xy.

Why ArchitectureDiagram Wires Never Kink

In naive diagramming tools, adding a 2-line label underneath an icon shifts the node's bounding center downward, causing horizontal arrows between aligned icons to develop ugly Z-bends.

3 Core Innovations

1. Card-Centric Coordinates (xy = Card Center):
   • When you call d.add(Node("Label", width=w, height=h, icon=...), xy=(x, y)), (x, y) is strictly the center of the node card (w, h).
   • Multi-line labels fit inside the card without shifting the card's center—so nodes sharing the same y always connect with a razor-straight horizontal line!
2. Auto-Bounding NodeGroup Containers:
   • Calling group = d.add(NodeGroup(title="...", padding=6.0), xy=(gx, gy)) creates a relative coordinate group that automatically expands its boundary box to enclose all child nodes and nested subgroups.
3. 1-to-N Bus Fan-Out (node.fork()):
   • lb.fork([svc1, svc2, svc3], at_x=55.0, padding=2.0) creates a clean vertical distribution bus at at_x with orthogonal taps into every target node.

Official Cloud & Interface Icons Built In

drawlib.diagrams.architecture integrates directly with Drawlib's icon ecosystem:

• GcpIcon (259 Official Icons):
  • Compute & Containers: GcpIcon.GOOGLE_KUBERNETES_ENGINE, GcpIcon.CLOUD_RUN, GcpIcon.COMPUTE_ENGINE
  • Networking & Security: GcpIcon.CLOUD_LOAD_BALANCING, GcpIcon.CLOUD_ARMOR, GcpIcon.CLOUD_CDN
  • Databases & Storage: GcpIcon.CLOUD_SQL, GcpIcon.CLOUD_SPANNER, GcpIcon.CLOUD_STORAGE, GcpIcon.BIGQUERY
• PhosphorIcon (1,531 Vector Icons):
  • Clients, browsers, devices, locks, queues, and generic infrastructure symbols.

Nested Hierarchical NodeGroups

• Nest Public Subnet and Private Subnet groups inside an outer VPC Network group (vpc.add(NodeGroup(...), xy=...)).
• Child coordinates inside a NodeGroup are local to that group's origin, making subnet refactoring effortless.

ISO 5807 Flowcharts with Cross-Lane Coordinates

FlowDiagram models operational workflows, CI/CD release gates, and approval processes across organizational or system swimlanes:

Standard Flowchart Node Classes

• Start / End: Rounded stadium/pill terminals (shape_r=5.0).
• Process: Rectangular execution step (24 x 12).
• Decision: Diamond conditional gate (22 x 14) with explicit start_side="right" | "bottom" | "left" branch routing.
• Data: Slanted parallelogram for I/O artifacts or payloads (24 x 12).

Unified Swimlane Coordinate System

• Call flow.add_lane(name, width=...) for vertical columns or set lane_orientation="horizontal" for horizontal rows.
• Global Coordinate Plane: All nodes share the exact same global (x, y) canvas space—so placing steps across different lanes at the same y coordinate guarantees horizontal alignment!