Seatsurfing

Seatsurfing is a self‑hosted booking and scheduling platform that exposes a robust REST API, coupled with two modern Progressive Web Apps (PWAs) for user self‑service and administrative tasks. The core engine is written in Go, leveraging its concurrency model to handle high‑volume booking requests while maintaining low latency. The frontends are built with TypeScript and React, sharing a common codebase that ensures consistent data models across the UI layers. This architecture enables developers to integrate Seatsurfing into existing workflows, expose custom endpoints, or embed the booking widget inside other applications.

Key Features

• Room & Seat Management – Create, update, and delete resources (desks, meeting rooms, flexible spaces) via the API or UI.
• Booking Lifecycle – Reservations support creation, modification, cancellation, and conflict detection with customizable rules (e.g., max duration, buffer times).
• Floor‑Plan Upload – Drag‑and‑drop layout editor that stores SVG/JSON maps, allowing spatial queries and proximity calculations.
• Multi‑tenant & Role‑Based Access – Organizations can be isolated, and fine‑grained permissions (admin, manager, user) are enforced at the API level.
• Integration Hooks – Webhooks for booking events, Microsoft Teams app, Atlassian Confluence connector, and an open API spec for third‑party extensions.

Technical Stack

The backend exposes a v1 REST API with hypermedia links (HAL) for discoverability. All data structures are defined in a shared TypeScript package (/pkg/common) which is compiled to JSON Schema for runtime validation. This guarantees type safety across the stack and simplifies client generation.

Core Capabilities & APIs

• Resource API – CRUD for seats, rooms, and spaces. Supports bulk import via CSV/JSON.
• Booking API – Endpoints for GET /bookings, POST /bookings, PUT /bookings/:id, and conflict resolution.
• Availability API – Query free slots for a resource or user over a time window, with optional filters (location, skill set).
• Webhook Registration – Clients can subscribe to events (booking.created, booking.updated, booking.cancelled) and receive signed payloads.
• WebSocket Stream – Real‑time updates for UI components, reducing polling overhead.

All endpoints are versioned and documented via OpenAPI 3.0, which can be introspected by tools such as Swagger UI or Postman.

Deployment & Infrastructure

Seatsurfing ships as a single Docker image (ghcr.io/seatsurfing/backend) that contains the Go server and static assets for both UIs. A minimal docker‑compose.yml is provided, but the image can be deployed on any container platform:

• Kubernetes – The repo includes a Helm chart that configures PostgreSQL as an external or in‑cluster deployment, secrets for CRYPT_KEY, and optional Ingress settings.
• Bare Metal / VM – Run the binary directly; environment variables control database URL, encryption key, and feature flags.
• Scalability – Horizontal scaling is achieved by running multiple backend replicas behind a load balancer. PostgreSQL handles concurrency via row‑level locking; the API uses connection pooling (pgx) to maintain throughput.

Because the UI is served from the same binary, no separate web server is required, simplifying deployment footprints.

Integration & Extensibility

Seatsurfing’s plugin architecture allows developers to extend functionality without modifying core code:

• Custom Middleware – Add request/response interceptors in Go to inject authentication tokens or audit logs.
• Webhook Consumers – Build microservices that react to booking events (e.g., send Slack notifications, update external calendars).
• UI Customization – Import the shared TypeScript package into a custom React app to reuse components and API clients.
• External Data Sources – The API supports OAuth2 authentication, enabling integration with corporate identity providers or SSO solutions.

The platform also exposes a GraphQL shim (experimental) for developers preferring query‑based data fetching.

Developer Experience

• Configuration – All runtime settings are driven by environment variables (POSTGRES_URL, CRYPT_KEY, INIT_ORG_USER, etc.). The docs provide a comprehensive reference.
• Documentation – Live API docs (Swagger UI) are auto‑generated from OpenAPI specs. The public website hosts a full developer guide with code snippets in Go, Python, and JavaScript.
• Community & Support – The project is open source under GPL 3.0, with an active issue tracker and Slack channel for real‑time help.
• Testing – The repo contains unit, integration