Spacerizr

Interactive 3D/2D C4 architecture visualizer for Structurizr DSL and workspace JSON files.

Features

• 3D visualization — Three.js-powered interactive scene with orbit controls, particle effects, and floating animations
• 2D visualization — Clean, sketch-style canvas view with pan & zoom
• Drill-down navigation — Click elements to explore System > Container > Component levels
• Presentation mode — Fullscreen with auto-generated slides, laser pointer, and auto-hiding toolbar
• SVG & PNG export — High-quality architecture diagrams for documentation
• Dark & light themes — Auto-detects system preference
• Structurizr DSL & JSON — Supports both workspace formats
• URL loading — Load models via ?url= query parameter for easy sharing
• Paste-to-load — Paste DSL content directly onto the welcome screen
• Shareable links — Settings and navigation state serialized in URL hash
• Watch mode — Auto-reloads when files change during development
• Keyboard shortcuts — Navigate with keyboard, present without a mouse

Quick Start

CLI (recommended)

npx spacerizr                              # Scan current directory
npx spacerizr workspace.dsl                # Open a specific file
npx spacerizr docs/                        # Scan a directory

This starts a local viewer at http://localhost:4777 and opens your browser.

Install in a project

npm install spacerizr --save-dev

Add scripts to your package.json:

{
  "scripts": {
    "arch": "spacerizr docs/",
    "arch:export": "spacerizr docs/ --export svg",
    "arch:watch": "spacerizr docs/ --watch"
  }
}

CLI Reference

spacerizr [file-or-dir] [options]

Arguments:
  file-or-dir    Path to a .dsl or .json workspace file, or a directory
                 containing them. Defaults to current directory.

Options:
  --port, -p     Port to serve on (default: 4777)
  --export, -e   Export format: svg (headless export, then exit)
  --output, -o   Output file path for export (default: <filename>.svg)
  --theme, -t    Theme for export: dark or light (default: dark)
  --watch, -w    Watch for file changes and auto-reload browser
  --help, -h     Show this help message

Examples

# Interactive viewer
spacerizr workspace.dsl
spacerizr docs/ --port 3000
spacerizr docs/ --watch

# Headless SVG export (no browser needed)
spacerizr workspace.dsl --export svg
spacerizr workspace.dsl --export svg --output architecture.svg
spacerizr workspace.dsl --export svg --theme light
spacerizr docs/ --export svg                  # Exports all files

Keyboard Shortcuts

| Key | Action | |-----|--------| | P | Enter presentation mode | | Backspace | Go up one level | | F | Zoom to fit | | Esc | Exit presentation mode |

In Presentation Mode

| Key | Action | |-----|--------| | → / Space / PageDown | Next slide | | ← / PageUp | Previous slide | | L | Toggle laser pointer | | Home | First slide | | End | Last slide | | Esc | Exit presentation |

Presentation Mode

Press P or click the Fullscreen button in the controls panel to enter presentation mode.

• Auto-generated slides — walks through the model hierarchy (top-level → systems → containers)
• Auto-hiding toolbar — appears on mouse movement, hides after 3 seconds
• Laser pointer — toggle with L for a red cursor dot during live presentations
• Slide counter — shows current position (e.g. "3 / 12")
• Annotations — each slide shows the element name as a translucent overlay

URL Loading & Sharing

Load from URL

Load a model directly via query parameter — perfect for sharing links or embedding:

https://spacerizr.app/?url=https://example.com/workspace.dsl

Load from base64

For small models, encode as base64:

https://spacerizr.app/?dsl=d29ya3NwYWNlIC...

Shareable settings

Settings and navigation state are serialized in the URL hash:

https://spacerizr.app/?url=...#theme=dark&view=2d&path=system1,container2

| Hash param | Values | Description | |-----------|--------|-------------| | theme | light, dark | Color theme | | view | 2d, 3d | View mode | | path | comma-separated IDs | Navigation path |

Paste to load

On the welcome screen, paste DSL content directly with Ctrl+V / Cmd+V. No file needed.

Programmatic API

Spacerizr exposes a pure JavaScript API for parsing and rendering — no browser required. Perfect for CI/CD pipelines, scripts, and custom tooling.

npm install spacerizr

Parse & render SVG

import { parseDSL, parseJSON, renderSVG } from "spacerizr";
import { readFileSync, writeFileSync } from "fs";

// Parse a DSL file
const dsl = readFileSync("workspace.dsl", "utf-8");
const model = parseDSL(dsl);

// Or parse a JSON workspace
const json = readFileSync("workspace.json", "utf-8");
const model2 = parseJSON(json);

// Render to SVG string (no DOM needed)
const svg = renderSVG(model, { theme: "dark" });
writeFileSync("architecture.svg", svg);

Inspect the model

import { parseDSL, getViewState, hasChildren } from "spacerizr";

const model = parseDSL(dslText);

// Get top-level view
const view = getViewState(model, []);
console.log("Elements:", view.visibleElements.map((e) => e.name));
console.log("Relationships:", view.visibleRelationships.length);

// Drill into a system
const systemId = model.elements.find((e) => e.type === "softwareSystem")?.id;
if (systemId && hasChildren(model, systemId)) {
  const drillDown = getViewState(model, [systemId]);
  console.log("Containers:", drillDown.visibleElements.map((e) => e.name));
}

CI/CD example (GitHub Actions)

name: Export architecture diagrams
on:
  push:
    paths: ["docs/**/*.dsl"]

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npx spacerizr docs/ --export svg --theme light
      - uses: actions/upload-artifact@v4
        with:
          name: architecture-diagrams
          path: "*.svg"

Embed in Your App

Mount an interactive 3D/2D viewer inside any web application — Storybook, Docusaurus, internal portals, or your own React/Vue/Svelte app.

npm install spacerizr three

import { parseDSL } from "spacerizr";
import { createViewer } from "spacerizr/embed";

const model = parseDSL(dslText);

const viewer = createViewer(document.getElementById("arch-container"), model, {
  theme: "dark",       // "light" | "dark"
  viewMode: "3d",      // "3d" | "2d"
  onElementClick: (element, path) => {
    console.log("Clicked:", element.name);
  },
});

Viewer API

// Navigate programmatically
viewer.navigateTo(["system-id", "container-id"]);

// Switch theme or view mode
viewer.setTheme("light");
viewer.setViewMode("2d");

// Load a different model
viewer.loadModel(anotherModel);

// Get current state
const path = viewer.getPath();
const model = viewer.getModel();

// Clean up
viewer.destroy();

Viewer options

| Option | Type | Default | Description | |--------|------|---------|-------------| | theme | "light" \| "dark" | system | Color theme | | viewMode | "3d" \| "2d" | "3d" | Initial view mode | | showRelationshipLabels | boolean | true | Show labels on relationship lines | | floatingEnabled | boolean | true | Enable floating animation (3D) | | particlesEnabled | boolean | true | Enable particle effects (3D) | | onElementClick | function | — | Callback when an element is clicked | | onElementHover | function | — | Callback when an element is hovered |

Standalone Deployment

Build and deploy as a static site where users can drop .dsl or .json files:

npm run build
# Deploy the `dist/` folder to any static host (Vercel, Netlify, etc.)

The standalone viewer shows a welcome screen with:

• Drag-and-drop zone for loading workspace files
• Paste-to-load support (Ctrl+V)
• URL-based loading via ?url= parameter

Types

All types are exported for TypeScript users:

import type {
  C4Model,
  C4Element,
  C4Relationship,
  C4ElementType,   // "person" | "softwareSystem" | "container" | "component"
  ViewState,
  RenderSvgOptions,
} from "spacerizr";

Development

git clone https://github.com/tobiascervin/spacerizr.git
cd spacerizr
npm install
npm run dev          # Start dev server at localhost:5173
npm run build        # Build static app → dist/
npm run build:lib    # Build library API → dist-lib/
npm run build:all    # Build both

License

MIT