Reserve rooms and handle recurring local times

Application background

An employee chooses a room and meeting time in an office calendar. The application shows availability, then saves the reservation. The displayed result can become old before the employee clicks Confirm because another organizer may reserve the room first.

Time zones add another problem. A meeting repeated at 09:00 London time should follow London's clock when daylight-saving time changes, even though its UTC time may change.

Example walkthrough

The final reservation operation must check and save together. A previous availability search is useful information, but it cannot guarantee the room is still free.

Your assignment

Deliver: Build room search and reservation operations that cannot accept overlapping bookings. Define and demonstrate how recurring meetings behave across clock changes.

Required behavior: POST /rooms/{id}/bookings accepts an interval and request ID. Conflicting room occupancy returns 409. GET /availability is advisory. The booking transaction decides whether the interval is still available.

The required first milestone is a working local implementation of the behavior above. The numbered implementation steps define the scope. The cloud architecture is a later extension, not something the starter has already provisioned.

Get the code and run the supplied example

The code is in the public junior-to-staff repository. Install Git and Python 3.12+. No AWS account or Python packages are required for this first run. If you already have a checkout, use it and skip cloning.

git clone https://github.com/Soulful-Iris/junior-to-staff.git
cd junior-to-staff
python3 examples/architecture-starts/calendar_availability.py

Supplied file: examples/architecture-starts/calendar_availability.py. You can also read or download the source here (download file, source below).

"""Local mechanism demonstration for calendar-availability. No AWS resources are created."""
bookings=[]
def reserve(start,end):
    if end<=start: return '400 invalid interval'
    if any(start<b and a<end for a,b in bookings): return '409 room occupied'
    bookings.append((start,end)); return '201 reserved'
for interval in [(600,660),(630,690),(660,720)]:
    print(interval,reserve(*interval))
print('Minutes from midnight:',bookings)

This program is a mechanism demonstration: it runs the small scenario in one process and prints the result. It is not an HTTP service, a complete application, or an AWS deployment. A successful run demonstrates this mechanism only. It does not establish the workload or failure guarantees of the application you will build.

Example output from the supplied run:

Generated IDs and timestamps may differ. Compare the state transitions and outcomes.

(600, 660) 201 reserved
(630, 690) 409 room occupied
(660, 720) 201 reserved
Minutes from midnight: [(600, 660), (660, 720)]

Set up your implementation workspace

Create work/calendar-availability/ in your checkout (or use a separate repository). Copy the supplied mechanism into that directory as mechanism.py, then extract its state transitions into functions you can call from your implementation. The record and module names below describe what you must implement. They are not a promise that files with those names already exist. Keep a README.md beside your implementation with its exact run commands and observed results.

Local components and state to implement

This table names the records, interfaces or decision inputs for your deliverable. Unless a name is explicitly linked to supplied source above, it is something you create. Implement the local state transitions first, then connect the HTTP, storage or worker boundaries required by the steps.

Implement the assignment

1. Implement one room first

Store UTC instants and require end after start. In PostgreSQL, use a GiST exclusion constraint combining room equality with overlapping tstzrange values. Enable btree_gist where required. A SELECT availability followed by an unconstrained INSERT can double-book under concurrency.

2. Add recurrence without losing local intent

Keep the IANA timezone, local recurrence rule and occurrence exceptions. For this exercise skip nonexistent local times and choose the earlier instant for ambiguous times. Display that policy. Recompute future materialized occurrences after rule edits under a series revision.

3. Separate browsing from committing

Cache availability briefly with an as-of timestamp. On submit, recheck through the authoritative constraint. Preserve the organizer’s proposed time when returning a conflict, and offer a fresh availability read.

4. Handle series edits and cancellation

Change only the explicitly chosen occurrence or future series segment. Use stable occurrence IDs and transactionally update occupancy. Notify attendees asynchronously from an outbox. A failed email must not roll back an already reserved room.

Demonstrate the completed local result

Handoff: In your implementation README, include the start command, one successful operation, the failure case above and the resulting stored state or decision. State which dependencies are simulated. Someone with a fresh checkout should be able to reproduce this without your chat history.

Workload assumptions and capacity decisions

These are constructed exercise assumptions. The stated workload is a design target. The local demonstration does not establish that throughput. Use the estimation constants to check units before choosing capacity.

Map the local implementation to AWS

Deployment status: local only. Running the supplied command creates no AWS resources and configures no cloud connections. The diagram is a proposed deployment of the completed application. Each box needs either a deployed runtime, a provisioned service or an explicitly external dependency.

Read the diagram by following the arrows from the entry point: application code accepts the request or event, the state owner commits it, and any worker produces the later result. The table ties those roles to code and adapter work. Multiple boxes do not imply multiple Python files already exist.

A relational occupancy constraint fits interval exclusion directly. DynamoDB conditional puts alone do not prevent arbitrary overlapping intervals without an additional serialized room-calendar design.

Provision resources, then connect the application

Use one disposable AWS environment for the cloud exercise. Put the named resources in infra/template.yaml or your existing IaC tool, pass resource IDs through configuration, and scope each runtime role to its own tables, buckets and queues. The diagram is a design to implement. It is not a claim that these resources have been deployed. Record the commands you used to deploy and remove the exercise resources.

For concrete provisioning commands, configuration wiring and cleanup, use the AWS foundation guide. It includes a deployable table/queue/object-storage foundation and explains which application and service adapters you still implement.

A provisioned queue or table does not make the local program use it. Configure resource IDs in the deployed runtime, replace the local adapter, and replay the same successful and failing operation against that runtime. Record the deployed commit and observable result, then remove the disposable resources using your infrastructure tool.

Extend the design after the baseline works

Worked follow-up: Reserve three rooms as one booking

The organizer should not receive a successful meeting with only two rooms. Independent availability checks are stale as soon as another organizer reserves a room.

Revised architecture. Follow the changed responsibility and failure path below. This is a design to implement. The supplied local example does not provision these components.

What to implement. For rooms in one relational store, acquire room locks in a stable ID order and enforce interval exclusion inside one transaction. Insert the meeting and all reservations together. Roll back the entire transaction if any room conflicts. Use an outbox for invitations after the booking is saved. If rooms belong to independent providers, use expiring holds and a visible pending booking, then compensate partial holds. That alternative has a different user contract.

Walk through the result. Request R1, R2 and R3 for 09:00–10:00 while R2 is already occupied. The result is a conflict and no new reservation for R1 or R3. Compare that with the external-provider variant, where the user sees pending until all holds are confirmed. Hand over both the transaction boundary and cancellation behavior.

Add a meeting requiring three rooms atomically. Compare a database transaction spanning all room constraints with independent reservations and compensation. Explain what the organizer sees if only two rooms can be acquired.

CREATE EXTENSION IF NOT EXISTS btree_gist;
CREATE TABLE room_booking (
  booking_id text PRIMARY KEY, room_id text NOT NULL,
  starts_at timestamptz NOT NULL, ends_at timestamptz NOT NULL,
  cancelled boolean NOT NULL DEFAULT false,
  CHECK (starts_at < ends_at),
  EXCLUDE USING gist (room_id WITH =,
    tstzrange(starts_at, ends_at, '[)') WITH &&)
    WHERE (NOT cancelled)
);