The three altitudes

Vishwakarma describes a system at three heights at once: the domain and application model it is made of, the architecture its capabilities compose into, and the flows that move through it. The same model carries all three, and the compiler generates from all three together. The running example is Chowk, a small marketplace.

The domain and application model

This is the ground floor — the nouns, the facts, and the operations that change them. An entity is an aggregate with its fields, relationships, isolation, and indexes. Here is an order line: one product-and-quantity on an order.

entity OrderLine aggregate_root global {
  audit   timestamps

  indexes [
    { name "ix_order_line_order" kind standard fields [order_id] }
  ]

  id         uuid  pk filterable[eq]
  order_id   uuid  required immutable filterable[eq] relates Order many_to_one on_delete cascade
  product_id uuid  required immutable filterable[eq]
  quantity   int32 required
  unit_price Money required
}

A line item is conceptually part of an order, but every persisted entity is its own aggregate — so the line is its own root, tied to its order by relates Order many_to_one on_delete cascade. The cascade is what makes the ownership real: delete the order and its lines go with it.

Around the entity sit the verbs: a command writes, a query reads, an event records a fact, a subscription reacts to one, and a use_case orchestrates several operations as a state machine. This layer descends well below "boxes and arrows" — it reaches field constraints, row-level isolation, and index shape. It is the full behavioral specification, not a sketch.

The architecture overlay

Above the model is the structural view: the capabilities the operations compose into, what they cost, and what they supply. A system groups operations under a capability heading, carries its cost and value as metadata, and declares the capabilities it provides.

system OrderingSystem {
  title "Ordering"
  kind  capability
  doc   "Chowk's checkout lifecycle: open an order, add its lines, pay, and read it back."

  metadata {
    operating_cost:  40
    business_value:  10
    criticality:     "critical"
  }

  // The capabilities this system supplies to the flows that need them.
  provides {
    OrderCheckout maturity "beta"
    OrderPayment  maturity "beta"
    OrderTracking maturity "beta"
  }
}

This overlay is a genuine architecture description: components, cost and value, and the capabilities each system supplies. Because operations tag themselves into a system, the picture stays true as the model grows — it is derived from the same source, not maintained by hand in a separate document.

The flow lens

The third height models how a persona reaches a goal. A business_process names an actor, states a goal, and lists the steps it traverses. Crucially, a step declares the capability it needs — not the operation that supplies it — and forks on outcome.

business_process PlaceAndPayOrder {
  title "Place and pay for an order"
  actor platform.v1.Customer
  goal  "A customer opens an order with its first line, pays it, and reads the paid order back."

  step checkout "Open an order with its first line" {
    requires [OrderCheckout]
    on success -> pay
    on error   -> end "checkout-rejected"
  }
  step pay "Pay for the order" {
    requires [OrderPayment]
    on success -> confirm
    on error   -> end "payment-failed"
  }
  step confirm "Read the paid order back" {
    requires [OrderTracking]
  }
}

A step can name a capability that no system provides yet. That is not an error; it is a plan. The step becomes a build task, and it reconciles automatically once a system declares it in a provides block. One tier up, a journey composes whole business processes into a persona's end-to-end arc. The flow lens is where you describe the intended experience before the model that realizes it exists.

One model, three views

These are not three artifacts to keep in sync. They are three views of one description, and a capability is the hinge between two of them: the business process's step requires OrderCheckout, the system provides OrderCheckout, and reconciliation matches them — the same node seen from the flow side and the structure side. The domain model says what the system is, the overlay says how its capabilities are structured, and the flows say how someone moves through it — and the compiler reads all three to check the design and generate the system. You author at whichever height the work calls for, and the others stay consistent because they read from the same source.