Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Core Concepts

The mental model behind AKS: what each construct is for and how they compose. All snippets here are validated against the real parser in CI.

Workspaces

A workspace is the root container — one per file, quoted name, explicit end workspace:

workspace "Commerce"
  module commerce@1.0.0
end workspace

The optional module <name>@<version> line versions the model itself.

Entities

Entities are the nodes of your architecture graph: services, databases, queues, people, external systems.

entity checkout_api
  has role: orchestration
  has description: "Order checkout flow"
  has tag critical
end entity

Entity kinds

Structural classification uses the built-in kind vocabulary in the header:

entity payments_db database
end entity

entity events queue
end entity

entity stripe external system
end entity

Kinds: database, queue, container, component, person, external system. An entity without a kind is generic.

Entity properties and tags

  • has <key>: <value> — arbitrary properties (strings, numbers, booleans, identifiers, lists, objects)
  • has tag <name> — tags, the primary grouping mechanism for views and policies

The has keyword is required — bare key: value lines are a parse error in entity bodies.

Shapes (Data Structures)

Shapes define typed data structures — the input to type modeling and code generation.

Basic shape

shape User
  id: String
  email: String
  age: Int
end shape

Nested shapes

Reference other shapes by name:

shape Address
  street: String
  city: String
end shape

shape User
  id: String
  address: Address
end shape

Collections and optionals

shape Order
  id: String
  item_ids: String[]
  coupon: String?
  audit_trail: Json
end shape

T[] list, T? optional, suffixes stack (String?[]), Json for open key-value data. Map/tuple/union types and field constraints (@min etc.) are not part of the grammar — model invariants as policies.

Events (State Changes)

Events are shapes with async/message semantics — same field grammar, different keyword:

event OrderPlaced
  order_id: String
  user_id: String
  timestamp: Timestamp
end event

Events vs shapes: use event for records of things that happened (past-tense names), shape for commands, entities’ data, and value objects.

Relationships

Two ways to express edges in the graph:

Local edges (inside the entity)

entity checkout_api
  edge payments_db depends on
    has via: "SQL"
  end edge
end entity

Standalone relationships

relationship checkout_api calls payment_service
  has protocol: https
end relationship

Both use the same phrase vocabulary (calls, depends on, sends data to, publishes, subscribes, produces, consumes, … — see grammar §6). Unknown single words become custom phrases.

Shape conformance

An entity that owns/implements a data structure references the shape in its header:

entity user_service: User
  has role: orchestration
end entity

Multiple services may reference the same shape; an entity can reference at most one shape directly (model composites with edges or tags).

Provenance (Evidence)

Track where a claim about the architecture comes from:

entity checkout_api
  derived from: "doc:checkout-design"
  evidenced by: "trace:prod:checkout"
  verified by: "test:integration-suite"
end entity

Verbs: derived from, evidenced by, observed in, verified by, deprecated by. Provenance also attaches to edges and relationships. Values conventionally encode a source category prefix (doc:, trace:, test:, mirror:, code:).

Governance: Lattices and Policies

Lattices define ordered domains; policies state rules over the graph:

lattice Tier
  order best_effort < standard < critical
end lattice

policy critical_ownership
  applies to tag: critical
  must have owner
  requires tier at least standard
end policy

See grammar §8–9 and the governance examples.

Views and Projects

Views are filtered projections for diagrams; projects bundle entities with configuration:

view revenue_overview
  kind: system
  schema: c4
  include: tag: revenue_path
  focuses_on: checkout_api
end view

project checkout_system
  includes entity checkout_api
  has team: payments
end project

A Complete Workspace

workspace "Commerce"
  module commerce@1.0.0

  # Data structures
  shape Product
    id: String
    price: Float
  end shape

  # Events
  event ProductPurchased
    product_id: String
    timestamp: Timestamp
  end event

  # System components
  entity storefront
    has role: presentation

    edge catalog_api depends on
    end edge
  end entity

  entity catalog_api: Product
    has role: orchestration
    has tag critical
    has owner: catalog_team

    edge catalog_db depends on
    end edge
  end entity

  entity catalog_db database
  end entity

  # Governance
  policy critical_ownership
    applies to tag: critical
    must have owner
  end policy

  # Projection
  view overview
    kind: system
    schema: c4
    include: tag: critical
  end view
end workspace

Next