Documentation / System Design
Getting StartedSign in

AAL System Design language reference

Understand declarations, identifiers, properties, references, and validation.

AAL System Design 0.2 · Dictionary 0.2.0

Document structure

AAL is the text form of your diagram. Start with a complete document, then change one declaration at a time. The small Orders flow below uses two elements and one relationship.

Read the document

DeclarationPurpose
aal system-design "0.2"Selects the System Design language.
dictionary "0.2.0"Selects the element dictionary.
designGives the design a stable ID and quoted display name; braces contain its declarations.
environmentOptional context such as production. Omit it for logical integrations or data flows.
elementAn ID and quoted name, with an optional type inside the block. Nested elements establish containment.
relationAn ID, source -> destination, interaction kind, and quoted label.
Customer sends a request to Orders API.
Complete first request flow
aal system-design "0.2"
dictionary "0.2.0"
design OrdersFlow "Orders request flow" {
  element Customer "Customer"
  element Api "Orders API"
  relation Request Customer -> Api connect "Submit order"
}

Identifiers and references

An ID connects declarations; a display name helps people read them. In Customer → Api, Api is the reference even if its displayed name is Orders API.

Keep references valid

  • Give elements and relations unique, stable IDs.
  • Rename a quoted display name to improve readability. If you change an ID, update its intended references too.
  • Nesting determines parent IDs. Other references and relation endpoints must identify existing elements.
  • Use compiler diagnostics or Inspector to check referenced kinds and allowed containment. The appearance of the diagram alone does not prove its references are valid.

Validation and property values

Diagnostics explain what prevents the source from becoming a valid diagram. The compiler checks syntax, IDs, dictionary types, references, and supported structure.

Repair the source

  1. Start with the first actionable diagnostic.
  2. Check quoted strings, property types, and any referenced IDs. Use typed Inspector controls or the dictionary’s type-specific examples.
  3. Correct the error and recheck the canvas before making unrelated changes.

Supported relationship kinds

  • request_response
  • invoke
  • publish
  • deliver
  • read
  • write
  • telemetry
  • connect
  • depends_on
  • member_of
  • runs_on

Connected customer experience

Connect a customer portal, orders, CRM, and payments around one customer journey.

Application Integration · Beginner · Application Integration · Purposeful relationships · Stable resource IDs

Uses · connectPlace order · request_responseUpdate customer · writeTake payment · request_responseCustomercustomerCustomer portalapplicationOrders APIapplicationCustomer CRMexternal systemPaymentsexternal system
Example
aal system-design "0.2"
dictionary "0.2.0"
design Example "Connected customer experience" {
  element Customer "Customer" { type generic.customer }
  element Portal "Customer portal" { type generic.application }
  element Orders "Orders API" { type generic.application }
  element CRM "Customer CRM" { type generic.external_system }
  element Payments "Payments" { type generic.external_system }
  relation Flow1 Customer -> Portal connect "Uses"
  relation Flow2 Portal -> Orders request_response "Place order"
  relation Flow3 Orders -> CRM write "Update customer"
  relation Flow4 Orders -> Payments request_response "Take payment"
}

Try changing…

  • Rename Customer while preserving its ID; its relationships remain connected.
  • Change the label of Flow1; its semantic direction stays the same.
  • Arrange the diagram and export it as SVG; visual changes stay outside AAL.