إنتقل إلى المحتوى الرئيسي

AVL: Almadar Visual Language

AVL is the formal visual notation for Orb programs. Every construct in the .orb language has a corresponding visual symbol. These diagrams are language-neutral: identical across English, Arabic, and Slovenian.

The Orbital Unit​

The fundamental building block. An Orbital Unit is: one Entity (the data), one or more Traits (the behavior), and Pages (the routes).

TaskLifecycleAssignment/tasks/task/:id

Reading this diagram:

  • The outer circle is the orbital boundary (the module shell)
  • The filled circle at center is the Entity nucleus. Radiating lines = fields. "Task" with 5 fields.
  • The dashed ellipses are Traits (state machines). "Lifecycle" and "Assignment" orbit around the entity.
  • The small squares on the boundary are Pages (routes). "/tasks" and "/task/:id".

Structural Primitives​

Entity​

The data nucleus. The stroke style tells you how data is stored:

Persistent (solid)
Runtime (dashed)
Singleton (double)

Orbital, Trait, Page​

Module
Orbital (boundary)
Behavior
Trait (state machine)
/route
Page (route)

Behavioral Primitives​

States and Transitions​

States are rounded rectangles arranged in a ring. Transitions are arrows between them. The initial state has a dot marker. Terminal states have a double border.

FETCHDONEFAILRETRYRESETidleloadingsuccesserror

Events, Guards, Effects​

Each transition can have:

CLICK
Event (trigger)
isValid?
Guard (condition)

14 Effect types, each with a distinct icon:

render-ui
set
persist
fetch
emit
navigate
notify
call-service
spawn
despawn
do
if
log

The Closed Circuit​

Every user action follows a guaranteed loop: Event triggers a Transition, which checks a Guard, executes Effects, updates the UI, and is ready for the next Event.

EventGuardTransitionEffectsUI Response

Cross-Orbital Communication​

Traits emit events that other traits in other orbitals listen to. This is how orbitals communicate without coupling.

OrdersInventory~ORDER_PLACED~ ~ ~

Data Primitives​

Field Types​

Each data type has a distinct shape:

string
number
boolean
date
enum
object
array

Bindings​

References to schema data: @entity.field, @payload.value, @state, @now.

@entity.name
@payload.id

Expression Trees​

Logic in Orb is written as s-expressions: ["gt", "@entity.age", 18]. AVL renders these as trees:

andgt@entity.age18eq@entity.statusactive

Slot Map​

Pages have named regions where traits render their UI. The slot map shows which patterns appear where:

Page Layoutheadersidebarmainmodal (overlay)toast (overlay)

Operator Namespace Colors​

S-expression operators are color-coded by namespace:

NamespaceColorExample
arithmeticBlue #4A90D9+, -, *, /
comparisonOrange #E8913Agt, lt, eq, neq
logicPurple #9B59B6and, or, not
stringGreen #27AE60concat, upper, lower
collectionTeal #1ABC9Cmap, filter, find
timeYellow #F39C12now, format-date
controlRed #E74C3Cif, cond, match
asyncPink #E91E8Fdebounce, throttle

Interactive Cosmic Zoom​

The AVL Cosmic Zoom lets you explore an entire application interactively. Click orbitals to zoom into their traits, click traits to see their state machines, click transitions to see effect trees.

Loading visualization...

How to Read AVL Diagrams​

  1. Find the Entity nucleus at the center. The stroke style tells you the persistence kind (solid = persistent, dashed = runtime, double = singleton).
  2. Count the radiating lines to see how many fields the entity has.
  3. Follow the elliptical orbits to identify traits (state machines).
  4. Look for square markers on the orbital boundary for pages (routes).
  5. Inside each trait, states form a layout with transition arrows between them.
  6. Transition labels show: event name (bold), effect icons (below).
  7. Dashed arrows between orbitals show cross-orbital event flow (emit/listen).
  8. Color coding: operator namespace colors follow the table above.