S C A N
01 / 10
Origin01 / 10

Architecture starts as a shared idea.

Every system begins as a picture in someone's mind.

  • Components, responsibilities and interactions
  • A model the whole team needs to understand
  • Before code, there is structure
System sketch
Web App
Service
Service
Orders API
Service
Service
Payments
Service
Service
Database
Database
DB
v0.1 · shared idea
01
Drift02 / 10

Then the picture becomes fragmented.

The architecture rarely stays in one place.

  • Diagrams in presentation files
  • Contracts in separate repositories
  • Decisions buried in documentation and conversations
  • Implementation drifting away from the original model
Presentation · Architecture Slide
Order API → Payment
API Contract · Repository
paths:
/orders:
get:
post: ...
Decisions · Documentation
ADR-017 — API strategy · Accepted
ADR-012 — Eventing
ADR-008 — Data consistency
Team Channel
Emma · Should Order API expose REST + gRPC?
Luca · Yes — aligns with ADR-017.
Priya · Agreed. Consumers need both.
02
Decay03 / 10

Static diagrams lose contact with reality.

A diagram can describe the system — and still know nothing about it.

  • Boxes have no operational meaning
  • Connections hide their contracts
  • Changes are difficult to trace
  • The diagram becomes outdated
Outdatedv1.2.4 · 2023-08-17
Web App
Order Service
Payment Service
Database
03
Notation04 / 10

Meet SCAN.

A notation for architecture understood by people and machines.

  • Components and connections
  • Boundaries and responsibilities
  • Structured to validate and render
  • Portable as a simple specification
Trust Boundary
Payment Platform
External System
Exposes
REST (OpenAPI)
External
Fraud Provider
External System
Exposes
gRPC (Proto)
External
Order API
Service
Consumes
REST (OpenAPI)
gRPC (Proto)
Exposes
REST (OpenAPI)
Service
Payment Service
Service
Consumes
REST (OpenAPI)
Service
Inventory Service
Service
Consumes
REST (OpenAPI)
Exposes
REST (OpenAPI)
Service
Orders DB
Database
DB
Order Created
Event
Consumes
OrderCreated (v1)
Exposes
OrderCreated (v1)
Event Stream
Search Index
Data Store
Consumes
OrderCreated (v1)
Search
REST
OpenAPI
REST
OpenAPI
gRPC
Proto
DB Access
JDBC
Publish
AsyncAPI
Stream
AsyncAPI
04
Components05 / 10

Every component is more than a box.

A component carries its identity, role, technology and deployment context.

  • Name, type and description
  • Clear responsibility and architectural role
  • Technology and deployment context
  • Consistent identity through component type
Trust Boundary
Payment Platform
External System
Exposes
REST (OpenAPI)
External
Fraud Provider
External System
Exposes
gRPC (Proto)
External
Order API
Service
Consumes
REST (OpenAPI)
gRPC (Proto)
Exposes
REST (OpenAPI)
Service
Payment Service
Service
Consumes
REST (OpenAPI)
Service
Inventory Service
Service
Consumes
REST (OpenAPI)
Exposes
REST (OpenAPI)
Service
Orders DB
Database
DB
Order Created
Event
Consumes
OrderCreated (v1)
Exposes
OrderCreated (v1)
Event Stream
Search Index
Data Store
Consumes
OrderCreated (v1)
Search
REST
OpenAPI
REST
OpenAPI
gRPC
Proto
DB Access
JDBC
Publish
AsyncAPI
Stream
AsyncAPI
Order API
Service
Service
DescriptionReceives and coordinates customer orders.
ResponsibilityOrder intake and orchestration
TechnologyJava · Spring Boot
DeploymentCloud Run
05
Contracts06 / 10

Every connection explains how the system collaborates.

Connections are contracts — with direction, protocol and payload.

  • Required and provided interfaces
  • APIs, events and data flows
  • Direction and dependency made visible
  • Contracts accessible from the architecture
Trust Boundary
Payment Platform
External System
Exposes
REST (OpenAPI)
External
Fraud Provider
External System
Exposes
gRPC (Proto)
External
Order API
Service
Consumes
REST (OpenAPI)
gRPC (Proto)
Exposes
REST (OpenAPI)
Service
Payment Service
Service
Consumes
REST (OpenAPI)
Service
Inventory Service
Service
Consumes
REST (OpenAPI)
Exposes
REST (OpenAPI)
Service
Orders DB
Database
DB
Order Created
Event
Consumes
OrderCreated (v1)
Exposes
OrderCreated (v1)
Event Stream
Search Index
Data Store
Consumes
OrderCreated (v1)
Search
REST
OpenAPI
REST
OpenAPI
gRPC
Proto
DB Access
JDBC
Publish
AsyncAPI
Stream
AsyncAPI
Payment Service
Service
Consumes
REST (OpenAPI)
Service
Order API → Payment Service
REST · OpenAPI
POST /payments
View contract
06
Zoom07 / 10

Move from system landscape to component context.

Focus on one boundary without losing orientation.

  • Start with the whole architecture
  • Focus on one boundary or component
  • Reveal dependencies and interfaces
  • Return without losing orientation
Trust Boundary
Order Domain · Bounded Context
Payment Platform
External System
Exposes
REST (OpenAPI)
External
Fraud Provider
External System
Exposes
gRPC (Proto)
External
Order API
Service
Consumes
REST (OpenAPI)
gRPC (Proto)
Exposes
REST (OpenAPI)
Service
Payment Service
Service
Consumes
REST (OpenAPI)
Service
Inventory Service
Service
Consumes
REST (OpenAPI)
Exposes
REST (OpenAPI)
Service
Orders DB
Database
DB
Order Created
Event
Consumes
OrderCreated (v1)
Exposes
OrderCreated (v1)
Event Stream
Search Index
Data Store
Consumes
OrderCreated (v1)
Search
REST
OpenAPI
REST
OpenAPI
gRPC
Proto
DB Access
JDBC
Publish
AsyncAPI
Stream
AsyncAPI
07
Validation08 / 10

A structured model can check itself.

Missing references, incomplete contracts, disconnected nodes — surfaced automatically.

  • Detect missing or invalid references
  • Surface incomplete contracts
  • Reveal disconnected components
  • Keep topology and specification aligned
Trust Boundary
Payment Platform
External System
Exposes
REST (OpenAPI)
External
Fraud Provider
External System
Exposes
gRPC (Proto)
External
Order API
Service
Consumes
REST (OpenAPI)
gRPC (Proto)
Exposes
REST (OpenAPI)
Service
Payment Service
Service
Consumes
REST (OpenAPI)
Service
Inventory Service
Service
Consumes
REST (OpenAPI)
Exposes
REST (OpenAPI)
Missing contract
Service
Orders DB
Database
DB
Order Created
Event
Consumes
OrderCreated (v1)
Exposes
OrderCreated (v1)
Event Stream
Search Index
Data Store
Consumes
OrderCreated (v1)
Search
REST
OpenAPI
REST
OpenAPI
gRPC
Proto
DB Access
JDBC
Publish
AsyncAPI
Stream
AsyncAPI
Validation
12 passed
2 issues
08
Viewpoints09 / 10

One model. Multiple viewpoints.

The same architecture, answering different questions.

  • System — landscape and boundaries
  • Dependencies — relationships and impact
  • Contracts — APIs, events and data flows
System
Landscape and boundaries
Dependencies
Relationships and impact
Contracts
APIs, events and data flows
Trust Boundary
Payment Platform
External System
Exposes
REST (OpenAPI)
External
Fraud Provider
External System
Exposes
gRPC (Proto)
External
Order API
Service
Consumes
REST (OpenAPI)
gRPC (Proto)
Exposes
REST (OpenAPI)
Service
Payment Service
Service
Consumes
REST (OpenAPI)
Service
Inventory Service
Service
Consumes
REST (OpenAPI)
Exposes
REST (OpenAPI)
Service
Orders DB
Database
DB
Order Created
Event
Consumes
OrderCreated (v1)
Exposes
OrderCreated (v1)
Event Stream
Search Index
Data Store
Consumes
OrderCreated (v1)
Search
REST
OpenAPI
REST
OpenAPI
gRPC
Proto
DB Access
JDBC
Publish
AsyncAPI
Stream
AsyncAPI
Validation
12 passed
2 issues
09
Together10 / 10

Describe the system once. Understand it together.

SCAN is a shared, open language for architecture.

  • Open. Portable. Built for architecture.
Trust Boundary
Payment Platform
External System
Exposes
REST (OpenAPI)
External
Fraud Provider
External System
Exposes
gRPC (Proto)
External
Order API
Service
Consumes
REST (OpenAPI)
gRPC (Proto)
Exposes
REST (OpenAPI)
Service
Payment Service
Service
Consumes
REST (OpenAPI)
Service
Inventory Service
Service
Consumes
REST (OpenAPI)
Exposes
REST (OpenAPI)
Service
Orders DB
Database
DB
Order Created
Event
Consumes
OrderCreated (v1)
Exposes
OrderCreated (v1)
Event Stream
Search Index
Data Store
Consumes
OrderCreated (v1)
Search
REST
OpenAPI
REST
OpenAPI
gRPC
Proto
DB Access
JDBC
Publish
AsyncAPI
Stream
AsyncAPI
order-system.scan.yamlSCAN
components:
  - id: order-api
    type: service
    name: Order API
    exposes:
      - rest: POST /orders
    consumes:
      - payment-service
      - orders-db

connections:
  - from: order-api
    to: payment-service
    contract: Payments.charge/v1
    protocol: https
GitHub
Explore the notation
Web modeler
app.spherescan.io
npm
Install the package
10