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).

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

Orbital (boundary)

Trait (state machine)

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.

Events, Guards, Effects

Each transition can have:

Event (trigger)

Guard (condition)

14 Effect types, each with a distinct icon:

---

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.

---

Cross-Orbital Communication

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

---

Data Primitives

Field Types

Each data type has a distinct shape:

Bindings

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

---

Expression Trees

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

---

Slot Map

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

---

Operator Namespace Colors

S-expression operators are color-coded by namespace:

Namespace	Color	Example
arithmetic	Blue #4A90D9	+, -, *, /
comparison	Orange #E8913A	gt, lt, eq, neq
logic	Purple #9B59B6	and, or, not
string	Green #27AE60	concat, upper, lower
collection	Teal #1ABC9C	map, filter, find
time	Yellow #F39C12	now, format-date
control	Red #E74C3C	if, cond, match
async	Pink #E91E8F	debounce, 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.