Building Beautiful Technical Diagrams with Spayscript

Technical diagrams are the backbone of system documentation. Whether you are designing microservices, mapping data flows, or visualizing network topologies, a good diagram communicates in seconds what paragraphs of text cannot. But creating diagrams that are both beautiful and maintainable has traditionally been a painstaking process.

Enter Spayscript — a declarative DSL that lets you define diagrams in plain text and renders them instantly. This guide walks through everything from basic syntax to advanced styling techniques.

Getting Started with Spayscript

Spayscript uses a clean, YAML-inspired syntax to define nodes, edges, and containers. A basic diagram looks like this:

// hello.spy — Your first diagram
title: "Hello, World!"
theme: dark

box "Service A" {
  -> "Service B" [label: "HTTP /api/v1/users"]
  -> "Database" [label: "PostgreSQL"]
}

box "Service B" {
  -> "Cache" [label: "Redis"]
}

Core Concepts

Nodes

Nodes are the fundamental building blocks of any diagram. Each node represents a component, service, or entity. You can define nodes inline or reference them by name:

# Inline node definition
box "API Gateway" [color: indigo]
  -> "Auth Service"

# Referenced node
node "database" [shape: cylinder, color: slate]
box "Primary Database" [ref: database]

Edges & Connections

Edges define relationships between nodes. Spayscript supports directed, bidirectional, and dashed edges with custom labels and styles:

// Edge types
"Service" -> "Database"        // Directed edge
"Service" <-> "Cache"          // Bidirectional
"Legacy" -/> "New Service"     // Migration (dashed)

// With labels
"Client" -> "API" [label: "HTTPS", color: emerald]

Containers: Box, Stack, and Grid

Containers help you organize nodes into logical groups. Three container types give you full control over layout:

1. Box — A bordered rectangle that groups related nodes. Ideal for bounded contexts or deployment environments.
2. Stack — Arranges children vertically or horizontally. Perfect for layered architectures like OSI models.
3. Grid — Positions children in a uniform grid. Great for service meshes and microservice topologies.

// Container examples
box "Production (us-east-1)" [color: slate] {
  "Web Server" -> "App Server"
  "App Server" -> "Database"
}

stack "Network Layers" [direction: vertical] {
  "Application"
  "Transport"
  "Internet"
  "Link"
}

grid "Service Mesh" [columns: 3] {
  "Auth" "Payments" "Orders"
  "Notifications" "Search" "Analytics"
}

Styling Your Diagrams

Spayscript ships with a comprehensive theming system. You can customize colors, fonts, borders, and shadows at the diagram, container, or node level:

/* Custom theme */
theme: {
  colors: {
    primary: "#6366f1",
    surface: "#0c0c0e",
    text: "#ffffff"
  },
  fonts: {
    heading: "Geist Sans",
    body: "Geist Sans",
    mono: "Space Grotesk"
  },
  borders: {
    radius: "12px",
    width: "1.5px"
  }
}

The best diagrams are the ones you do not have to redraw. Spayscript designs are declarative — change the source, and the visual updates automatically.

Built-in Color Palette

Spayscript includes a carefully curated palette inspired by modern design systems:

• Indigo #6366f1 — Primary accent, great for main services
• Emerald #22c55e — Success states, healthy services
• Amber #f59e0b — Warnings, rate limits, partial outages
• Rose #ef4444 — Errors, downtime, security issues
• Slate #64748b — Neutral infrastructure, third-party services

Advanced Patterns

For production systems, Spayscript supports advanced patterns like template inheritance, @include directives for multi-file projects, and variables for dynamic content:

{
  "version": "2.0",
  "include": ["base.spy", "monitoring.spy"],
  "variables": {
    "region": "us-west-2",
    "environment": "production"
  }
}

For a complete reference of all available directives and their options, check out the Spayscript documentation.

Real-World Example: Microservice Architecture

Here is a complete example of a production microservice architecture diagram:

title: "E-Commerce Platform Architecture"
theme: dark

box "Client Layer" [color: slate] {
  "Web App" [icon: globe]
  "Mobile App" [icon: smart-phone]
}

box "API Gateway" [color: indigo] {
  "Web App" -> "API Gateway" [label: "HTTPS"]
  "Mobile App" -> "API Gateway" [label: "HTTPS"]
  "API Gateway" -> "Auth Service" [label: "JWT Verify"]
}

box "Core Services" [color: indigo] {
  "User Service" [color: emerald]
  "Product Service"
  "Order Service"
  "Payment Service" [color: amber]
}

box "Data Layer" [color: slate] {
  "PostgreSQL" [shape: cylinder]
  "Redis" [shape: cylinder, color: emerald]
  "Elasticsearch" [shape: cylinder]
}

// Connections
"API Gateway" -> "User Service"
"API Gateway" -> "Product Service"
"API Gateway" -> "Order Service"
"Order Service" -> "Payment Service"
"User Service" -> "PostgreSQL"
"Product Service" -> "Elasticsearch"
"Order Service" -> "Redis"

// Monitoring
box "Observability" [color: emerald] {
  "Prometheus" -> "Grafana"
  "Loki" -> "Grafana"
}

"Core Services" -> "Prometheus" [style: dashed]
"Core Services" -> "Loki" [style: dashed]

This diagram renders as a complete, publication-ready visualization. Each service is color-coded by layer, connections show data flow direction, and the monitoring integration is shown with dashed edges.

Conclusion

Spayscript transforms how teams create and maintain technical diagrams. By treating diagrams as code, you gain version control, automated generation, and consistent styling — all while producing visuals that look hand-crafted.

Ready to try it? Head over to the docs to get started, or jump straight into the /docs/examples gallery for inspiration.

Old approach: Draw diagrams in Excalidraw, export PNG, lose source.

Related Reading

If you found this guide helpful, you might also enjoy:

• Designing Resilient Systems with Circuit Breakers
• Monitoring Microservices: A Practical Guide to Observability
• From Monolith to Microservices: A Migration Playbook