Architecture
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:
- what exists: venues, resources, offerings, opening hours, prices, policies;
- what is free;
- atomic reservation.
Its contract:
- Every mutating method is atomic: it fully succeeds, or throws without side effects.
-
createHoldreserves capacity exclusively untilexpires_at. Two overlapping holds for the same capacity must never both succeed. -
Expired holds stop blocking inventory. Report them as
expired. -
Business failures throw
BookingErrorwith a specific code. Anything else is reported to agents as a retryableprovider_error.
The BookingService owns the agent-safety
rules:
-
Validation. Zod at the boundary. Failures become a
validation_errorthat lists every bad field. -
Idempotency.
-
Every mutating call needs an
idempotency_key. Same key and same request replays the result; same key and a different request isidempotency_conflict. -
Concurrent calls with the same key share one execution. The
in-flight entry is registered synchronously, before any
await. - Only successes are stored, because failed calls changed nothing.
- Replays return the current state of the booking.
-
Every mutating call needs an
-
Hold TTL. The engine computes
expires_at; every hold response carries it. Reads present a past-expiry hold asexpiredeven if the provider hasn't swept it yet. -
Expiry events. Nothing runs when a hold lapses, so
the engine announces it (
booking.expired, operationexpire) when something first notices: any read of the booking, orservice.sweepExpired(), which a cron or timer should call so lapses nobody reads are still reported. A claim per booking (expiryClaims; hosted andPostgresNotificationLoguse the email dedupe table) makes it at-most-once across instances. A crash between claim and delivery loses the event rather than repeating it. A hold confirmed or cancelled in time never emits. The event has no actor. -
Consent.
confirmrequiresuser_confirmed === true, as does cancelling a confirmed booking. Releasing a hold doesn't need it. -
Prerequisites.
- Customer details (name plus email or phone) are required before confirmation.
-
A
payment_tokenis required when a deposit is due at confirmation.
-
Cancellation rules. The pure function
evaluateCancellation():- free before
free_cancellation_until; -
the late fee after that (for
non_refundable, the paid deposit is retained); - not cancellable online once the booking has started.
The provider just records the computed fee and refund.
- free before
- State idempotency. Confirming an already-confirmed booking returns it, even with a fresh key. Cancelling an already-cancelled booking is a no-op. An agent that loses a response and retries with a new key therefore still can't double-book or double-charge.
-
Events.
onEventfires after every operation (operation, ok, booking id, status, error code, replayed). The demo logs it; the bench counts with it.
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 #
-
Few tools, flat inputs. Seven tools, and
party_sizeis an integer. Each tool description says what it does and does not do, e.g. "hold does NOT confirm". -
Responses tell the agent what to do. Every booking
response includes
next_step, and every error includessuggested_next_action. Holds carry bothexpires_atandexpires_in_seconds. -
Policy terms up front. Search results and holds
carry the cancellation policy (human-readable
descriptionplus structured fields) and the deposit terms before confirmation. -
Opaque slot ids. A
slot_idencodes everything needed to hold it, so the agent doesn't re-send dates and times and can't get them wrong.
Scaling beyond the demo #
-
Postgres.
@openbooking-sh/postgresmakes everything durable and safe across instances.PostgresBookingStorereserves under a transaction-scoped advisory lock per venue resource (check overlap, then insert), so overlapping holds can never both commit. Updates take the same lock, and a confirm that turns blocking re-checks for overlaps: a late confirm whose hold lapsed and was re-booked fails withhold_expiredinstead of double-booking. Expiry is applied on read, so no sweeper job is needed. Runmigrate(db)on start (idempotent, lock-serialised). -
Idempotency store.
PostgresIdempotencyStore(or your ownIdempotencyStoreon Redis/SQL) asserviceOptions.idempotencyStore. Two simultaneous first calls with one key run once, also across instances: the first to claim the key (an optionalclaim()/release()on the store; the Postgres store has them) runs, and the other waits for its result and replays it. A claim that is never finished, because its instance died, expires after 60 seconds. A store withoutclaim()still joins calls per process only, so across instances both can run (inventory stays safe through the atomic store, and the later record wins). -
USP state. The USP adapter
(
@openbooking-sh/adapter-usp, in progress) remembers who owns each hold, booking credentials (by hash), proofs it has already seen, and what request eachIdempotency-Keywas first used for. In memory by default, which is fine for one process. With more than one instance (serverless), passpostgresStores(db).uspascreateUspRouter({ state }): otherwise a credential issued by one instance is unknown to the others and a replayed proof is caught by only one. Each check-and-record is one atomic statement, so two instances racing on the same proof or key cannot both win. -
Clock. Inject a
Clockfor tests and simulations (ManualClock, the bench'sOffsetClock). -
MCP.
createMcpHandleris stateless, so any instance can serve any request. SetallowedHoststo your public hostnames.
Development notes #
-
Source-first packages. Each package's
exportshas a custom@openbooking/sourcecondition that points atsrc/index.ts.tsc(customConditions), vitest (resolve.conditions) andtsx --conditionsall use it, sopnpm dev,pnpm testandpnpm typecheckneed no build. Published consumers getdist/. -
Build.
tsupbuilds ESM plus.d.tsper package. -
Tests.
-
Unit tests per package live in
packages/*/test. -
The end-to-end MCP test in
packages/server/testdrives the full Hono app with a real MCP client, in-process, on both protocol eras. - The bench smoke test runs every task with the scripted driver.
-
Unit tests per package live in
This page is generated from
docs/ARCHITECTURE.md
in the open-source repository. To fix something, change it there.