Diagram-as-Code With Manual Control: Beyond Auto-Layout and GUI Tools

A fresh project called Reladraw just hit Hacker News, and it’s solving a problem every technical professional has felt: you want the efficiency of code-based diagrams like Mermaid or Graphviz, but you’re tired of fighting their auto-layout algorithms. At the same time, GUI tools like Draw.io give you pixel-perfect control but eat up enormous amounts of time. Reladraw introduces a third path—a diagram language that lets you write in code yet explicitly control where every element lands. This isn’t just another tool announcement; it’s a lens into how modern infrastructure teams are rethinking visual documentation workflows.

Let’s use this moment to explore the practical skill of building maintainable, version-controlled diagrams that don’t sacrifice precision. Whether you’re documenting cloud architectures, network topologies, or data flows, understanding when to use declarative syntax versus imperative positioning can transform how your team collaborates.

Table of Contents

• The Layout Control Spectrum
• Why Manual Positioning Matters for IT Documentation
• Reladraw Syntax Walkthrough
• Practical Use Cases for Infrastructure Teams
• Integrating Diagram-as-Code Into Your Workflow

The Layout Control Spectrum

Most diagram tools land on a spectrum. On one end, you have pure auto-layout engines. Graphviz and Mermaid parse your relationships and decide everything—node placement, edge routing, spacing. They’re fast for simple flowcharts but become unpredictable when you need to mirror an actual network rack layout or keep a specific service cluster visually grouped. You end up tweaking node order in code, hoping the engine interprets your intent, which is frustrating when your diagram needs to communicate precise physical or logical arrangements.

On the other end sits GUI software. Draw.io, Lucidchart, Visio—these give you absolute control. Drag a load balancer icon five pixels left, nudge an arrow, align three boxes. But that control comes at a cost: diagrams become binary blobs or proprietary formats. Diffing changes in version control is nearly impossible. Collaboration requires shared accounts or export rituals. And if you’re building automation or CI pipelines that generate or validate architecture diagrams, GUI tools are essentially off the table.

Reladraw occupies the middle ground. You write declarative syntax for shapes and connections, but you also specify coordinates. Think of it as SVG with a higher-level abstraction tailored for technical diagrams. This matters because modern infrastructure is code-first, and diagrams are documentation—they should live in the same Git repositories, go through the same review processes, and update alongside your Terraform or Kubernetes manifests.

Why Manual Positioning Matters for IT Documentation

When you’re diagramming a Kubernetes cluster, the physical positioning carries semantic weight. Placing all control plane components at the top, worker nodes in the middle, and external ingress at the bottom mirrors mental models your team already uses. Auto-layout might scatter those elements based on graph theory, not operational reality.

Consider network topology diagrams. A three-tier architecture—web, app, database—is understood top-to-bottom by convention. If an auto-layout engine decides to arrange those tiers horizontally or zigzag them based on edge weights, your diagram becomes harder to parse. Manual positioning preserves industry conventions and team-specific layout standards. This is why senior architects often sketch on whiteboards first: the spatial reasoning matters.

Another angle: agent and LLM manipulation. As the Reladraw author noted, GUI tools are inefficient for programmatic manipulation. If you’re generating compliance diagrams from inventory APIs or auto-updating architecture visuals from service mesh telemetry, you need a format that’s both human-readable and machine-writable. Plain text with explicit coordinates hits that sweet spot. Platforms like Coursera are starting to include courses on infrastructure-as-code documentation practices, recognizing that diagrams are first-class artifacts in DevOps pipelines.

Reladraw Syntax Walkthrough

Let’s look at a minimal Reladraw example—a classic three-tier web architecture. The syntax is approachable: you define nodes with types, labels, and x/y coordinates, then edges with explicit routing if needed.

// Three-tier web application architecture
node loadBalancer at (50, 20) {
  type: cloud
  label: "AWS ALB"
}

node webServer1 at (20, 60) {
  type: rectangle
  label: "Web Server 1"
}

node webServer2 at (80, 60) {
  type: rectangle
  label: "Web Server 2"
}

node database at (50, 100) {
  type: cylinder
  label: "PostgreSQL"
}

edge loadBalancer -> webServer1
edge loadBalancer -> webServer2
edge webServer1 -> database
edge webServer2 -> database

Notice how the y-coordinate increases downward (20, 60, 100), creating a clear top-to-bottom flow. The x-coordinates spread the web servers horizontally while centering the load balancer and database. This is intentional design, not algorithmic accident. If you need to add a caching layer, you insert a new node at y=80, and the visual hierarchy remains intact.

Compare this to a Mermaid equivalent, where you’d write relationships and hope the layout engine understands your intent. Reladraw’s explicitness is its strength. For IT professionals managing complex environments, that predictability is worth the extra coordinate specifications. If you’re still building skills in infrastructure visualization, DataCamp offers modules on data architecture diagramming that pair well with these diagram-as-code approaches.

Adding Detail and Styling

Real diagrams need more than boxes and lines. Reladraw supports styles, colors, and annotations. Here’s a more production-ready snippet showing a Kubernetes ingress flow with security zones:

// Kubernetes ingress with security zones
node internet at (50, 10) {
  type: cloud
  label: "Internet"
  color: "#e0e0e0"
}

node ingressController at (50, 40) {
  type: rectangle
  label: "Ingress Controller"
  color: "#4CAF50"
  style: "bold"
}

node serviceMesh at (50, 70) {
  type: hexagon
  label: "Service Mesh"
  color: "#2196F3"
}

node apiPods at (50, 100) {
  type: rectangle
  label: "API Pods (x3)"
  color: "#FF9800"
}

// Define security boundary
zone dmz from (40, 30) to (60, 50) {
  label: "DMZ"
  color: "#FFEB3B"
  opacity: 0.2
}

edge internet -> ingressController { label: "HTTPS" }
edge ingressController -> serviceMesh { label: "mTLS" }
edge serviceMesh -> apiPods { style: "dashed" }

The zone annotation creates a visual security boundary without cluttering the node definitions. This separation of concerns—structure versus decoration—makes diagrams easier to maintain. When your security team asks to highlight all DMZ components, you adjust zone definitions, not individual nodes.

Practical Use Cases for Infrastructure Teams

Where does this approach shine? Anywhere you need version-controlled, diff-able diagrams that also respect specific layouts.

Network Topology Documentation

Network engineers need diagrams that map to physical reality. A spine-leaf data center architecture has a specific visual structure—spines at the top, leaves below, connections radiating outward. Auto-layout algorithms optimize for graph aesthetics, not network conventions. Reladraw lets you encode that structure directly, making diagrams that operations teams can trust as references during outages.

CI/CD Pipeline Visualization

Your Jenkins or GitHub Actions pipeline has stages: build, test, deploy, verify. Representing this as a left-to-right flow with manual positioning ensures the diagram matches your mental model. When you add a new security scan stage, you insert it at the correct x-coordinate between test and deploy. The diff is obvious in code review—both the syntax change and the visual shift are clear.

Cloud Architecture Reviews

Architecture decision records (ADRs) benefit from embedded diagrams. Storing those diagrams as Reladraw code means future you—or future teammates—can see exactly what changed between decision points. “We moved the NAT gateway from the public subnet to a dedicated transit subnet” becomes a one-line coordinate change plus a commit message, not a screenshot replacement.

Integrating Diagram-as-Code Into Your Workflow

Adoption requires tooling. Reladraw is a new project, so the ecosystem is forming. The key workflow pieces you need: a command-line renderer that converts .rela files to SVG or PNG, Git integration for version control, and ideally a lightweight preview tool for quick iteration.

Start by converting one critical diagram—your production architecture or main service flow. Store the .rela file alongside your infrastructure code. Set up a CI job that regenerates the diagram on every commit and uploads it as a build artifact. This creates a living document: the diagram is always current because it’s generated from the same source of truth as your deployments.

For teams already using docs-as-code approaches with Markdown and static site generators, Reladraw diagrams slot in naturally. Your documentation repository contains text, code snippets, and diagram source files. The build pipeline renders everything into a searchable knowledge base. When a developer updates a service, they update the diagram in the same pull request—reviewers see both code and visual changes together.

Another integration point: GitOps workflows. If you’re using ArgoCD or Flux, your Git repository defines desired state. Adding diagrams to that repository—diagrams that show the desired architecture—creates a powerful alignment. The code, the config, and the diagram all live together, versioned identically.

The real test of any diagram approach is whether it survives the chaos of real projects. GUI tools look polished initially but degrade as teams grow—who has the latest version? Diagram-as-code with manual control handles that chaos. It’s text, it’s versioned, it’s diffable, and you decide the layout. Reladraw represents a maturation of this idea, acknowledging that full auto-layout isn’t always the answer. Sometimes you need to draw the damn box exactly where you know it belongs.

If you’re serious about infrastructure documentation, experiment with this middle path. Pick a diagram that frustrates you—one where Mermaid keeps rearranging nodes or where you’re tired of opening Draw.io. Rewrite it with explicit coordinates. Commit it. See how the code review process changes when your architecture is diffable text. That’s the unlock: treating visual documentation with the same rigor you apply to your infrastructure code, without sacrificing the clarity that intentional layout provides.