Skip to content

Access Control

This guide explains how Metrognome's access control system works—from when a customer books a studio to when they walk through the door. Understanding the full picture helps when troubleshooting issues or setting up new locations.

The Big Picture

When someone books a studio, the system needs to let them in at the right time and keep them out otherwise. Here's how the pieces connect:

Customer books Studio A
        ↓
System finds their access code (or creates one)
        ↓
System finds all doors that control access to Studio A
        ↓
Background jobs program the code into those locks
        ↓
Customer arrives, enters code, door unlocks
        ↓
Reservation ends, code is removed from locks

This happens automatically. Staff rarely need to intervene unless something goes wrong.

Core Concepts

Access Codes

Every customer has a personal access code—a 6-digit PIN they use at door keypads. The system creates this code automatically when they first book.

Key points:

  • One code per customer, reused across all their reservations
  • Codes are only programmed into locks during reservation windows
  • Customers see their code in confirmation emails and in the app (starting 15 minutes before)

→ Managing Access Codes

Access Gates

Access gates are the configuration layer connecting physical locks to studios. When you create an access gate, you're telling the system "this lock device controls access to this resource."

Key points:

  • Each physical door lock needs a corresponding access gate record
  • Gates can control a single studio (resource scope) or an entire area (resource group scope)
  • Gates are vendor-specific—Schlage, UniFi, or manual keypads

→ Managing Access Gates

Resource Groups

Resource groups organize studios by physical location—wings, floors, entry points. They're used to scope access gates that control multiple resources.

Example: The "Red Wing Entry" door controls access to all studios in the Red Wing. Instead of creating separate gates for each studio, you:

  1. Create a resource group called "Red Wing"
  2. Add all Red Wing studios to that group
  3. Create one access gate scoped to the "Red Wing" group

Now anyone booking any Red Wing studio automatically gets access through the Red Wing entry door.

→ Managing Resource Groups

How It Works: Step by Step

When a Reservation is Created

  1. Find or create the customer's access code
  2. If they already have a code, use it

  3. If not, generate a new random 6-digit code

  4. Find all applicable access gates

  5. Gates directly scoped to this resource

  6. Gates scoped to resource groups that contain this resource

  7. Schedule code provisioning jobs

  8. One background job per access gate
  9. Jobs run 15 minutes before the reservation starts
  10. Each job programs the code into the physical lock

During the Reservation

The customer's code works on all programmed locks. They can enter and exit freely during their reservation window.

When a Reservation Ends

  1. Code removal jobs trigger (1 minute before end time)
  2. Each lock removes the code
  3. Customer can no longer enter using that code at those specific locks

Their personal code still exists—it just isn't programmed into any locks until their next reservation.

When a Reservation is Cancelled

  1. All pending code jobs are cancelled (if not yet run)
  2. Code deletion jobs are created for any codes already programmed
  3. Locks remove the code immediately

Lock Vendors

Metrognome integrates with three types of door hardware:

Schlage

Smart locks typically used on individual studio doors.

  • Connected via Schlage's cloud service
  • Supports 4-8 digit codes
  • Each lock stores codes locally
  • Battery-powered with status monitoring

UniFi (Ubiquiti)

Enterprise access control for main entries and common areas.

  • Connected to local UniFi Access controller
  • Manages users, schedules, and access policies
  • Supports door groups for coordinated access
  • Shows real-time door status (open/closed, battery level)

Manual

Standard keypads without smart lock integration.

  • No automatic code programming
  • Uses a static code configured on the access gate
  • Code shown in confirmation emails but not provisioned
  • Used for analog locks or backup entry points

Monthly Lockouts vs Hourly Reservations

The access control flow differs slightly for monthly subscriptions:

Hourly reservations:

  • Code programmed → reservation starts → reservation ends → code removed
  • Access is time-limited to the reservation window

Monthly lockouts:

  • Code stays programmed as long as the subscription is active
  • Customer added to "members group" in UniFi for persistent entry access
  • When subscription ends, code removed and membership revoked

What Staff Can Manage

Task Where When to Use
View/regenerate a customer's code User detail page Customer forgot code or needs a new one
Create/edit access gates Staff → Access Gates Setting up new locks or changing scope
Monitor lock status Staff → Lock Devices Checking if hardware is online
Manage resource groups Staff → Resource Groups Organizing studios by area for access control

Troubleshooting

Customer can't get in

  1. Check their access code — Is it active? (User detail page → Access Code section)
  2. Check the reservation — Is it during the reservation window? Codes only work during booked times.
  3. Check the locks — Are they online? (Staff → Lock Devices)
  4. Check the access gates — Is the gate active? Does it have the correct device ID?

Code shows as "Pending"

The background job to program the code hasn't run yet. Jobs run 15 minutes before reservation start. If it's past that time and still pending, check Admin → Background Jobs for failed jobs.

Lock shows "Not configured"

The physical lock exists but isn't connected to a resource. Create an access gate with the correct device ID to link it.

Customer needs different access

If they need access to additional doors:

  • For a different studio: They need a reservation for that studio
  • For a shared area: Ensure the resource group and access gate are configured correctly
  • For extended hours: Modify the reservation times

Architecture Overview

For technical staff, here's how the system components connect:

┌─────────────────────────────────────────────────────────────────┐
│                        Reservation Created                       │
└─────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                     SecurityService                              │
│  - Gets/creates user's AccessCode                                │
│  - Finds applicable AccessGates via AccessGateService            │
│  - Enqueues background jobs via JobQueueService                  │
└─────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                    BackgroundJob Queue                           │
│  - Jobs scheduled for 15 min before reservation start            │
│  - Each job targets one access gate                              │
│  - Jobs retry on failure (up to 5 times)                         │
└─────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                  AccessCodeJobHandler                            │
│  - Routes to correct provider based on vendor                    │
│  - Handles CREATE and DELETE operations                          │
│  - Schedules auto-deletion jobs on CREATE                        │
└─────────────────────────────────────────────────────────────────┘
                    │                           │
                    ▼                           ▼
     ┌──────────────────────┐     ┌──────────────────────┐
     │   SchlageProvider    │     │    UnifiProvider     │
     │   (Railway service)  │     │   (UniFi Access)     │
     └──────────────────────┘     └──────────────────────┘
                    │                           │
                    ▼                           ▼
              Physical Lock                Physical Lock