Sphere·SCAN
Go to app →
scan: "0.1" · notation + modeler

An architecture whiteboard,
on an open notation.

SCAN is a YAML/JSON metamodel for software systems — services, datastores, streams, agents, repositories, and typed connections. Sphere is the reference whiteboard that reads, writes, and validates it.

See SphereRead the notationSee the story →
sphere · product demo

Sphere product demo · ~1:30

sphere · order-platform.scan.yaml
Sphere whiteboard showing an order platform: Order API, Payment Service, Inventory Service, Orders DB, an Order Created Kafka stream, and an Engineering Agent Runtime — with an Inspector panel and an 'Ask Sphere to fix' warning.
Sphere · whiteboard

The architecture board that stays in sync with the model.

Sphere is the reference modeler for SCAN — a live canvas where every box, port, and arrow is a validated node in a YAML document you can check into git.

Fast design
Pen tool on the rail — click services, thin-box datastores, large-box boundaries, click-to-click connect, with an on-canvas legend.
Ask Sphere
On-canvas and inspector chips scoped to the selected component. Architecture warnings offer Ask Sphere to fix in one click.
Voice mic
Dictate into the AI bar — local speech-to-text fills the prompt and submits design chat automatically.
Live architecture warnings
Enterprise Architect review surfaces ephemeral issues on the board — not a static mock — with re-validate feedback after a fix.
Multi-select & checks
Ctrl/Cmd+click components and boundaries, drag the group, and see green selection checkmarks plus a selection count.
Readable wires
Orthogonal edges with lane gaps and deconflicted labels. Typed connections stay validated by @spherescan/rules.
SCAN · notation

System & Component Architecture Notation.

An open YAML/JSON metamodel for software architecture. Semantics live in root collections, presentation under views[], validation by @spherescan/model and @spherescan/rules.

Principle
Keep architectural type (role) separate from technology (stack). A node is a service first; it happens to be Spring Boot.
Connection types
synchronous-requestRequest/response (REST)
grpc-requestSynchronous gRPC call
database-accessClient → datastore
event-publicationProducer → channel
event-subscriptionChannel → consumer
stream-consumeStream / topic consume
agent-delegationAgent → agent
git-integrationSystem → repository
checkout.scan.yaml
scan: "0.1"
scan: "0.1"

system:
  id: checkout
  name: Checkout

components:
  - id: checkout-api
    name: Checkout API
    type: service
    technology: NestJS
    exposes:
      - id: checkout-api-out
        label: REST
        protocol: OpenAPI

external_systems:
  - id: payments
    name: Payments Provider
    exposes:
      - id: payments-out
        label: REST

connections:
  - id: c1
    from: payments
    to: checkout-api
    type: synchronous-request
    label: REST

views:
  - id: board
    layout:
      checkout-api: { x: 320, y: 120, w: 260, h: 190 }
      payments:     { x:  40, y: 120, w: 220, h: 150 }
The toolkit

Five packages. One model.

SCAN ships as small, embeddable libraries. Read a document, render it, edit it, validate it — pick the surface you need.

@spherescan/model
Parse / serialize / validate SCAN YAML & JSON
@spherescan/rules
Legal connection pairs + port checks
@spherescan/viewer
Model → board graph; SVG/PNG export
@spherescan/modeler
Command stack: move, connect, create, auto-layout, undo
@spherescan/cli
validate, export svg, …
Embed the viewer
import { ScanViewer } from "@spherescan/viewer";

const viewer = new ScanViewer({ container: "#canvas" });
await viewer.importYAML(yamlString);
Feature tour

Every control on the board, explained.

A guided walk through Sphere — Fast design, Ask Sphere, voice, live warnings, canvas, ports, and typed connections — with screenshots for each control.

Explore all featuresBack to overview
Fast design
Sketch services, datastores, and boundaries with one pen tool.
Ask Sphere
Canvas + inspector chips and one-click fixes from warnings.
Voice mic
Dictate prompts; local STT auto-submits design chat.
Live warnings
Enterprise Architect toast with re-validate while fixing.
Multi-select
Ctrl/Cmd+click, group drag, green selection checks.
Clean wires
Orthogonal lanes, hop arcs, typed validated connections.
Brought to you by Sphere

SCAN is free and open.
Sphere takes it further.

The SCAN notation is developed and maintained by the team behind Sphere. Use the libraries and CLI freely — or create a free Sphere account to design SCAN schemas with an AI copilot, collaborate with your team, and keep architecture in sync with your codebase.

Create a free Sphere accountOr just use the notation
Sphere
AI copilot for SCAN
Describe a system in plain English and Sphere drafts the SCAN schema — components, ports, typed connections, and a clean starting layout.
Sphere
One-click fixes
Architecture warnings surface inline on the canvas. Missing async contract? Illegal connection? Ask Sphere to fix and accept the diff.
Sphere
Team boards & history
Live multiplayer editing, versioned diagrams, comments on elements, and a shared library of reusable components across your systems.
Sphere
Git-native round-trip
Sphere reads and writes the same SCAN YAML you check into git. Review architecture changes as pull requests, like code.

Start modeling with Sphere, or build on SCAN.

Open the web editor to design an architecture whiteboard, or grab the open-source toolkit.

Open Sphere web editor →@spherescan on npmscan-js on GitHubContact SphereScan