Core Concepts

NOTE

This documentation is currently Work In Progress.

Understanding the core concepts of BoardAPI will help you build better applications.

Boards

The central canvas where collaboration happens. Every board is an infinite whiteboard powered by Excalidraw, enhanced with BoardAPI's enterprise features.

Board Lifecycle

Boards follow a predictable lifecycle:

Creation - A board is created via API with an organization owner
Active - Participants can join, collaborate, and create objects
Archived - Board is preserved but read-only (retention policy applies)
Deleted - Permanently removed after retention period

Board Identity

Each board has:

UUID - Globally unique identifier
Name - Human-readable title
Organization ID - Owning organization for isolation
Access Tokens - JWT tokens for host and guest access

Board State

Board state consists of:

Canvas Elements - Excalidraw shapes, text, arrows synced via Yjs CRDT
Custom Objects - Organization-defined objects with customData
Participants - Currently connected users with presence information
Metadata - Creation time, last activity, version

Access Control

Two access levels:

Host - Full control (create, edit, delete, invite, settings)
Guest - Limited access (view, edit based on permissions)

Stateless participants join via shareable links without registration.

Objects

Elements on the board include both Excalidraw native elements and custom objects.

Object Types

Native Excalidraw Elements:

Shapes (rectangle, ellipse, diamond)
Text boxes
Arrows and lines
Hand-drawn paths
Images

Custom Objects (via Object Types API):

Organization-defined types with JSON Schema
Custom rendering and interactions
Typed data in customData field

Object Structure

Every object has:

json

{
  "id": "obj_unique_id",
  "type": "vocabulary-card",
  "x": 100,
  "y": 200,
  "width": 300,
  "height": 200,
  "customData": {
    "word": "hello",
    "translation": "привет",
    "pronunciation": "https://..."
  }
}

Custom Data

The customData field stores typed data validated against your registered Object Type schema. This enables:

Rich domain models (vocabulary cards, quiz questions, tasks)
Type safety and validation
Custom rendering via External Components
Searchable structured data

Object Operations

Via REST API:

POST /boards/:uuid/objects - Create object
PUT /boards/:uuid/objects/:id - Update object
DELETE /boards/:uuid/objects/:id - Delete object
GET /boards/:uuid/objects - List all objects

Via WebSocket:

object:create - Real-time object creation
object:update - Real-time updates (position, data)
object:delete - Real-time deletion

Frames

Frames divide the infinite canvas into structured areas (slides, rooms, sections). Think of them as "slides in a presentation" or "rooms in a building."

What are Frames?

A Frame is a rectangular region with:

Name and description
Position and size (x, y, width, height)
Lock mode for access control
Visibility state

Lock Modes

Three levels of access control:

None - Free navigation

Participants can scroll anywhere on the canvas
No restrictions

Soft Lock - Gentle guidance

Participants can leave the frame
"Return to lesson" indicator shown when outside
Ideal for classroom scenarios

Hard Lock - Strict boundaries

Participants cannot scroll outside the frame
Perfect for exams and controlled environments

Teachers can:

Create frames via Frame Manager UI
Navigate participants to specific frames
Track who is viewing each frame
Use with Follow Me mode for synchronized navigation

Use Cases

Presentations - Each frame is a slide
Lesson Plans - Structured activities in sequence
Group Workspaces - Separate areas for teams
Exams - Isolated problem sets

Learn more in Frames Guide.

Zones

Student Zones enable personalized, isolated workspaces within a board. This is a unique BoardAPI feature not found in competitors.

What are Zones?

A Zone is a designated area assigned to a specific participant:

Only the assigned participant can edit objects inside
Host maintains full control
Zones can be hidden from other participants (exam mode)

Zone Features

Assignment

One participant per zone
Bulk assignment for classes
Reassignment supported

Isolation

Only assigned participant can create/edit/delete objects inside
Violation detection returns objects to original position
Other participants see zone boundaries

Privacy

Zones can be hidden from other students
Perfect for independent work and exams
Host always sees all zones

Zone vs Frame

Feature	Frame	Zone
Purpose	Navigation structure	Edit permissions
Access Control	View boundaries	Edit isolation
Assignment	All participants	Single participant
Can overlap	No	No

Use Cases

Individual Assignments - Each student gets their workspace
Exams - Isolated work areas with privacy
Group Projects - Zones for different team members
Presentations - Student presentation areas

Learn more in Student Zones Guide.

Participants

People connected to a board in real-time.

Participant Roles

Host

Creator of the board
Full permissions (create, edit, delete, settings)
Can manage participants (kick, change permissions)
Access to advanced features (Frames, Zones, AI)

Guest

Joins via shared link
View and edit by default
Permissions can be restricted by host
Stateless - no registration required

Participant Information

Each participant has:

ID - Unique identifier for session
Name - Display name (can be anonymous)
Cursor - Real-time cursor position
Selection - Currently selected objects
Viewport - Visible canvas area

Presence System

Real-time awareness features:

Cursor tracking - See where others are pointing
Selection indicators - Who is editing what
Typing indicators - Live collaboration feedback
Viewport awareness - See who is viewing which area

Participant Management

Host capabilities:

View all connected participants
Set view-only mode for individuals
Remove disruptive participants
Assign to Zones or Frames

Real-time Events

BoardAPI uses WebSocket for instant updates across all connected participants.

Event Types

Board Events

board:snapshot - Full state sync for new participants
board:updated - Incremental updates

Object Events

object:create - New object created
object:update - Object modified (position, data)
object:delete - Object removed

Participant Events

participant:joined - New participant connected
participant:left - Participant disconnected
cursor:move - Cursor position update

Frame Events

frame:create - New frame created
frame:navigate - Host navigated to frame
frame:lock - Lock mode changed

Zone Events

zone:create - Zone created
zone:assign - Participant assigned to zone
zone:violation - Edit attempt in wrong zone

Event Flow

1. User action (e.g., create object)
   ↓
2. Frontend sends WebSocket event
   ↓
3. Backend validates and persists
   ↓
4. Backend broadcasts to room
   ↓
5. Other clients receive and update UI

Connection Architecture

BoardAPI uses a hybrid WebSocket architecture:

Single Socket.IO connection for efficiency
Yjs CRDT for conflict-free state sync
Custom events for ephemeral data (cursors, presence)

Benefits:

Low latency (< 100ms p95)
Auto-reconnect with buffering
Optimized for mobile (battery, reliability)
Multiplexed - one connection for everything

Offline Behavior

When connection is lost:

UI shows "Connection lost" indicator
Changes are buffered locally (max 30 seconds)
Auto-reconnect with exponential backoff
Buffered changes sync on reconnect

Custom Components

External Components SDK enables developers to create custom interactive elements that embed in boards.

What are Components?

Components are iframe-embedded applications with:

Custom UI and behavior
Shared state across participants (CRDT-like sync)
Access to board context (frames, participants, quota)
Sandbox security

Component vs Object Type

Feature	Object Type	Component
Rendering	Server-defined template	Custom iframe UI
Interactivity	Limited	Full JavaScript
State Management	customData only	Shared storage + local
Use Case	Simple data cards	Complex apps (quiz, poker)

SDK API Modules

Components access platform features via board.* API:

Core APIs

board.storage - Shared state with auto-sync
board.props - Component settings
board.participants - Participant info and presence

Advanced APIs

board.context - Frame/Zone awareness
board.quota - Check limits before actions
board.backend - Proxy API calls (hide secrets)
board.webhooks - External integrations

Example: Planning Poker

typescript

// Component uses Shared State
await board.storage.set('myVote', 5);

// Subscribe to reveals
board.storage.subscribe('revealed', (isRevealed) => {
  if (isRevealed) showAllVotes();
});

// Check quota before upload
const canUpload = await board.quota.canUpload();

Development Workflow

Create - Use CLI: boardapi create my-component
Develop - Local simulator with hot reload
Test - Testing utilities and mock board
Publish - Deploy to your CDN
Register - Add to BoardAPI catalog

Learn more in Components Documentation.

AI Agents

Autonomous AI agents that react to board events and take actions without explicit user requests.

What are Agents?

Agents are event-driven automations powered by LLM decision-making:

Listen to board events (object created, participant joined, etc.)
Analyze context using GPT
Act automatically (send message, create object, move participant)

Agent Architecture

Event occurs (e.g., zone violation)
  ↓
Event Router → matching agents
  ↓
LLM Decision Engine → analyze context
  ↓
Action Executor → perform action
  ↓
Result broadcast to participants

Agent Actions

Communication

send_message - Send message to participant
broadcast_announcement - Notify all participants

Content

create_object - Add object to board
update_object - Modify existing object
delete_object - Remove object

Navigation

move_participant - Send participant to frame
lock_board - Change lock mode

Gamification

award_points - Give points to participant
set_timer - Start countdown timer

Agent Presets

Ready-to-use templates:

AI Tutor

Monitors student progress
Generates hints on request
Provides contextual help

Moderator

Watches for rule violations
Sends warnings
Maintains order in exams

Timer

Manages activity time limits
Auto-advances frames
Sends time warnings

Use Cases

Automated Teaching Assistant - Help students in real-time
Exam Monitoring - Detect suspicious behavior
Content Generation - Create practice problems on demand
Progress Tracking - Move students to next activity when ready

Learn more in AI Agents Documentation.

How Concepts Work Together

BoardAPI's power comes from combining these concepts:

Example: Interactive Vocabulary Lesson

Board - Create lesson canvas
Frames - One frame per activity (introduction, practice, quiz)
Object Types - Register "vocabulary-card" type
Objects - Create cards with word/translation in customData
Zones - Each student gets practice zone
Participants - Students join via link
Real-time Events - Cards sync instantly
Components - Quiz component for assessment
AI Agent - Tutor provides hints when students struggle

This creates a rich, interactive learning experience impossible with standalone tools.

Next Steps

Quick Start Guide - Build your first board
API Reference - Complete REST and WebSocket API
Components SDK - Create custom components
Use Cases - Real-world examples

Core Concepts ​

Boards ​

Board Lifecycle ​

Board Identity ​

Board State ​

Access Control ​

Objects ​

Object Types ​

Object Structure ​

Custom Data ​

Object Operations ​

Frames ​

What are Frames? ​

Lock Modes ​

Frame Navigation ​

Use Cases ​

Zones ​

What are Zones? ​

Zone Features ​

Zone vs Frame ​

Use Cases ​

Participants ​

Participant Roles ​

Participant Information ​

Presence System ​

Participant Management ​

Real-time Events ​

Event Types ​

Event Flow ​

Connection Architecture ​

Offline Behavior ​

Custom Components ​

What are Components? ​

Component vs Object Type ​

SDK API Modules ​

Example: Planning Poker ​

Development Workflow ​

AI Agents ​

What are Agents? ​

Agent Architecture ​

Agent Actions ​

Agent Presets ​

Use Cases ​

How Concepts Work Together ​

Example: Interactive Vocabulary Lesson ​

Next Steps ​

Core Concepts

Boards

Board Lifecycle

Board Identity

Board State

Access Control

Objects

Object Types

Object Structure

Custom Data

Object Operations

Frames

What are Frames?

Lock Modes

Frame Navigation

Use Cases

Zones

What are Zones?

Zone Features

Zone vs Frame

Use Cases

Participants

Participant Roles

Participant Information

Presence System

Participant Management

Real-time Events

Event Types

Event Flow

Connection Architecture

Offline Behavior

Custom Components

What are Components?

Component vs Object Type

SDK API Modules

Example: Planning Poker

Development Workflow

AI Agents

What are Agents?

Agent Architecture

Agent Actions

Agent Presets

Use Cases

How Concepts Work Together

Example: Interactive Vocabulary Lesson

Next Steps