SEER Booking Service (seer-booking)

Overview

The SEER Booking Service is a dedicated microservice for resource reservation management within the SEER platform. It handles scheduling, conflict detection, and availability queries for shared resources such as meeting rooms, zones, and devices.

Why a Separate Service

The existing task service does not cover:

• Conflict / overlap detection for shared resources
• Schedule status queries with time-range filtering
• Recurring booking management
• Available-slot computation
• Booking-specific policies (max duration, min notice, cancellation rules)

A dedicated booking service addresses these gaps cleanly without overloading the task service.

---

Key Capabilities

Capability	Description
Resource Registration	Register SEER zones or devices as bookable resources with operating hours and booking policies
Booking Lifecycle	Full lifecycle management: pending → confirmed → completed/cancelled, with check-in/check-out support
Conflict Detection	Application-level and PostgreSQL exclusion constraint enforcement to prevent overlapping bookings
Schedule Queries	Query bookings by date range and compute available time slots for a given resource
Recurring Bookings	iCal RRULE-based recurrence with parent/occurrence storage and series-level operations
Policy Enforcement	Configurable per-resource policies: max duration, advance booking limits, cancellation rules, grace periods
No-Show Detection	Automatic status transition to no_show when check-in grace period expires
Webhook Events	NATS-based event emission for all booking lifecycle transitions, consumed by seer-hook
Timezone Support	All times stored in UTC; IANA timezone conversion on display via query parameter

---

Bookable Resources

Resource Type	SEER Source Service	Identifier	Notes
Zone / Room	Device Management (/device/v1/)	zoneId	Meeting rooms, labs, shared spaces
Device	Device Management (/device/v1/devices)	deviceId	Shared sensors, equipment, cameras

The booking service does not duplicate zone/device data. It stores a reference (resourceType + resourceId) and fetches display details from the SEER device service on demand or via cache.

---

API Endpoints

Resource Management

POST   /booking/v1/resources
GET    /booking/v1/resources                ?workspace=&resourceType=&isActive=&page=&limit=
GET    /booking/v1/resources/:id
PATCH  /booking/v1/resources/:id
DELETE /booking/v1/resources/:id

GET    /booking/v1/resources/:id/schedule         ?from=ISO8601&to=ISO8601&tz=IANA
GET    /booking/v1/resources/:id/available-slots   ?date=YYYY-MM-DD&tz=IANA&slotMinutes=30

Booking Management

POST   /booking/v1/bookings
GET    /booking/v1/bookings                 ?workspace=&resourceId=&status=&bookerProfileId=&from=&to=&page=&limit=
GET    /booking/v1/bookings/:id
PATCH  /booking/v1/bookings/:id             (reschedule — subject to conflict check)
PATCH  /booking/v1/bookings/:id/confirm
PATCH  /booking/v1/bookings/:id/cancel      { reason? }
PATCH  /booking/v1/bookings/:id/checkin
PATCH  /booking/v1/bookings/:id/checkout

POST   /booking/v1/bookings/bulk            (create recurring series)
PATCH  /booking/v1/bookings/series/:parentId/cancel

Health Check

GET /booking/v1/health

---

IAM Permissions

Action	LV2 (WS Admin)	LV3 (Group Admin)	LV4 (User)	LV5 (Guest)
Register / manage resources	✅	✅	❌	❌
Create booking	✅	✅	✅	❌
View own bookings	✅	✅	✅	✅
View all bookings (workspace)	✅	✅	❌	❌
Cancel any booking	✅	✅	❌	❌
View schedule (resource)	✅	✅	✅	✅

---

Integration Points

System	Integration
Auth Service	JWT Bearer token validation via seer-nestjs JwtAuthGuard
Workspace IAM	Role-based access control using SEER LV1–LV5 permission hierarchy
Device Management	Resource validation on registration; metadata enrichment on display (cached 5 min)
Webhook System	NATS event emission for booking.create, booking.confirm, booking.cancel, booking.reminder, booking.no_show, booking.checkin, booking.checkout
Rule Engine	Webhook events can trigger SEER rules for alerts and automation

---

Booking Lifecycle

---

Tech Stack

Component	Technology
Framework	NestJS (Node.js)
ORM	TypeORM
Database	PostgreSQL (with tstzrange exclusion constraints)
Message Broker	NATS
Caching	Redis / SeerCacheService
Timezone	Luxon
Recurrence	rrule (iCal RRULE parsing)
Scheduling	@nestjs/schedule (cron jobs)

---

Related Documentation

• Booking Service Requirements — Full requirements specification
• OpenAPI Reference — Available at /booking/docs-yaml when the service is running