Skip to main content

Key Concepts

Understanding the core entities and how they relate to each other.

Data Model​

Organization​

The tenant root. Every entity in SpaceOS belongs to an organization. An organization represents a company, coworking space, or building operator.

  • Organizations are isolated from each other (multi-tenant)
  • Each org has its own users, roles, spaces, and settings
  • Identified by a unique ID and a human-readable slug

Space Group​

A logical grouping of meeting spaces. Typically represents a physical location (a building, a floor, or a campus).

  • Carries timezone and address information
  • Contains one or more meeting spaces
  • Used for grouping availability views

Meeting Space (Virtual Space)​

A reservable inventory unit in ZenCore. This is the virtual representation of a bookable room, desk, or pod.

  • Has capacity, amenities, pricing rules, and availability windows
  • Linked to a physical space in ZenEdge via Physical Space Mappings
  • Supports dynamic pricing, business hours, and unavailability periods

Physical Space​

A physical location managed by ZenEdge. Represents the actual room or pod with its devices (locks, displays, sensors).

  • Linked to a virtual Meeting Space via a mapping
  • Contains adapters for IoT devices
  • Has its own device health monitoring

Booking​

A reservation for a meeting space during a time window.

  • Lifecycle: pending → confirmed → active → completed (or cancelled)
  • Triggers device automation (lock access, Wi-Fi vouchers) via webhooks
  • Supports payments, refunds, and voucher redemptions

Adapter​

A bridge between SpaceOS and a physical device (smart lock, Wi-Fi hotspot, fan, light). Each adapter translates the device's native protocol into the SpaceOS adapter contract.

  • One adapter = one device
  • Supports capability discovery, health monitoring, and action execution
  • Classified by criticality tiers: CRITICAL, STANDARD, OPTIONAL

Device Criticality Tiers​

TierMeaningFailure behavior
CRITICALEssential for the booking (e.g., door lock)Booking access may fail; retry with grace period
STANDARDImportant but not blocking (e.g., Wi-Fi)Booking proceeds; user notified of degraded service
OPTIONALNice to have (e.g., ambient lighting)Silently degraded

Webhook​

An outbound event subscription. Organizations register webhook endpoints to receive real-time notifications about booking events, device status changes, and more.

  • HMAC-SHA256 signed payloads
  • Automatic retry with exponential backoff
  • Delivery tracking and logs

Next Steps​