docs.zenspace.io
    docs.zenspace.io
    • 🧭 Introduction
    • 🧱 System Components
    • 🧰 Tech Stack
    • 🏗️ System Architecture
    • 🌐 Deployment Architecture
    • 🗄️ Database Design Documentation
    • API Endpoints
      • RaspberryPi
        • Heartbeat API
        • Retrieve all active sensors and device permissions
        • Control a device (e.g., turn on/off, adjust intensity)
        • Enable or disable a device
        • Register a meeting space ID and retrieve network details
      • Meeting Space
        • Schedule meeting space state
        • Get meeting spaces by customer
        • Get meeting space state by ID
        • Get meeting space state by device ID
        • Disable meeting space state
        • Send meeting space state by meeting space ID
        • Store meeting space availability
        • Create Google Calendar
      • Device Management
        • Create device
        • Create device sensors
        • Create or update admin unlock codes
        • Upload meeting space screenshot
      • Authentication
        • Create authorization token
      • Messaging
        • Send message to Android device
      • Booking
        • Send meeting space state by booking ID
        • Create or update booking

    🏗️ System Architecture

    The Workspace Management platform is built on a modular, event-driven architecture to manage SmartPods across various public venues. It blends real-time booking interfaces, IoT control, and serverless backend logic to ensure a seamless experience for both users and administrators.

    🔍 Overview#

    The system is divided into three key layers:
    1.
    Presentation Layer (UI Interfaces) – Admin portals, client booking site, meeting room displays
    2.
    Logic & Integration Layer (Backend) – AWS Lambda, API Gateway, EventBridge, Supabase
    3.
    Hardware Layer (IoT & Devices) – Raspberry Pi, relays, and electrical components inside each pod
    All layers communicate through secure REST APIs and push-based messaging (FCM), enabling smooth, asynchronous control across the system.

    🗂️ Key Architecture Modules#

    1. Frontend Interfaces#

    Booking Admin Portal: Manages global bookings, payments, and reports.
    Client Booking Portal: Allows users to search, reserve, and pay for SmartPods.
    Customer Admin Portal: Venue-level control over pod bookings and access control.
    Room Displays (Android): Touch interfaces outside and inside pods.
    Each frontend connects securely to AWS Lambda APIs and Supabase via HTTPS using JWT-based authentication.

    2. Backend (Serverless Core)#

    All business logic runs within AWS Lambda functions. These include:
    Booking validations and conflict resolution
    Command dispatch to Raspberry Pi via FCM
    Integration with Google Calendar
    Sending email notifications via AWS SES
    Scheduled operations like auto-cancellations and booking reminders are handled using AWS EventBridge.

    3. Database & Sync#

    Supabase is used for:
    User authentication
    Booking storage
    Session metadata
    Logs and analytics
    Real-time updates from Supabase power live booking status on displays and client portals.
    Google Calendar sync is bi-directional, managed by Lambda functions with token-based OAuth.

    4. IoT Control (Raspberry Pi + Hardware)#

    Each SmartPod includes a Raspberry Pi running Python/Django.
    The Pi receives control instructions (e.g., turn on fan/light) via FCM or Supabase poll.
    Pi sends electrical signals to relays connected to physical devices.
    Device health/status is reported back to Supabase and visualized in admin dashboards.

    🔁 Data & Command Flow#

    1.
    User books pod → Client Portal → Supabase
    2.
    Lambda receives trigger → Validates → Updates Supabase
    3.
    Command sent to Pi → via REST API
    4.
    Pi controls hardware → Updates booking status
    5.
    Displays update via Supabase

    📈 Architecture Diagram (Placeholder)#

    🖼️ Architecture Diagrams#

    1. 📌 Overall System Architecture#

    ZenSpace-Architecure.jpg

    2. 📌 Booking Flow#

    [Placeholder – Insert: Booking Flow Diagram]
    Covers flow from user booking → validation → payment → command dispatch to pod.

    3. 📌 Customer Pod Access Flow#

    [Placeholder – Insert: Customer Access Flow Diagram]
    Shows QR generation → scanning at pod → session start → device control inside.

    4. 📌 SmartPod Onboarding Flow#

    [Placeholder – Insert: SmartPod Onboarding Flow Diagram]
    Illustrates steps from adding new pod in portal → Pi setup → verification → availability.
    Previous
    🧰 Tech Stack
    Next
    🌐 Deployment Architecture
    Built with