Shiftboard: Build an AI-Powered App on RaisinDB

This tutorial installs and walks through Shiftboard, a complete working app. A cafe manager plans weekend shifts on a live board and chats with an AI agent that reads and updates the same data through tools. On request the agent coordinates with the staff directly, or starts a durable workflow that does the coordination for it.

Everything in this tutorial is a real, running example. The full source lives in the RaisinDB repository under examples/shiftboard/.

What you'll build

• A weekend shift board. Shifts and staff are plain nodes in a staffing workspace, installed from a package.
• An AI planning agent (/agents/shift-planner) that chats with the manager, calls tool functions (list-shifts, assign-shift, and others), and updates the board you are looking at.
• A server-side rendered SvelteKit frontend with cookie auth, a live board over WebSocket node subscriptions, and inbox notifications.
• Agent-to-staff coordination over chat. The agent asks staff members themselves, handles declines, and assigns only after someone confirms.
• The same coordination as a durable workflow: inbox approval tasks with accept and decline buttons, deadlines, and a full audit trail, started by the agent on request.
• A plan-driven coordinator that fills the whole board in one request. It proposes an approvable plan with one task per open shift, and each approved task starts a workflow.

Chat, board, notifications, and human tasks are all nodes and node events. That is the whole architectural idea, and you will see it pay off in every part.

Prerequisites

• A running RaisinDB server, local (raisindb server start) or remote. The tutorial works identically against both. The example's scripts default to http://localhost:8081; adjust the URL to your server.
• The raisindb CLI (Node 20+): npm install -g @raisindb/cli
• Node.js 20+ for the frontend and test scripts.
• An AI provider API key for Parts 2, 4 and 6. The example agents use Groq (llama-3.3-70b-versatile), so a Groq key is the fastest path. Any configured provider works; see AI Provider Configuration. Parts 1, 3 and 5 need no model at all.

Demo credentials

The tutorial uses demo-only accounts throughout: manager planner@example.com / Planner12345!, staff anna@example.com and cara@example.com / Staff12345!. You register them yourself in Part 1. Do not reuse them anywhere real.

The parts

The tutorial is progressive: data and CLI basics first, then chat and tools, then the app, then multi-user coordination, then durable workflows, and finally plans, which compose everything that came before.

Part	What you'll do
1. Install the app with the CLI	Log in, create a repo, configure the AI provider, deploy the package, register users. Local or remote, scriptable for CI
2. Chat with the agent + tools that act	The agent definition, tool functions with JSON schemas, the two SQL result shapes, token accounting
3. A real app: SSR, live board, inbox notifications	SvelteKit SSR over HTTP, WebSocket node subscriptions, the notification bell, the live dev loop
4. The agent coordinates your staff	The agent messages real staff users, handles a decline, assigns on confirmation, and where chat-only coordination reaches its limit
5. Same scenario as a durable workflow	The /flows/fill-shift flow, inbox tasks as nodes, the in-app task panel, and how the agent starts workflows
6. The Planner: plans and workflows composed	A plan-enabled agent fills the whole board: approvable plan, one workflow per task, the board filling live, and what "completed" means