OpenBooking / Docs / Architecture
Guide

Architecture

Last updated 2026-11-06 · Edit on GitHub

            AI agents / platforms
   ┌──────────────┬───────────────┬──────────────┐
   │ MCP client   │ UCP platform  │ A2A client   │
   └──────┬───────┴───────┬───────┴──────┬───────┘
          │ /mcp          │ /ucp/*       │ /a2a  (+ /.well-known/ucp, /.well-known/agent-card.json)
   ┌──────▼───────────────▼──────────────▼───────┐
   │ @openbooking-sh/server   (one Hono app)        │
   │  adapter-mcp   adapter-ucp   adapter-a2a    │  ← thin protocol translation
   └──────────────────────┬──────────────────────┘
                          │
   ┌──────────────────────▼──────────────────────┐
   │ @openbooking-sh/core  BookingService           │  ← agent-safety lives here, once
   │  validation · idempotency · hold TTL ·      │
   │  explicit consent · cancellation rules      │
   └──────────────────────┬──────────────────────┘
                          │ BookingProvider (the ONE interface you implement)
   ┌──────────────────────▼──────────────────────┐
   │ provider-memory | your POS / PMS / calendar │  ← inventory + persistence
   └─────────────────────────────────────────────┘

Packages #

Package Responsibility Depends on
@openbooking-sh/core Domain model (zod), BookingProvider, BookingService, errors, idempotency, cancellation rules, time-zone helpers zod
@openbooking-sh/provider-memory Configured provider (catalog + slot rules) on a pluggable BookingRecordStore; demo salon and restaurant core
@openbooking-sh/postgres Postgres stores: bookings/holds, idempotency, Studio activity, Cal.com records; migrate() core, provider-memory, studio, pg
@openbooking-sh/adapter-mcp Seven MCP tools, Streamable HTTP handler, stdio core, @modelcontextprotocol/server
@openbooking-sh/adapter-ucp UCP profile, booking-session REST, availability extension core, hono
@openbooking-sh/adapter-a2a Agent Card builder plus the SendMessage endpoint core
@openbooking-sh/server Mounts everything on one Hono app; listen() for Node all adapters, hono, @hono/node-server, @modelcontextprotocol/hono
examples/demo pnpm dev server, provider-memory
@openbooking-sh/booking-page Public booking page and its JSON API (zod schemas, OpenAPI 3.1), manage links, JSON-LD, WebMCP core, hono, zod
@openbooking-sh/client Typed fetch client for the booking page API; no dependencies, runs in browsers, edge and Node none
@openbooking-sh/react React BookingWidget and hooks on the client; React is a peer dependency client
@openbooking-sh/notifications Booking emails with .ics invites (Mailer: Resend, console, memory) core
@openbooking-sh/google-calendar Google OAuth, busy-time source, bookings → events core, provider-memory
@openbooking-sh/hosted Many businesses: accounts, settings → catalog, per-business runtime, the OpenBooking MCP app (find_business) all of the above
bench Agent-success benchmark server, provider-memory, MCP client

Who owns what #

The split matters. Every protocol must behave identically, and booking-system vendors should only have to think about inventory.

The provider (BookingProvider) owns:

Its contract:

  1. Every mutating method is atomic: it fully succeeds, or throws without side effects.
  2. createHold reserves capacity exclusively until expires_at. Two overlapping holds for the same capacity must never both succeed.
  3. Expired holds stop blocking inventory. Report them as expired.
  4. Business failures throw BookingError with a specific code. Anything else is reported to agents as a retryable provider_error.

The BookingService owns the agent-safety rules:

Adapters only translate. They never call the provider directly.

Lifecycle #

search_availability ──► slots (with price, deposit, cancellation policy; not reserved)
        │
hold_slot ─────────────► booking { status: held, expires_at }      ── TTL passes ──► expired
        │                       │
        │                  update (customer/notes)
        │                       │
confirm_booking(user_confirmed=true) ──► confirmed { confirmation_code }
        │
cancel_booking ────────► held: released (no fee)
                         confirmed: needs user_confirmed; fee/refund per policy ──► cancelled

The UCP status mapping is in SPEC-NOTES §1.5.

Agent-friendly design choices #

Scaling beyond the demo #

Development notes #

This page is generated from docs/ARCHITECTURE.md in the open-source repository. To fix something, change it there.