Quickstart

This guide gets you from zero to a running animated architecture diagram in under five minutes.

Prerequisites

Node.js 18 or later
pnpm 8 or later
A modern browser (Chrome, Firefox, Safari, Edge)

Running the app

Clone the repository

git clone https://github.com/lamp-labs/cloud-arch.git
cd cloud-arch

Install dependencies

pnpm install

Start the development server

pnpm dev

This starts both the web app (apps/web) on port 3000 and the API (apps/api) on port 8080.

Open the app

Navigate to http://localhost:3000 in your browser.

You will see the main canvas with the editor sidebar on the left.

Running your first example

Open the examples panel

Click the Examples icon in the left sidebar (the grid icon). A list of categorized example scripts appears.

Choose an example

Select Circuit Breaker from the Design Patterns category. The script loads into the editor.

Execute the script

Click the Run button (triangle icon) at the top of the editor. The canvas populates with nodes, groups, and animated edges.

Play the animation

The AnimationPlayer toolbar appears at the bottom of the canvas. Click Play to watch the circuit breaker scenario unfold step by step.

Switch scenarios

Use the scenario dropdown in the AnimationPlayer to switch between the “Normal Request”, “Circuit Open”, and “Fallback” scenarios.

Adjust playback speed

Click the speed button (default 1x) to cycle through 0.5x, 1x, 2x, and 4x speeds.

Opening a shared diagram

cloud-arch supports shareable URLs. Navigate to any /s/[slug] URL to load a pre-saved script:

https://web.cloud-arch.ru/s/data-platform
https://web.cloud-arch.ru/s/kafka-internals

The script loads automatically and the topology renders without any setup.

On a fresh page load, the app falls back to a built-in example if the requested slug is not found in the database. This means shared links work even on a local dev instance, though the diagram may differ from the original.

Writing your own script

Open a new tab in the editor (the + button), paste any script, and click Run. The canvas updates immediately.

See Your First Script for a full walkthrough of building a topology from scratch.

Keyboard shortcuts

Action	Shortcut
Run script	`Ctrl+Enter` / `Cmd+Enter`
Zoom to fit	`Ctrl+Shift+F` / `Cmd+Shift+F`
Play / Pause animation	`Space` (when AnimationPlayer is focused)
Next step	`Right arrow`

What next

Your First Script — build a real diagram step by step
Core Concepts — understand the mental model before diving into the API
TopologyBuilder reference — full API for topology creation

Introduction Your First Script