Step-by-Step Architecture Guide
Build a production cloud system architecture from scratch using shapes, arrow types, interactive badges, and network groups.
This tutorial walks you through constructing a modern, production-grade cloud system architecture from scratch using @filekit-studio/diagram.
By following along, you will learn how to:
- Declare geometric shapes (
rounded,diamond,cylinder). - Connect services with all 3 arrow styles (
straight,curved,elbow). - Attach interactive badges to arrows that automatically mask the lines underneath.
- Enclose backend services inside a Private Cloud VPC network using groups.
What We Are Building
Here is the final production edge architecture you will have created by the end of this guide. You can pan, zoom, and inspect it live:
Step 1: Declaring the First Service Box
Every diagram begins with defining nodes. A node is a service, database, or gateway represented by a geometric shape.
Let us define the primary backend API service:
id: Unique identifier used for wiring arrows ("app").label: The title and description ("Core API Service\n(Node.js)").shape:"rounded"for modern microservice boxes.color: Color accent ("purple").badge: An eyebrow tag anchored to the top-right ("CORE").
import type { DiagramData } from "@filekit-studio/diagram";
export const step1Data: DiagramData = {
title: "Step 1: Single Microservice",
direction: "LR",
nodes: [
{
id: "app",
label: "Core API Service\n(Node.js)",
shape: "rounded",
color: "purple",
badge: "CORE"
}
]
};Live Output (Step 1)
Step 2: Connecting Client to API with a Straight Arrow
Now, let us introduce the client application and connect it to our Core API service using a Straight Arrow.
When you declare an edge with a label, the SDK automatically attaches an interactive badge pill to the arrow. The pill has an opaque background mask, so the arrow line underneath never cuts through the text.
export const step2Data: DiagramData = {
title: "Step 2: Client to API",
direction: "LR",
nodes: [
{
id: "web",
label: "Web Client\n(Next.js 16)",
shape: "rounded",
color: "indigo",
badge: "FRONTEND"
},
{
id: "app",
label: "Core API Service\n(Node.js)",
shape: "rounded",
color: "purple",
badge: "CORE"
}
],
edges: [
{
from: "web",
to: "app",
label: "HTTPS / REST",
color: "#6366f1"
}
]
};Live Output (Step 2)
Notice how the "HTTPS / REST" badge is centered cleanly on the arrow with high contrast:
Step 3: Adding a Database (cylinder Shape) & Curved Arrow
Next, our API service needs to persist data. We will add a relational PostgreSQL database using the cylinder shape.
To illustrate an asynchronous or branched flow, we will route this connection with a Curved Arrow (routing: "curved"):
export const step3Data: DiagramData = {
title: "Step 3: Database & Curved Flow",
direction: "LR",
nodes: [
{ id: "web", label: "Web Client\n(Next.js 16)", shape: "rounded", color: "indigo", badge: "FRONTEND" },
{ id: "app", label: "Core API Service\n(Node.js)", shape: "rounded", color: "purple", badge: "CORE" },
{
id: "db",
label: "Aurora Database\n(PostgreSQL ACID)",
shape: "cylinder",
color: "emerald",
badge: "DATABASE"
}
],
edges: [
{ from: "web", to: "app", label: "HTTPS / REST", color: "#6366f1" },
{
from: "app",
to: "db",
label: "Write SQL (ACID)",
color: "#10b981",
routing: "curved"
}
]
};Live Output (Step 3)
The curved arrow bends dynamically between the two shapes with a smooth quadratic Bézier curve, and the "Write SQL (ACID)" badge adapts along the curve apex:
Step 4: Adding Edge Security (diamond Shape) & Orthogonal Routing
Production systems rarely expose APIs directly to the open web. We will introduce an edge security shield using the diamond shape.
To ensure clean engineering wiring without diagonal overlaps, we will use Orthogonal / Elbow routing (edgeRouting: "elbow"). Notice how the orthogonal arrow cleanly navigates horizontal and vertical corridors, and the "Clean Ingress" badge stays centered along the mid-corridor:
export const step4Data: DiagramData = {
title: "Step 4: Edge Gateway & Orthogonal Routing",
direction: "LR",
nodes: [
{ id: "web", label: "Web Client\n(Next.js 16)", shape: "rounded", color: "indigo", badge: "FRONTEND" },
{
id: "gw",
label: "Cloudflare Edge\n(DDoS & Bot Shield)",
shape: "diamond",
color: "amber",
badge: "EDGE"
},
{ id: "app", label: "Core API Service\n(Node.js)", shape: "rounded", color: "purple", badge: "CORE" },
{ id: "db", label: "Aurora Database\n(PostgreSQL ACID)", shape: "cylinder", color: "emerald", badge: "DATABASE" }
],
edges: [
{ from: "web", to: "gw", label: "HTTPS POST", color: "#6366f1" },
{ from: "gw", to: "app", label: "Clean Ingress", color: "#f59e0b" },
{ from: "app", to: "db", label: "Read / Write", color: "#10b981" }
],
layout: { direction: "LR", edgeRouting: "elbow", nodeSpacing: 80, rankSpacing: 200 }
};Live Output (Step 4)
Step 5: Full Production Architecture (Caching & Private VPC Subnet)
Finally, let us finalize our system design:
- Add a Redis Cluster (
"kv"): A fast session and caching store to prevent database bottlenecks. - Private VPC Enclosure (
groups): Wrap internal microservices (app,db, andkv) into a protected VPC boundary corridor withgroupPadding: 48.
export const fullArchitecture: DiagramData = {
title: "Production Edge Pipeline (Complete)",
direction: "LR",
nodes: [
{ id: "web", label: "Web Client\n(Next.js 16)", shape: "rounded", color: "indigo", badge: "FRONTEND" },
{ id: "gw", label: "Cloudflare Edge\n(DDoS & Bot Shield)", shape: "diamond", color: "amber", badge: "EDGE" },
{ id: "app", label: "Core API Service\n(Node.js)", shape: "rounded", color: "purple", badge: "CORE" },
{ id: "db", label: "Aurora Database\n(PostgreSQL ACID)", shape: "cylinder", color: "emerald", badge: "DATABASE" },
{ id: "kv", label: "Redis Cluster\n(Session Store)", shape: "cylinder", color: "rose", badge: "CACHE" }
],
edges: [
{ from: "web", to: "gw", label: "HTTPS POST", color: "#6366f1" },
{ from: "gw", to: "app", label: "Clean Ingress", color: "#f59e0b" },
{ from: "app", to: "db", label: "Read / Write", color: "#10b981" },
{ from: "app", to: "kv", label: "Cache Lookup", color: "#ec4899" }
],
groups: [
{
id: "backend",
label: "Private VPC Network (us-east-1)",
nodeIds: ["app", "db", "kv"],
color: "purple"
}
],
layout: {
direction: "LR",
edgeRouting: "elbow",
nodeSpacing: 80,
rankSpacing: 220,
clusterSpacing: 200,
groupPadding: 48
}
};Live Interactive Output (Complete)
Architecture Cheat Sheet
| Feature | Property | Supported Values | Common Use Case |
|---|---|---|---|
| Microservice | shape: "rounded" | "rounded", "rectangle" | APIs, web services, microservice workers |
| Decision Gateway | shape: "diamond" | "diamond" | WAF, auth guards, load balancers, rate limiters |
| Databases & Cache | shape: "cylinder" | "cylinder", "database" | SQL databases, Redis clusters, document stores |
| Straight Arrow | routing: "straight" | "straight" | Direct client-to-gateway ingress |
| Curved Arrow | routing: "curved" | "curved" | Organic data branching, queues, pub/sub topics |
| Orthogonal Arrow | routing: "elbow" | "elbow", "orthogonal" | Enterprise bus, clean grid corridors |
| Arrow Badge | label: "..." | Any string | Protocol tags (HTTPS), action tags (Read/Write) |
| Subnet Group | groups: [{ ... }] | Array of { id, label, nodeIds } | VPC networks, Kubernetes pods, DMZ clusters |
Next Steps
- Explore All Supported Shapes for cloud architecture, ellipses, and sticky notes.
- Read Edge Routing & Corridor Physics to master tunneling and collision evasion.
- Learn how to embed the interactive Whiteboard Viewer in your app.