SCAN reference

Distilled from the normative scan-0.1 spec. Machine schemas live in @spherescan/model. If implementations disagree with the human spec, the spec wins.

Canonical serialization is YAML. JSON uses the same schema. Legacy root key sphere: is accepted as an alias for scan:.

System

system:
  id: order-platform
  name: Order Platform
  purpose: Process customer orders
  owner: Commerce Team

Required: id, name. Optional: purpose, owner.

Components

components:
  - id: order-api
    name: Order API
    type: service
    technology: Spring Boot
    repository:
      provider: github
      path: company/order-api
    status: warn
    warn: Missing async contract
    consumes: [ ... ]
    exposes: [ ... ]

Component type

Value	Typical use
service	Application / API
datastore	Database / store
search	Search / index
external-system	Prefer external_systems collection
agent	Prefer agents
repository	Prefer repositories
event-stream	Prefer channels

Optional: subtitle, icon (Lucide name, URL, or data URL), status (ok | warn), warn.

Channels

channels:
  - id: order-created
    name: Order Created
    type: event-stream
    technology: Kafka

External systems, agents, repositories

Same port pattern as components. Agents may set runtime to an agent_runtimes id. Repository nodes use provider / path.

Connections

connections:
  - id: e1
    from: order-api
    to: orders-db
    type: database-access
    label: DB Access
    fromSide: b
    toSide: t
    fromPort: oa-out
    toPort: db-in
    contract: OpenAPI
    operations:
      - POST /orders

Connection types (0.1)

Type	Meaning
synchronous-request	Request/response (e.g. REST)
grpc-request	Synchronous gRPC-style
database-access	Client → datastore
event-publication	Producer → channel
event-subscription	Channel → consumer
stream-consume	Stream / topic consume
agent-delegation	Agent → agent
git-integration	Agent/system → repository

Legal kind pairs: @spherescan/rules. Reference integrity: validateScanModel in @spherescan/model.

fromSide / toSide are diagram DI only: l | r | t | b.

Views and boundaries

views:
  - id: architecture-board
    type: service-architecture
    boundaries:
      - id: g-order
        label: Order Platform
        kind: trust
        members: [order-api, orders-db]
        x: 420
        y: 60
        w: 1240
        h: 620
    layout:
      order-api: { x: 480, y: 180, w: 260, h: 190 }

Boundary kind: trust | runtime (default trust). Layout entries need at least x, y; w / h optional.

Validation

1. Structural — JSON Schema / Zod in @spherescan/model
2. Semantic — validateScanModel(model) → { ok, issues[] }
3. CLI — scan validate file.yaml (exit 1 on errors)