Core Concepts

A quick tour of the objects and ideas you’ll meet everywhere in SIP.IO. Each links to its deep-dive.

The brain and the edge

SIP.IO splits cleanly into a control plane and a media/signaling edge.

• Control plane (the brain): an edge runtime plus stateful edge objects. It makes every decision: who may register, where a call goes, what a flow does next, which agent takes a queued call, and whether a new call is admitted. See The Control Plane.
• Edge (the node): the SIP signaling layer, the media relay, and the media engine on a SIP node. It carries SIP and RTP, and executes what the brain tells it. See The Media Edge.

The guiding rule: if the platform doesn’t need to answer the call, it just proxies it (media flows through the media relay’s kernel relay). the media engine is only inserted when the platform itself must speak, collect digits, queue, record, or mix.

Tenancy

• Account: your tenant. Accounts form a hierarchy for reseller / white-label use: an account can have a parent, its own brand domain, and default language/timezone. See Multi-Tenant & White-Label.
• SIP domain: a realm an account answers on (its own plus white-label vanity domains).

Identity

• sip_user is the logical identity/extension: a person or an agent. It owns presentation (caller-ID), concurrency ceiling, and (if is_agent) queue membership.
• sip_device is a registering endpoint (desk phone, softphone, WebRTC) that holds a SIP digest credential. One user can own several devices.

Numbers and routing targets

• DID: an inbound number (E.164). It points at a single route target.
• Extension: an internal short code (ext-to-ext, feature codes), also pointing at a route target.
• Route target: the consistent trio used everywhere a call can go next:
  • dest_kind is a typed enum: flow, user, extension, ring_group, queue, voicemail, conference, forward, hangup.
  • dest_id is the id within the table implied by dest_kind.
  • dest_xform holds small JSON variables applied on that hop.

Simple direct routes stay simple (dest_kind: "user"); anything branching folds into a call flow (dest_kind: "flow"). See Numbers & Extensions.

Call flows

A call flow is a versioned JSON node-graph, React-Flow-compatible for the visual builder and executable by the interpreter. Nodes are actions (play, menu, collect, dial, enqueue, voicemail, condition, timeCondition, httpRequest…); edges carry the outcome (digit:1, timeout, answered, in_hours…). Each live call walks the graph inside its own CallSessionDO. See Call Flows.

Contact center

• Queue: ACD config (strategy, timeouts, wrap-up, announcements, MOH mode, overflow exits). The live brain is the PresenceDO; the queue row is the static config it loads.
• Agent is a sip_user with is_agent = 1, a member of one or more queues (with a skill tier). Agents log in / pause / go available through the agent control surface.
• Presence: live, derived state (available, offering, in-call, wrap-up, reachable) kept in the per-account PresenceDO.
• Ring group: fork a call to several members at once (or in order), then fall through to an exit. See Ring Groups.

Schedules (business hours)

A time_schedule is a reusable, timezone-aware set of rules (weekly hours, specific dates, date ranges, holiday overrides). It can be:

• evaluated inside a flow by a timeCondition node, or
• attached to an object (DID, extension, queue, ring group) so that being closed/holiday overrides the route target (the “hours on the queue” model).

See Business Hours.

Concurrency control (CAC)

Every call passes admission control: per-account concurrency ceilings (max_in, max_out, max_dialer), per-user simultaneous limits, per-DID channel caps, and sliding-window rate rules. It’s enforced atomically inside the per-account PresenceDO. See Concurrency Control.

State, in three places

SIP.IO is deliberate about where each kind of state lives:

State	Lives in	Why
Configuration (accounts, numbers, queues, schedules)	the edge SQL database (SQLite)	Queryable, relational, the source of truth
Live call & agent state (presence, reservations, CAC counters, flow position)	stateful edge objects	Single-threaded, atomic, per-account / per-call
SIP registrations / contacts	the registrar's location store	The registrar’s job
CDRs & call-event traces	object storage (Apache Iceberg)	Cheap, columnar, huge volume; see Observability
Media (prompts, MOH, voicemail)	object storage	Object storage, served to the edge
Secrets (trunk passwords, tokens, PINs)	the key-value store (encrypted)	Never plaintext; referenced by *_secret_ref

With the vocabulary in hand, continue to Edge-Native Architecture.