Vavan Core

Link types

Typed, directional relationships between object types, with cardinality, that let apps and AI traverse the model coherently.

A link type is a typed, directional relationship between two object types, with a defined cardinality. Where properties describe a single object, link types describe how objects connect: an Account has many Contacts, an Order belongs to one Account, a Route contains many Stops. Links are first-class parts of Vavan Core, not foreign keys hidden inside one app's tables.

Each link type names both ends and the direction between them, so the relationship can be traversed either way — from an Account to its Orders, or from an Order back to its Account. Because the relationship is declared once on the shared model, every app and the in-app assistant see the same connections rather than maintaining their own copies.

Note. Use a link type whenever a relationship matters in more than one place or in both directions. A lightweight Reference property can point at another object, but only a link type carries cardinality and is traversable on both ends.

Cardinality

Cardinality declares how many objects can sit on each end of a link. It is what lets the model answer "how many" correctly and lets apps render the right control — a single select versus a list.

One-to-many (1:N) — one object on the source side relates to many on the target side. Traversed from the "one" you get a collection (an Account → its Contacts); from any "many" you get back exactly one parent.
Many-to-one (N:1) — the inverse view of the same relationship: many objects each point to one parent. Traversed from a child you resolve a single parent (an Order → its Account).
Many-to-many (N:N) — objects on both sides relate to multiple objects on the other. Traversal in either direction yields a collection. These are modeled explicitly so membership is queryable from both ends.

One-to-many and many-to-one are two views of a single directional link; Vavan Core exposes both so traversal reads naturally from either object.

Representative link types

The links below are illustrative of how the operational model fits together across customer, order, fulfillment, and signal objects.

From → To	Cardinality	Meaning
Account → Contacts	1:N	An account has many people associated with it.
Order → Account	N:1	Every order belongs to exactly one account.
Order → Line Items	1:N	An order is composed of one or more line items.
Line Item → Product	N:1	Each line item references a single product from the catalog.
Route → Stops	1:N	A route is an ordered set of stops.
Stop → Order	N:1	A stop fulfills a specific order.
Account → Site / Location	1:N	An account can have many physical sites or delivery locations.
Driver → Vehicle	N:1 or 1:1	A driver is assigned a vehicle (one per shift, or a fixed pairing).
Signal → Account	N:1	A signal is raised about a specific account.
Task → Account	N:1	A task is scoped to the account it concerns.

Traversal

Traversal is the act of following links to assemble a view of the model. Apps and AI agents do not query disconnected tables; they walk the graph Vavan Core describes. A single, common traversal:

Start at an Account.
Follow Account → Orders and filter to open orders.
From each Order, follow Order → Line Items.
From each Line Item, follow Line Item → Product to see what is consumed.

The result — every product an account is currently buying — is computed by traversal, not by a bespoke join written separately in each app. The same path powers a sales rep's account view, a reorder signal, and the assistant answering "what does this customer order most."

Modeling relationships as link types — rather than duplicating a foreign key in each app's own schema — is what keeps the model coherent. There is one definition of how Orders relate to Accounts, so a change made by the dispatch app and a query run by the CRM app see the same truth. Duplicated keys drift; shared links do not.

Note. Like all Vavan Core data, link traversal is organization-scoped: following a link can only ever reach objects within the same organization. See Security.

Conceptual example

The following is a conceptual example of a link-type declaration, not a literal API payload:

# conceptual example — link type definition
link:
  name: order_account
  from: Order
  to: Account
  cardinality: many_to_one   # many orders -> one account
  inverse: account_orders    # Account -> Orders (one_to_many)

Links and the closed loop

Links are what let work flow across apps without re-entry. A lead captured in the CRM becomes an account; that account's orders are dispatched onto routes; route stops resolve back to orders and accounts; fulfillment updates raise signals against the same account. Each app contributes to one connected graph instead of its own island. This is the closed loop the platform is built around — see the Platform overview.

Continue with action types, the governed operations that create and modify objects and the links between them.