Diagram SDK
Shapes
Deep-dive guide into every geometric node shape, semantic color palettes, fill styles, custom dimensions, and status badges.
In @filekit-studio/diagram, shapes represent services, databases, gateways, and architectural boundaries in your system. Each shape conveys semantic meaning and automatically adjusts its dimensions, text wrapping, and connection ports.
1. Microservices & Web Servers (rounded & rectangle)
The rounded and rectangle shapes represent compute workloads, microservice containers, web servers, API endpoints, and client apps.
Key Characteristics:
rounded: Modern containers with smooth12pxrounded corners. Best for microservice pods, serverless functions, and frontend applications.rectangle: Crisp rectangular cards with sharp90°corners. Best for monolith services, controllers, or legacy systems.- Supports
badgetags (e.g."REST","v2","K8S") anchored to the top-right.
import type { DiagramData } from "@filekit-studio/diagram";
export const servicesDiagram: DiagramData = {
title: "Compute & Microservice Tier",
direction: "LR",
nodes: [
{
id: "web_client",
label: "Next.js 16 Web App\n(SSR + Static)",
shape: "rounded",
color: "indigo",
badge: "FRONTEND",
description: "Port 3000"
},
{
id: "api_gateway",
label: "Fastify API Gateway\n(Node.js 22)",
shape: "rounded",
color: "purple",
badge: "GATEWAY",
description: "JWT Validation & Rate Limiting"
},
{
id: "billing_service",
label: "Billing Monolith\n(Go Gin Engine)",
shape: "rectangle",
color: "emerald",
badge: "CORE",
description: "Stripe Webhooks & Invoicing"
}
],
edges: [
{ from: "web_client", to: "api_gateway", label: "HTTPS /api" },
{ from: "api_gateway", to: "billing_service", label: "gRPC Channel" }
],
layout: { direction: "LR", edgeRouting: "elbow", rankSpacing: 220 }
};Loading diagram canvas...
2. Security & Decision Gateways (diamond)
The diamond shape is the industry standard for decision checkpoints, condition branches, Web Application Firewalls (WAF), load balancer balancers, and authentication guards.
Key Characteristics:
- Features 4 angled vertices with diagonal borders.
- Ingress and egress routes can branch off either side (
Authorizedvs.Denied). - Automatically calculates angled surface normals for arrow attachments.
export const securityDiagram: DiagramData = {
title: "Traffic Ingress & Inspection Gateway",
direction: "LR",
nodes: [
{
id: "public_traffic",
label: "Public Web Traffic",
shape: "rounded",
color: "neutral"
},
{
id: "waf_guard",
label: "Cloudflare WAF\n(DDoS & Bot Shield)",
shape: "diamond",
color: "amber",
badge: "SECURITY"
},
{
id: "private_cluster",
label: "Internal VPC Cluster",
shape: "rounded",
color: "emerald",
badge: "AUTHORIZED"
},
{
id: "quarantine",
label: "Honeypot / Drop\n(403 Forbidden)",
shape: "rounded",
color: "rose",
badge: "DROPPED"
}
],
edges: [
{ from: "public_traffic", to: "waf_guard", label: "Inbound Packets" },
{ from: "waf_guard", to: "private_cluster", label: "Clean Request", color: "#10b981" },
{ from: "waf_guard", to: "quarantine", label: "Malicious Attack", color: "#ef4444", style: "dashed" }
],
layout: { direction: "LR", edgeRouting: "elbow", rankSpacing: 220, nodeSpacing: 80 }
};Loading diagram canvas...
3. Database & Storage Engines (cylinder & database)
The cylinder (or database) shape renders a 3D isometric storage drum with curved elliptical top and bottom caps. It represents persistent storage engines, SQL databases, Redis caches, data lakes, and blob stores.
Key Characteristics:
- Curved top rim ellipse with straight vertical cylindrical sides.
- Automatically balances multi-line labels inside the lower drum body.
- Best for PostgreSQL, MySQL, Redis, AWS DynamoDB, ClickHouse, and S3 Object Stores.
export const storageDiagram: DiagramData = {
title: "Multi-Model Persistence Architecture",
direction: "LR",
nodes: [
{
id: "api_layer",
label: "API Data Layer",
shape: "rounded",
color: "indigo"
},
{
id: "postgres",
label: "Aurora PostgreSQL\n(Primary ACID Store)",
shape: "cylinder",
color: "emerald",
badge: "RELATIONAL"
},
{
id: "redis",
label: "Redis Sentinel Cluster\n(Sessions & Rate Limits)",
shape: "cylinder",
color: "rose",
badge: "IN-MEMORY"
},
{
id: "clickhouse",
label: "ClickHouse Lakehouse\n(OLAP Columnar Store)",
shape: "cylinder",
color: "amber",
badge: "ANALYTICS"
}
],
edges: [
{ from: "api_layer", to: "postgres", label: "Write Transactions", color: "#10b981" },
{ from: "api_layer", to: "redis", label: "Read / Write Cache", color: "#f43f5e" },
{ from: "api_layer", to: "clickhouse", label: "Async Ingest", color: "#f59e0b", style: "dashed" }
],
layout: { direction: "LR", edgeRouting: "elbow", rankSpacing: 240, nodeSpacing: 60 }
};Loading diagram canvas...
4. Public Internet, CDN & Third-Party APIs (cloud)
The cloud shape draws a multi-lobed cloud contour representing untrusted external networks, third-party SaaS APIs (Stripe, GitHub, OpenAI), and Content Delivery Networks (CDNs).
Key Characteristics:
- Organic cloud lobes around the perimeter.
- Anchor ports radiate perpendicular to each lobe curvature.
- Instantly distinguishes internal VPC services from external SaaS providers.
export const cloudDiagram: DiagramData = {
title: "Third-Party SaaS & Public Cloud APIs",
direction: "LR",
nodes: [
{
id: "orchestrator",
label: "Task Orchestrator",
shape: "rounded",
color: "purple"
},
{
id: "stripe_api",
label: "Stripe Billing Engine\n(Payments & Webhooks)",
shape: "cloud",
color: "sky",
badge: "PAYMENTS"
},
{
id: "openai_api",
label: "OpenAI Platform\n(GPT-4o Embeddings)",
shape: "cloud",
color: "emerald",
badge: "LLM"
}
],
edges: [
{ from: "orchestrator", to: "stripe_api", label: "Charge Customer", color: "#0ea5e9" },
{ from: "orchestrator", to: "openai_api", label: "Streaming Inference", color: "#10b981" }
],
layout: { direction: "LR", edgeRouting: "elbow", rankSpacing: 240, nodeSpacing: 80 }
};Loading diagram canvas...
5. State Machine Events & Lifecycle Triggers (ellipse & circle)
The ellipse (or circle) shape renders smooth curved oval contours. They represent event topics, Kafka partitions, start/finish lifecycle states, and user actors.
export const stateDiagram: DiagramData = {
title: "Event-Driven State Machine",
direction: "LR",
nodes: [
{
id: "order_placed",
label: "Event: Order Placed\n(Kafka Topic)",
shape: "ellipse",
color: "sky"
},
{
id: "inventory_worker",
label: "Inventory Service",
shape: "rounded",
color: "indigo"
},
{
id: "order_fulfilled",
label: "State: Fulfilled",
shape: "ellipse",
color: "emerald"
}
],
edges: [
{ from: "order_placed", to: "inventory_worker", label: "Consume Message" },
{ from: "inventory_worker", to: "order_fulfilled", label: "Dispatch Package", color: "#10b981" }
],
layout: { direction: "LR", edgeRouting: "elbow", rankSpacing: 220 }
};Loading diagram canvas...
6. Architecture Notes & Callouts (sticky)
The sticky shape renders a post-it note card with a folded corner in the bottom-right. It is ideal for callouts, operational SLAs, security compliance disclosures, and architect comments.
export const notesDiagram: DiagramData = {
title: "Architecture With Compliance Callout",
direction: "LR",
nodes: [
{
id: "vault_svc",
label: "HashiCorp Vault\n(Secret Management)",
shape: "rounded",
color: "purple",
badge: "SECURITY"
},
{
id: "sec_note",
label: "Architecture Note:\n• SOC2 Type II Certified\n• AES-256 Key Rotation\n• Zero-Trust Network",
shape: "sticky",
color: "amber"
}
],
edges: [
{ from: "vault_svc", to: "sec_note", label: "Audit Log", style: "dotted", color: "#d97706" }
],
layout: { direction: "LR", edgeRouting: "elbow", rankSpacing: 240 }
};Loading diagram canvas...
7. Shape Fill Styles (fillStyle)
Control the interior canvas rendering texture of any shape via fillStyle:
| Value | Appearance | Best Used For |
|---|---|---|
"hachure" (default) | Hand-drawn diagonal sketchy hatching | Default human-crafted whiteboard aesthetic |
"solid" | Opaque background fill | Polished enterprise cards, high contrast |
"cross-hatch" | Double crisscrossed grid lines | Highlighting mission-critical services |
"dots" | Stipple dotted interior pattern | Background services, telemetry daemons |
"none" | Transparent fill with only outer boundary | Lightweight framing boxes |
8. Semantic Color Palettes (color)
@filekit-studio/diagram provides 8 semantic color palettes that automatically adapt to light and dark modes:
{
"color": "indigo" | "purple" | "emerald" | "amber" | "rose" | "sky" | "neutral" | "#HEX_COLOR"
}indigo: Frontend apps, web clients, public interfaces.purple: Core business services, API controllers, orchestrators.emerald: Relational databases, ACID transactions, authorized paths.amber: WAFs, gateways, telemetry warnings, architecture notes.rose: Cache layers, dropped packets, honeypots, rate-limiters.sky: External cloud APIs, DNS providers, CDNs.neutral: Standard backend workers, generic queue consumers.- Custom Hex Color: Pass any CSS color string (
"#6366f1","rgba(99, 102, 241, 0.9)").