Sphere·SCANscan-js on GitHub
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 notation
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.

All Systems, one canvas
Model services, external systems, contracts, and agent runtimes as separate views — or zoom out to the full architecture on one board.
Typed, validated connections
REST, gRPC, DB access, publish/subscribe, agent delegation, git integration. Legality checked by @scan/rules — no service→database→agent surprises.
Inspector with real semantics
Every element carries type, technology, ports, contracts, and connections. Click a Kafka stream and see who publishes and who consumes.
Ask Sphere to fix
Architecture warnings — like a missing AsyncAPI contract on Inventory Service — surface inline, one click away from a proposed fix.
Boundaries & runtimes
Group elements into trust or runtime boundaries. Agents, coding tools, and repositories become first-class citizens of the diagram.
Auto-layout, human overrides
Layout on demand for a clean board. Positions live in views[] so hand-tuned diagrams round-trip cleanly with the model.
SCAN · notation

System & Component Architecture Notation.

An open YAML/JSON metamodel for software architecture. Semantics live in root collections, presentation under views[], validation by @scan/model and @scan/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.

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

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

Every control on the board, explained.

A guided walk through Sphere — canvas, elements, ports, typed connections, inspector, views, and the AI copilot — with screenshots for each control.

Explore all featuresBack to overview
Canvas & navigation
Pan, zoom, minimap, and quick-find across large systems.
Elements & ports
Services, streams, datastores, agents — with typed ports.
Typed connections
REST, gRPC, pub/sub, agent delegation, git integration.
Inspector
Edit type, technology, contracts, and connections in one panel.
Views & layout
Multiple views per model with auto-layout and hand overrides.
Ask Sphere to fix
Inline architecture warnings with one-click AI fixes.
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.