Getting Started

Core Concepts

← Back to Getting Started

Five concepts underlie every screen in the manual. Read this once; every other section assumes you know what these words mean.

Tenant

A tenant is one organisation using the platform. FlatsBratislava is one tenant. As the platform onboards new operators, each becomes a new tenant.

  • Tenants are isolated: data, settings, integrations, and users never cross a tenant boundary at the application layer.
  • Only superadmins can switch between tenants. Regular admins and operators only ever see one.
  • Each tenant has its own WhatsApp Cloud API number, Hospitable connection, Nuki account, and language defaults.

The tenant boundary is the most important security and data-integrity boundary in the system. If you ever see data from someone else's tenant, that's a bug — file it with the security label immediately.

Property

A property is one bookable unit — typically a flat or an apartment in a building. Properties belong to a tenant and have:

  • An address and photos
  • Check-in / check-out windows (checkInTime, checkOutTime — defaults the rules engine falls back to when a reservation doesn't override)
  • One or more Nuki smart locks (front door, apartment door, garage)
  • A guidebook PDF generated per reservation
  • Default pricing inputs for the revenue simulation

See Properties → Configuration for the full editor.

Reservation

A reservation is one stay — one guest (or guest party), one property, a check-in date, and a check-out date. Reservations arrive at the platform via webhook from a booking channel:

  • Hospitable (the primary source — channel-aggregates Airbnb, Booking.com, direct)
  • Beds24 (legacy, kept for migration tenants)
  • Direct API push (for direct bookings)

Each reservation has a canonical guest row in the guests table — that's where the per-stay PIN code, 2N intercom code, and guidebook personalisation live.

⚠ One reservation can produce multiple guest rows if the booking channel re-syncs. The system always picks the canonical row (the most-populated, most-recent). If you ever see a Send Check-in task blocked because "reservation.nukiAccessCode is_not_null" is false — and you've confirmed the PIN exists — that's the canonical-row picker doing its job (or a bug, see #260).

See Reservations for the list view and per-reservation actions.

Task

A task is one unit of work tied to one reservation. Tasks are not created by hand; they are generated by task templates (rules) that watch for reservation events:

Event Example task fired
reservation.created Schedule cleaning, Generate access code
reservation.checkin (~24h before) Send check-in instructions, Confirm arrival window
reservation.checkin (at time) Notify cleaner cleaning is overdue
reservation.checkout (~2h before) Send pre-checkout reminder
reservation.checkout (at time) Mark cleaning required, Request review

Each task has:

  • A name (human-readable, language-resolved)
  • An action (e.g. whatsapp.sendTemplate, nuki.generateCode, report.sendReply) — what fires when the task completes
  • An assignee (which role/teammate it goes to)
  • A due date/time
  • Zero or more checklist items — including optional auto-resolve conditions

Tasks are surfaced in three places: the Pulse dashboard (today's work), Operations → Tasks (full list, filterable), and WhatsApp (interactive button notifications). See Tasks for the full lifecycle.

Teammate

A teammate is one person who acts inside the tenant: an owner, host, cleaner, admin. Each teammate has:

  • A role (admin / host / cleaner / viewer)
  • A language (the default outbound language for messages they author or the AI ghost-writes for them)
  • A set of properties they're responsible for (optional — admins span all)
  • A Nuki access code generated by the platform (so they can enter properties on their days; auto-revoked when their role ends)
  • A WhatsApp phone number the system uses to route tasks to them

Teammates are managed under Team & Account — see Team & Access → Teammates.

⚠ Removing a teammate's access code does NOT yet always revoke the Nuki PIN — see issue #166 for the fix and current state.

How they connect

Tenant
 ├─ Properties
 │   └─ Nuki locks
 ├─ Teammates (cleaners, hosts, admins)
 │   └─ Per-teammate Nuki access codes
 └─ Reservations
     ├─ Guest (canonical row with per-stay PIN)
     └─ Tasks
         ├─ Generated by task templates
         ├─ Assigned to one teammate (role)
         └─ Fired through WhatsApp (button-driven)

Everything in the rest of the manual is a screen on top of this graph.

  • #260 — canonical-guest-row selection (5-duplicate-row bug).
  • #137 — NULL propertyName on reservation (data quality).
  • #166 — teammate access-code removal & Nuki revocation.
Source: the FlatsBratislava operator manual.