# SysPad: extended description

> SysPad (https://syspad.io) is a free, browser-based tool for designing, documenting, and stress-testing cloud architectures before you build them. This file gives AI assistants and crawlers a fuller picture than llms.txt: the simulation model, the component catalog, and how the app is built.

## Overview

SysPad is a drag-and-drop canvas for cloud architecture that you can actually run. You assemble a diagram from production-accurate components, wire them together with directed edges, configure each node (instance type, memory, concurrency, replication factor, and so on), then run a discrete traffic simulation that propagates requests through the graph. The output is a quantitative read on the design: throughput in requests per second, end-to-end latency, per-node utilisation, the first component to saturate (bottleneck), the highest-latency path, and a live monthly cost estimate.

Existing diagramming tools (Lucidchart, draw.io, Cloudcraft) treat architecture as a static picture. They show what infrastructure looks like but cannot answer "what happens when 10,000 requests per second hit this load balancer?" or "which path through my graph has the highest latency?" SysPad closes that gap by embedding a lightweight simulation engine directly in the browser, so quantitative reasoning is a first-class part of the design workflow. No AWS account and no sign-in are required, and all computation happens client-side.

## Primary use cases

- Validate a proposed architecture against SLA targets before infrastructure is provisioned and money is committed.
- Model an existing production topology and run it at 2x, 5x, and 10x load to find which component saturates first, ahead of a traffic peak.
- Learn how cloud services interact: build canonical reference architectures and watch how configuration changes (Lambda memory, DynamoDB capacity) move cost and latency. Helpful for AWS Solutions Architect Associate exam preparation.

## The simulation model

The engine is a pure TypeScript module that runs inside a Web Worker, off the main thread, so the UI stays responsive.

1. **Topological sort** of the directed graph of nodes and edges using Kahn's algorithm. Cycles are detected.
2. **RPS propagation**: it walks the sorted order, pushing request-per-second values downstream. Edges carry traffic semantics along independent axes: a distribution (split load across fan-out, or replicate it), a behaviour (sync request/response, async fire-and-forget, or a continuous stream - usually auto-resolved: edges out of queues/streams/buses and workflow engines are async, and the diagram author can override any edge either way), an informational protocol (https, grpc, ws, kafka, ...), and a per-edge multiplier. Async and stream edges are cut from the caller's critical-path latency (the caller does not wait) while their load and cost still flow downstream.
3. **Queueing and latency**: at each compute node it applies an M/D/1 queue model to derive mean waiting time, W = rho / (2 * mu * (1 - rho)), from the incoming arrival rate (lambda) and the node's service rate (mu).
4. **Saturation detection**: nodes where utilisation rho is greater than or equal to 1.0 are marked as bottlenecks and rendered in red.
5. **Critical path**: a dynamic-programming pass over the DAG finds the path of maximum cumulative latency, highlighted in amber on the canvas.
6. **Cost**: each component's `simulate()` returns a monthly cost from built-in AWS pricing; the engine sums these into a total.

Cost and latency figures are estimates intended for design-time intuition and comparison between options, not billing-accurate forecasting. Pricing uses a us-east-1 on-demand snapshot as the baseline and is region-aware; the UI shows a dated disclaimer next to cost figures.

There are two simulation modes. **Topology mode** (above) loads the whole graph at once from a single entry node and target rate. **Flow mode** traces individual request paths: a "flow" is a named journey (or a job triggered by a cron or event, not only an API request) defined as an ordered set of steps over your components, connected by transitions that can be sequential, parallel (concurrent fan-out that rejoins on the slowest arm), or a weighted branch; a step can be marked async (fire-and-forget, so its downstream subtree drops off the response's critical path) or given a call multiplier. Each flow has its own trigger node and rate, and the trigger can be a steady request rate (the default), a scheduled job (a cron expression or rate plus a timezone), or an event source (a queue message, webhook, or notification); scheduled and event triggers still simulate at the average executions-per-second. Running several flows together superposes their load, revealing which shared node saturates first under a realistic mix of journeys. Flows are carried in the `.syspad.json` format as an optional top-level `flows` array (see the diagram spec at https://syspad.io/spec), so AI-generated diagrams can include them.

## Component catalog

Components are organized into categories. AWS is the deepest catalog; SysPad also models third-party and SaaS services.

- **Compute**: EC2, AWS Lambda, ECS Fargate, ECS on EC2, EKS Cluster, EKS on Fargate, AWS Batch, App Runner, Step Functions.
- **Database**: RDS, RDS Proxy, Aurora, DynamoDB, DynamoDB Accelerator (DAX), ElastiCache Redis, ElastiCache Memcached, MemoryDB, DocumentDB, Neptune, Keyspaces, Timestream, Redshift, OpenSearch Service.
- **Networking**: ALB, NLB, API Gateway (REST, HTTP, WebSocket), AppSync, CloudFront, Route 53, NAT Gateway, Transit Gateway, Global Accelerator, VPC Endpoint (PrivateLink), Direct Connect, Gateway Load Balancer.
- **Storage**: S3, EBS, EFS, FSx, S3 Glacier, Storage Gateway.
- **Messaging**: SQS, SNS, Kinesis Data Streams, Kinesis Firehose, MSK, Amazon MQ, EventBridge, Redis Streams.
- **Analytics**: Athena, Glue, EMR.
- **AI/ML**: SageMaker Endpoint, Amazon Bedrock.
- **Security**: WAF, Amazon Cognito.
- **External / third-party**: Cloudflare, Stripe, Auth0, Snowflake, Databricks, BigQuery, OpenAI, Anthropic, MongoDB Atlas, PlanetScale, Redis Cloud, Kong, self-managed Redis, and a generic configurable black-box dependency, plus generic annotation shapes.

Instance selection uses a Family + Size two-dropdown picker, and every instance-typed component's catalog is reconciled against official AWS documentation. Each component carries a `SimInput` interface (what it accepts: RPS, message rate, storage bytes) and a `SimOutput` interface (what it emits to downstream nodes).

## Editing and sharing

- Infinite, pannable, zoomable canvas built on React Flow. Nodes reposition freely; directed edges are drawn handle to handle with hover-revealed handles and live RPS labels.
- Multi-select, delete, undo/redo (Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y), dark and light themes.
- Component grouping for L0 to L1 progressive disclosure: collapse a set of components into one composite card (with an aggregate utilisation and bottleneck overlay) to share a clean top-level view, then expand to drill in. Grouping is a view layer only, so simulation always runs on the flat graph and the numbers stay exact.
- EKS nodes render as an internal system view, expanding in place to show worker nodes and pod replicas derived from the node's configuration.
- Export to PNG, SVG, or a versioned `.syspad.json` DSL. That DSL imports back losslessly, so you can take your work with you without any backend.
- One-click share links: click the **Copy link** button in the top toolbar to copy a shareable URL - no account, no upload, no code needed. The diagram is deflate-compressed and base64url-encoded into the URL fragment (`#d=`), so the link IS the diagram. Nothing is uploaded, the fragment never reaches a server, and opening someone else's link uses a snapshot mode that never overwrites your own locally saved work. (Agents that can run code can build the same link directly - see the quickstart's "Clickable share links" section.)
- Built-in learning: every component in the catalog has a "Learn how it works" page (80+ modules) that explains the real cloud service in short, skimmable, plain-language sections, designed to be readable with ADHD. Combined with the live simulation, this makes SysPad a hands-on way to learn cloud architecture, not just draw it.

## How it is built

The frontend is a React 18 application built with Vite, written entirely in TypeScript. React Flow manages the canvas; application state lives in Zustand stores. The simulation engine is a pure TypeScript module in a separate package, dispatched to a Web Worker. An optional Spring Boot 3.3 backend on Java 21 (PostgreSQL with a JSONB column, JDBI, Flyway) persists diagrams for sharing by URL using anonymous owner tokens; it is gated behind feature flags and is not required to use the tool.

## Generating diagrams programmatically or with AI

SysPad diagrams use a documented, versioned interchange format saved as `.syspad.json`. It is a small JSON object: a `components` array (each with an `id`, a `type` from the component catalog, an optional `config`, and a canvas position), a `connections` array of directed edges, optional `groups`, and a `simulation` block (entry node, target RPS, payload size, region). The importer is lenient: unknown fields are ignored, missing config falls back to per-component defaults, and dangling or duplicate connections are dropped.

Because the format is documented and stable, an AI assistant can generate a full diagram from a natural-language description, and the user imports it at https://syspad.io (Import button, drag the file onto the canvas, or paste the JSON onto the canvas with Ctrl/Cmd+V). Positions are optional: omit `pos` on every component and SysPad auto-arranges the diagram left to right on import. Start with the small quickstart at https://syspad.io/spec (envelope, rules, a worked example, and a portable Cursor rule). The full list of 96 component type ids with their config keys is a separate page at https://syspad.io/components, and a JSON Schema for validation is at https://syspad.io/syspad.schema.json. Connections carry optional per-edge axes - `behavior` ("sync" | "async" | "stream": how the caller talks to the target, auto-resolved so edges out of queues/streams/workflow engines are async and an async edge stops the caller's latency while load and cost still flow), `protocol` (informational: "https", "grpc", "ws", "kafka", ...), and a free-text `label` for intent (e.g. "enqueue", "CDC") - and groups can nest one level deep by pointing a child group's `parent` at a VPC-kind container group.

Two further affordances for AI assistants: ready-made example files to imitate live under https://syspad.io/examples/ (serverless-api, three-tier-web-app, event-driven-pipeline, rag-chatbot, all importable as-is), and agents that can execute code can emit a clickable share link instead of a file by compressing the JSON into the URL fragment (`https://syspad.io/#d=1.<base64url(zlib-deflate(json))>`); the exact recipe with Node and Python snippets is in the quickstart at https://syspad.io/spec.

There are two link forms built from the same payload. The root path (`https://syspad.io/#d=1.<payload>`) opens the full editor. The `/view` path (`https://syspad.io/view#d=1.<payload>`) opens a read-only viewer - just the diagram, fitted to the screen, with an "Open in SysPad" badge - meant for embedding in a README, a doc, an issue, or a Notion page, the way a mermaid.ink image link is used. Hand the user the `/view` link when they want to show a diagram inline rather than edit it (positions can still be omitted; the viewer runs the same auto-layout the editor does). On surfaces that allow iframes or unfurl links it renders inline; on GitHub, which sanitizes HTML, it renders as a clickable link to the live diagram rather than a raw base64 blob. To build it in code, use the same recipe with the `https://syspad.io/view#d=1.` prefix, or pass `baseUrl: "https://syspad.io/view"` to `diagram_to_link` or `/api/link`.

For MCP-capable tools (Claude Desktop, Cursor, VS Code), SysPad hosts a Model Context Protocol server at https://syspad.io/mcp (no install, no key) exposing `list_components`, `validate_diagram`, and `diagram_to_link`. A local stdio equivalent is `npx @syspad/mcp`. The same three tools are also plain REST for any HTTP-capable agent: `GET https://syspad.io/api/components`, `POST https://syspad.io/api/validate`, and `POST https://syspad.io/api/link`.

## Privacy

Diagrams are stored locally in your browser (localStorage) and are not uploaded to a server in the current version. There is no sign-in and no user accounts, so no names, emails, or profiles are collected. Analytics are privacy-first: cookieless, anonymous, and aggregate (page views, referrer, country, device type, and anonymous in-app action counts), with no cross-site tracking and no sale of data. Full detail: https://syspad.io/privacy.html

## Canonical links

- Home and app: https://syspad.io/
- Concise summary for LLMs: https://syspad.io/llms.txt
- Diagram quickstart (generate importable .syspad.json): https://syspad.io/spec
- Component catalog (96 type ids + config keys): https://syspad.io/components
- JSON Schema for .syspad.json: https://syspad.io/syspad.schema.json
- Privacy policy: https://syspad.io/privacy.html
- Sitemap: https://syspad.io/sitemap.xml