Quickstart

This guide gets you from a fresh clone to a running animated architecture diagram.

Prerequisites

Node.js 20 or later
pnpm 9.15 or later — the repo pins packageManager: pnpm@9.15.0
Bun 1.1 or later — apps/api runs on the Bun runtime, not Node
A reachable PostgreSQL 15+ instance — the API refuses to start without one
A modern browser (Chrome, Firefox, Safari, Edge)

⚠️

pnpm dev starts the web app and the API. The API validates its environment at boot, so skipping the env step below makes it exit immediately with a Zod error.

Running the app

Clone the repository

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

Install dependencies

pnpm install

Configure the environment

cp .env.example .env

At minimum fill in:

Variable	Purpose
`DATABASE_URL`	PostgreSQL connection string, e.g. `postgres://postgres:postgres@localhost:5432/cloud_arch`
`BETTER_AUTH_SECRET`	Auth signing secret. Generate one: `openssl rand -hex 32`
`BETTER_AUTH_BASE_URL`	Usually `http://localhost:4000`
`NEXT_PUBLIC_API_BASE_URL`	Where the web app calls the API, usually `http://localhost:4000`

Everything else in .env.example is optional locally. NEXT_PUBLIC_YANDEX_METRIKA_ID holds the Yandex.Metrika counter id — leave it empty in development and the counter is never loaded.

Drizzle migrations are applied automatically on API startup — no separate migrate step.

Start the development server

pnpm dev

This starts the web app (apps/web) on port 3000 and the API (apps/api) on port 4000 (API_PORT). Run them separately with pnpm dev:web / pnpm dev:api.

Open the app

Navigate to http://localhost:3000.

Running your first example

Scripts live in the database, not in the repo — there is no bundled example registry. A fresh local database therefore starts empty except for the canonical seed migrations.

Browse the gallery

Open http://localhost:3000/explore. Public scripts are grouped by topic; each card links to its viewer page at /v/<slug>.

Open a diagram

Click any card. The topology renders on the canvas and the AnimationPlayer toolbar appears at the bottom when the script defines scenarios.

Play the animation

Press Play. Packets travel along the edges and each step prints its showMessage / showError text under the canvas.

Switch scenarios

When a script calls .scenario(...) more than once, scenario pills appear in the player bar. Click one to replay that branch.

Read the source

Use View source on the viewer page to see the script that produced the diagram, or open it in the editor to modify it.

Opening a shared diagram

Any public script is reachable at /v/<slug>:

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

Slugs resolve against the database only. An unknown slug returns 404 — there is no built-in fallback example, so a local instance shows a shared link only if that script exists in your database.

Writing your own script

Open http://localhost:3000/editor. The left rail switches panes: Components, DSL (the script itself), Readme, Scenarios, Inspector, AI Assist, Concepts, Validate, History. Write into the DSL pane and run.

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

Keyboard shortcuts

Action	Shortcut
Run script	`Ctrl+Enter` / `Cmd+Enter`
Save script	`Ctrl+S` / `Cmd+S`
Quick search	`Ctrl+K` / `Cmd+K`

What next

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

Introduction Your First Script