Classlane

Adaptive Hold

Dynamically adjusts the two‑minute hold window based on time-to-class and historical response speed. Near start time, holds shorten to fill seats faster; with more lead time, holds lengthen to give students a fair chance. Instructors keep momentum without micromanaging timers, boosting last‑minute conversions while staying student-friendly.

Requirements

Adaptive Hold Duration Engine

"As an instructor, I want the hold time to adjust automatically based on how soon class starts and how quickly my students usually respond so that seats fill faster without me tweaking timers."

Description

Implements a rules-and-model-based service that calculates the hold window per waitlist notification using two primary signals: time-to-class start and historical student response latency. Near start time, the engine shortens holds to accelerate backfill; with more lead time, it lengthens holds to improve fairness. Provides configurable global and per-class min/max caps, real-time recalculation on seat release and class state changes, and a safe default of 120 seconds when data is sparse or errors occur. Exposes a versioned API consumed by the waitlist and booking flows, supports caching and rate limiting, and logs inputs/outputs for auditability. Ensures deterministic behavior across devices and channels while reducing instructor micromanagement and improving last‑minute conversions.

Acceptance Criteria

Dynamic Hold by Time-to-Class

Given two notifications with identical inputs except time-to-class t1 < t2 When the engine calculates hold durations Then hold(t1) <= hold(t2) Given time-to-class <= configured_near_start_threshold and all inputs are valid When the engine calculates the hold duration Then the duration is strictly less than 120 seconds unless constrained by the minimum cap Given time-to-class >= configured_far_start_threshold and all inputs are valid When the engine calculates the hold duration Then the duration is greater than or equal to 120 seconds unless constrained by the maximum cap

Adjustment by Historical Response Latency

Given two students with historical median response latencies L1 < L2 and identical other inputs When the engine calculates the hold duration Then hold_for_L1 <= hold_for_L2 Given insufficient or no historical response latency for the notified student When the engine calculates the hold duration Then the latency signal is omitted from the calculation and the result is derived from time-to-class and caps only Given historical latency data is available When the engine calculates the hold duration Then the resulting duration is within the effective [min_cap, max_cap] bounds

Min/Max Caps Configuration and Enforcement

Given global min_cap and max_cap are configured When the engine calculates the hold duration Then the output is within [global_min_cap, global_max_cap] Given per-class caps are configured for a class When the engine calculates the hold duration for that class Then per-class caps take precedence over global caps and the output is within [class_min_cap, class_max_cap] Given a misconfiguration where an effective min_cap exceeds the effective max_cap When the engine calculates the hold duration Then it returns 120 seconds and logs a configuration_error reason

Safe Default and Error Handling

Given both primary signals (time-to-class and historical response latency) are unavailable or invalid for a request When the engine calculates the hold duration Then it returns 120 seconds Given any unrecovered runtime error, dependency timeout, or model failure occurs during calculation When the engine calculates the hold duration Then it returns 120 seconds Given the engine returns the safe default When writing audit logs Then the log contains a reason code indicating default_applied with the triggering condition

Real-time Recalculation on Seat and State Changes

Given a seat is released for a class with an active waitlist When the next hold duration is requested for that waitlist Then the engine recomputes using current inputs rather than serving a stale cached value Given a class start time or status changes (e.g., updated start time, moved to Starting/In Progress) When a new hold duration is requested Then any cached value is invalidated and a new duration is produced consistent with the updated time-to-class Given an active hold offer has already been sent to a student When class state changes Then the engine does not retroactively alter the already-committed hold duration for that offer

Versioned API Contract and Determinism

Given a request to a supported versioned endpoint (e.g., /v{n}/hold-duration) When submitted with identical inputs across devices or channels Then the engine returns the same duration for the same engine version Given a request to an unsupported API version When submitted Then the engine responds with a version_not_supported error (e.g., HTTP 404) and does not perform a calculation Given any client-provided timestamps When calculating time-to-class Then the engine derives time-to-class from server-side class start time and server receipt time to ensure determinism

Caching, Rate Limiting, and Audit Logging

Given two identical requests arrive within the configured cache TTL and no invalidation events have occurred When the second request is processed Then the engine serves the result from cache and records a cache_hit in metrics or logs Given a client exceeds the configured request rate limit When additional requests are received Then the engine responds with HTTP 429 and includes a Retry-After header consistent with the rate-limit policy Given a calculation completes When writing audit logs Then the log includes timestamp, request attributes (time_to_class, latency_summary, caps source), selected duration, and API/engine version, with sensitive PII excluded or redacted

Response Latency Tracking

"As a platform operator, I want to capture accurate response-time metrics so that the adaptive engine can make fair, data-driven hold predictions."

Description

Adds event instrumentation and data models to capture and aggregate response times from waitlist notification sent to seat claim (or expiry). Stores per-class, per-timeslot, and cohort-level metrics with privacy-conscious aggregation, retention windows, and opt-out support. Provides percentile distributions and recency-weighted signals to the Adaptive Hold engine, with fallbacks when data is insufficient. Integrates with existing analytics pipelines, ensures timezone normalization, and exposes query endpoints for experimentation and monitoring.

Acceptance Criteria

Instrumentation of Response Latency Events

Given a waitlist notification is sent When the send occurs Then a notification_sent event is persisted within 100ms with fields: event_id, class_id, timeslot_id, anonymized_user_id, cohort_tags, server_timestamp_utc. And when a student claims a seat before expiry Then a seat_claimed event is persisted within 100ms and latency_ms = claim_time_server - notification_sent_time_server is stored. And when a hold expires without claim Then a hold_expired event is persisted and latency_ms equals the configured hold duration. And events are idempotent by event_id; duplicate submissions result in a single stored record. And in a load test of 10,000 notifications, end-to-end event loss is <0.1% and timing error is <50ms at P95. And 99.9% of notification_sent events have a matching terminal event (seat_claimed or hold_expired) within 15 minutes or until class start, whichever comes first.

Timezone Normalization for Timeslot Boundaries

Given classes operate across multiple timezones and DST transitions When response latency events are ingested Then event timestamps are stored in UTC and enriched with class_local_tz and local_date derived from the class’s timezone. And aggregations by timeslot align strictly to the class’s local timezone boundaries (not the user’s timezone). And on DST change days, no events are assigned to incorrect local_date or timeslot_id (100% correctness on test fixtures). And for a validation dataset of 1,000 events across 5 timezones, mapping of UTC->local_date/timeslot_id matches the reference mapping 100%.

Per-Class, Per-Timeslot, and Cohort Aggregations

Given streaming and daily batch aggregation jobs are running When response latency events arrive Then percentiles p50, p75, p90, p95, p99, mean, min, max, and count are computed for each grouping: class_id, timeslot_id, and cohort (e.g., city, category). And streaming aggregates are available within 5 minutes of window close (P95), and daily batch completes within 30 minutes of schedule (P95). And for a seeded dataset of 5,000 events, computed percentiles match a reference implementation within ±1% absolute error. And aggregates are stored with schema_version, window_start, window_end, and retained for ≥180 days.

Privacy, Aggregation Thresholds, and Opt-Out Compliance

Given privacy requirements When events are stored Then no raw PII (name, phone, email) is persisted; anonymized_user_id is a rotating hash (salt rotates daily) and is non-reversible. And cohort aggregates are only exposed when there are ≥10 unique anonymized_user_id in the window; otherwise the metric is suppressed. And if a user has analytics_opt_out=true or submits a deletion request Then their historical events are purged within 30 days and they are excluded from future raw and derived datasets within 24 hours. And raw events are retained ≤30 days; derived aggregates ≤180 days; purge jobs emit audit logs proving deletion success.

Recency-Weighted Signals and Fallback Logic

Given Adaptive Hold requests a response latency signal When computing signals Then an exponentially weighted moving average (half-life 7 days) and percentile estimates are produced per timeslot_id and class_id with freshness_timestamp. And if events in the past 14 days are <30 for timeslot_id, fallback to class_id; if <50 for class_id, fallback to cohort; if cohort unavailable, fallback to global default of 120 seconds. And the signal response includes provenance ∈ {timeslot, class, cohort, global} and sample_size. And in backtests over 90 days, the selection logic always chooses the most specific level with sufficient data (100% of cases) and never returns an empty signal. And the signal retrieval service meets P95 latency <200ms and uptime ≥99.9%.

Analytics Pipeline Integration and Schema Versioning

Given existing analytics infrastructure When publishing events Then events are emitted to topic response_latency.v1 with a registered schema; schema changes follow semantic versioning with backward-compatible additions as minor releases. And breaking schema changes publish vNext in parallel for ≥30 days and provide dual-write until consumers migrate. And end-to-end delivery latency is <1s at P95 with at-least-once guarantees; consumers can deduplicate via event_id. And contract tests in CI validate schema compatibility; a breaking change without migration plan fails the build.

Metrics Query API for Experimentation and Monitoring

Given consumers query metrics When calling GET /metrics/response-latency with filters (class_id, timeslot_id, cohort, date_from, date_to, tz) Then the API returns JSON containing percentiles [50,75,90,95,99], mean, count, window, provenance, and sample_size. And requests require OAuth2 with scope analytics.read and are rate-limited to 60 requests/min per token. And performance meets P95 latency <300ms and P99 <500ms for cached ranges. And invalid filters return 400 with structured error_code and message; insufficient data returns 200 with provenance=global and sample_size=0. And API documentation includes examples and is validated by 20+ contract tests with 100% pass rate.

Instructor Controls & Caps

"As an instructor, I want to cap how short or long holds can be and toggle the feature per class so that I retain control while keeping the experience fair for students."

Description

Delivers UI and settings to enable/disable Adaptive Hold globally and per class, set minimum and maximum hold durations (e.g., 30–180 seconds), and preview the next computed hold based on current time-to-class and recent response data. Includes an emergency pause, role-based access, sensible defaults, and inline education/tooltips. All changes are audited, applied without downtime, and propagated consistently to the hold engine so instructors maintain control and student-friendly boundaries.

Acceptance Criteria

Global and Per-Class Adaptive Hold Controls

- Given Global Adaptive Hold is enabled and a class has no override, When a waitlist offer is generated, Then the offer metadata includes adaptive=true and the Adaptive Hold algorithm is applied. - Given Global Adaptive Hold is disabled, When a waitlist offer is generated for any class without an override, Then the offer metadata includes adaptive=false and no adaptive computation is used. - Given Global Adaptive Hold is disabled and a specific class override is set to Enabled, When a waitlist offer is generated for that class, Then the offer metadata includes adaptive=true and other classes remain adaptive=false. - Given Global Adaptive Hold is enabled and a specific class override is set to Disabled, When a waitlist offer is generated for that class, Then the offer metadata includes adaptive=false and other classes remain adaptive=true. - Given any toggle change is saved, When observed in system events, Then the effective setting is propagated to the hold engine within 2 seconds (P95) without interrupting in-flight offers, and newly created offers reflect the new state.

Hold Duration Caps Enforcement and Validation

- Given the Min and Max hold duration inputs, When values outside 30–180 seconds or non-integers are entered, Then the form shows inline validation, prevents save, and explains allowed bounds. - Given Min > Max, When attempting to save, Then save is blocked and an error states that Min must be less than or equal to Max. - Given valid Min/Max (e.g., Min=30, Max=180), When saved, Then values persist on reload and are applied to both global defaults and any class that inherits global settings. - Given the hold engine computes a duration, When generating a new offer, Then the resulting holdDuration is within [Min, Max] inclusive and rounded to whole seconds; boundary cases (30 and 180) are honored exactly. - Given invalid characters or paste input, When entered, Then the field sanitizes or rejects input without altering stored values.

Preview Next Computed Hold Accuracy and Refresh

- Given current time-to-class and recent response data exist, When the Preview Next Hold is displayed, Then its value matches the hold engine’s computed value for the same inputs within ±1 second. - Given Min/Max caps are adjusted, When the preview is visible, Then the preview updates within 1 second and never shows a value outside the saved caps. - Given time-to-class changes by ≥60 seconds, When no other inputs are modified, Then the preview auto-refreshes to reflect the new computation without a page reload. - Given the preview service is temporarily unavailable, When the preview panel is opened, Then a non-blocking error state is shown and form saves remain available.

Emergency Pause Behavior and Recovery

- Given Emergency Pause is activated at the account or class level, When active, Then no new waitlist offers are sent and the UI shows a persistent Paused indicator for the affected scope. - Given Emergency Pause is activated while one or more offers are in-flight, When active, Then those in-flight offers continue to their original expiry without reassignment; no additional offers are issued until pause is lifted. - Given Emergency Pause is lifted, When new offers are generated, Then normal adaptive behavior resumes using the latest saved settings and the next eligible waitlist member receives the offer. - Given Emergency Pause is toggled, When saved, Then the state change is propagated to the hold engine within 2 seconds (P95) and an audit log entry is created.

Role-Based Access and Audit Logging

- Given a user with role Instructor or Admin, When viewing Controls & Caps, Then all settings are editable and Save applies changes successfully. - Given a user with role Staff or Viewer, When viewing Controls & Caps, Then settings are read-only and any attempted API write returns 403 Forbidden. - Given any setting change (global toggle, per-class override, Min/Max, Pause), When saved, Then an audit record is created with actor, timestamp (UTC), scope (account/class), fields changed (before→after), and request ID; records are immutable and viewable by Admins. - Given the audit log view, When filtered by scope or date, Then only matching entries are shown; unauthorized users cannot access the audit log.

Sensible Defaults and Inline Education

- Given a new account first opens Controls & Caps, When the page loads, Then defaults are set to Min=30s and Max=180s and Adaptive Hold is enabled globally (can be changed by the user). - Given info tooltips are present next to each control, When a user hovers (desktop) or taps (mobile), Then a concise explanation of the control appears with guidance on recommended ranges and a link to Learn More. - Given accessibility requirements, When navigating via keyboard or screen reader, Then tooltip triggers are focusable, have ARIA attributes, and content is announced appropriately.

Zero-Downtime Change Propagation and Consistency

- Given any setting is changed and saved, When the system processes offers, Then no 5xx errors occur and no service restarts or degraded availability are observed during or after the change. - Given a change is saved at time T, When the next offer is created on any engine node, Then the configuration version applied is the latest saved version with propagation latency ≤2 seconds (P95) and ≤5 seconds (P99). - Given transient propagation failures, When retries execute, Then the final applied configuration is consistent across nodes and exactly-once in the audit log (no duplicate/conflicting entries). - Given multiple changes are saved in quick succession, When evaluated by the engine, Then last-writer-wins ordering is honored and no offer is created using a configuration older than the last saved version after the propagation window.

Dynamic Waitlist Messaging

"As a student, I want notifications that clearly tell me how long I have to claim a spot so that I can decide quickly and avoid missing out."

Description

Updates SMS, push, and in-app templates to display the current hold duration and deadline within the claim link and landing page. Supports live countdowns, localized time formats, and explicit expiry states. Handles dynamic adjustments when class conditions change, ensures deliverability with throttling and retries, and includes deep links that validate hold tokens server-side. Integrates with the existing auto-text pipeline to maintain momentum and reduce confusion for students at the moment of decision.

Acceptance Criteria

SMS Template Shows Dynamic Hold and Deadline

Given a waitlist offer with hold_duration = 90s and deadline = 2025-08-27T15:05:00Z When the SMS is generated and dispatched Then the SMS body includes the phrases "You have 1:30 to claim" and "until 3:05 PM" And the message contains exactly one deep link with a signed hold token parameter And total SMS length is <= 160 GSM-7 characters; otherwise the auto-shortened template is used And template rendering adds <= 250 ms latency And the message is dispatched within 1 second of the next-candidate event

Push Notification Displays Real-Time Hold Countdown

Given push notifications are enabled and a waitlist offer with hold_duration = 120s is triggered When the push is dispatched Then the notification title includes the class name and "2:00" And the body includes the absolute deadline (localized) And the push is delivered to the device within 5 seconds of dispatch (network permitting) When the user taps after 95 seconds Then the landing page opens showing 25 seconds remaining When the user taps after expiry Then the landing page opens directly in "Hold expired" state

In-App Landing Page Countdown and Expiry State

Given a valid hold token that expires in 75 seconds When the landing page loads Then a countdown displays remaining time synchronized to the server within <= 500 ms drift and ticks every second And the "Claim" CTA is enabled while remaining time > 0 When remaining time reaches 0 Then the page switches to explicit "Hold expired" state and the CTA is disabled And the token validation request returns an expired status within 300 ms When the app is backgrounded for >= 10 seconds and then foregrounded Then the countdown resynchronizes within 300 ms of server time

Localization of Time Formats and Time Zones

Given locale = en-US and device timezone = America/Los_Angeles for deadline 2025-08-27T22:05:00Z When the template renders Then the time displays as "3:05 PM" and uses 12-hour format Given locale = en-GB and device timezone = Europe/London for the same deadline When the template renders Then the time displays as "11:05" and uses 24-hour format Given the device timezone is unavailable When the template renders Then the time defaults to the class timezone and appends the timezone abbreviation

Dynamic Hold Adjustment Mid-Hold

Given an active hold with 90 seconds remaining on the landing page When the server updates the hold deadline to reduce remaining time to 45 seconds Then the countdown updates within 1 second to the new remaining time And a non-blocking "Timer updated" notice is shown for 2 seconds When the server extends the hold by 30 seconds Then the countdown and absolute deadline update within 1 second And no additional SMS is sent due to the adjustment

Deliverability Throttling and Retries

Given an SMS send attempt returns a retryable error (e.g., 5xx) When the system retries Then up to 3 retries occur with exponential backoff of 2s, 4s, and 8s And total retry time does not exceed 20 seconds Given the provider returns 429 rate limited When dispatching waitlist notifications Then the system throttles to the configured per-tenant rate (default 30 SMS/sec and 60 push/sec) and enqueues overflow Given a recipient received a waitlist notification in the last 60 seconds When a new notification would be sent for the same class Then the send is suppressed and the suppression is logged with reason "recent-notification"

Deep Link Token Validation and Error States

Given a deep link with a signed hold token that has not expired and is unclaimed When the link is opened Then the server validates the signature, class, seat availability, and hold state and returns 200 And the landing page shows the active countdown and enabled CTA Given the token is expired When the link is opened Then the server returns 410 Gone And the landing page displays "Hold expired" with a button to rejoin the waitlist Given the token has already been claimed When the link is opened again Then the server returns 409 Conflict And the landing page displays "Offer already used" with no claim CTA Given the token signature is invalid When the link is opened Then the server returns 401 Unauthorized And the landing page displays a generic error with a safe recovery path

Edge-case & Fallback Logic

"As an engineer, I want robust fallback and concurrency handling so that seats are allocated correctly even during failures or last-minute spikes."

Description

Defines deterministic behavior for low lead time (e.g., <15 minutes to class), message delivery failures, overlapping holds, concurrent claims, class cancellations, and time sync issues. Implements atomic seat allocation, idempotent hold creation, and circuit breakers that revert to the static two-minute hold when anomalies occur. Provides alerting, structured error logging, and observability dashboards so operational teams can detect and resolve issues without impacting seat fill or student trust.

Acceptance Criteria

Low Lead Time Hold Duration Determinism (<15 Minutes)

Given a class has a start_time in less than 15 minutes and Adaptive Hold is enabled When a waitlist notification is sent Then the hold duration is set to low_lead_hold_seconds (default 60s) and does not exceed 60 seconds And the hold expiry is calculated as created_at + hold_duration using a monotonic server clock And the student-facing countdown matches the server hold_duration within ±1 second

Message Delivery Failure Fallback & Next-In-Line

Given a waitlist notification is initiated When the primary SMS provider responds with a non-2xx status or no delivery receipt within 15 seconds Then the system retries once via the secondary provider within 5 seconds And if the retry also fails or times out, the candidate is marked undeliverable and skipped And the next waitlister is notified within 5 seconds using a static 120-second hold And the failure event is logged with correlation_id, provider, error_code, and message_id

Idempotent Hold Creation Prevents Overlaps

Given CreateHold requests with the same idempotency_key for the same user and class arrive within 60 seconds When the requests are processed Then only one hold record is created and the same hold_id is returned for all duplicates And seat_available decrements at most once for that seat And any duplicate request without a valid idempotency_key receives 409 Conflict and no new hold is created

Concurrent Claims Race Resolution

Given a single seat is held and two claim requests are received within 100 milliseconds When the claims are processed Then exactly one claim succeeds and the seat is allocated atomically And the losing request receives 409 Conflict with reason "SeatAlreadyClaimed" and is not charged And the waitlist advances to the next candidate within 5 seconds if applicable

Class Cancellation During Active Holds

Given a class state changes to Canceled while there are active holds or pending claims When the cancellation is confirmed Then all active holds are invalidated immediately and become unclaimable And pending payment authorizations tied to those holds are voided or never captured And students with active holds receive a cancellation notice within 10 seconds And claim endpoints for those holds return 410 Gone

Circuit Breaker Threshold & Auto-Recovery

Given anomaly events of types {delivery_failure, claim_timeout, clock_skew_detected} are recorded When 5 or more anomalies occur within a rolling 2-minute window for the same class Then the circuit breaker opens for that class and the hold strategy reverts to a static 120-second hold And while open, adaptive adjustments are disabled and a breaker_open metric is emitted every minute And after 10 consecutive minutes with fewer than 2 anomalies per 2-minute window, the breaker auto-resets to Adaptive Hold And manual override can force open/close via admin API with an audit trail entry

Observability, Structured Logging, and Alerts

Given a synthetic failure is injected for a test class When the event occurs Then a structured log is written within 5 seconds containing {timestamp, environment, class_id, user_id, event_type, severity, correlation_id, error_code} And dashboard panels for delivery_failures, claim_conflicts, breaker_state, and clock_skew reflect the event within 1 minute And an on-call alert is triggered when delivery_failures >= 10 within 5 minutes, containing a link to the relevant dashboard and correlation_id search And logs and metrics are retained for at least 30 days

Impact Analytics & A/B Testing

"As a product manager, I want to A/B test and monitor the impact of Adaptive Hold so that we can validate outcomes and optimize settings before full rollout."

Description

Introduces an experimentation layer to compare Adaptive Hold against a static baseline across classes, cohorts, and time windows. Tracks conversion rate, time-to-fill, no-show rate, and student satisfaction proxies, with guardrails (sample sizing, stop-loss) and staged rollout controls. Provides instructor- and internal-facing dashboards to visualize impact and tune min/max caps, enabling data-driven iteration and confident, incremental deployment.

Acceptance Criteria

Randomized Assignment & Eligibility Guardrails

Given a class session with waitlist enabled and experimentation turned on When the session is created Then the session is randomly assigned to Adaptive Hold (treatment) or Static Hold (control) with the configured split (default 50/50), stratified by instructor and weekday/weekend Given a session has been assigned a variant When waitlist offers are sent for that session Then all offers in that session inherit the same variant (sticky) until the session ends Given eligibility rules When a session has fewer than 3 historical waitlist offers per session average, is a free event, or the instructor manually overrides hold duration Then the session is marked ineligible and routed to Static Hold with assignment logged as "excluded" Given assignment occurs When the decision is made Then an immutable log entry records experiment_id, variant, stratification buckets, timestamp, and actor=system

Sample Size, Power, and Stop-Loss

Given an experiment configuration with target MDE and power When traffic forecasts are computed Then the system calculates required sessions per arm to achieve >=80% power at the specified MDE and blocks start if projected enrollment is insufficient by >10% Given an active experiment When either primary metric (conversion rate) shows a control-over-treatment delta worse than the stop-loss threshold (e.g., -3pp) with two-sided p<0.05 for two consecutive daily windows and >=100 sessions per arm Then the system auto-pauses the experiment, routes new sessions to control, and notifies owners within 5 minutes Given minimum runtime constraints When the experiment has not yet reached 7 calendar days and 100 sessions per arm Then no "winner" recommendation is produced unless a stop-loss is triggered

Metric Definitions and Data Quality

Given event streams for waitlist_offer_sent, hold_accepted, booking_paid, class_attended, and feedback_signal When metrics are computed Then conversion_rate=booking_paid within the hold window / waitlist_offer_sent, time_to_fill=median time from seat available to booking_paid, no_show_rate=1 - attended/booking_paid, satisfaction_proxy=opt_out_rate + complaint_tag_rate; all definitions are applied consistently across variants Given metric computation jobs When events are ingested Then 99% of events are linked across the above entities within 60 seconds and daily missing/unlinked events stay below 0.5%; otherwise the experiment is flagged "data_quality_alert" and new assignments default to control until resolved Given a metric view When a user drills down to a session or instructor Then all counts and denominators reconcile within ±0.5% of raw event exports

Instructor Dashboard: Visibility and Safe Controls

Given an instructor with active experiments When they open Analytics Then they see per-variant conversion rate, time-to-fill, and no-show deltas with 95% confidence intervals for 14 and 30 days, updated within 15 minutes of event arrival Given role-based access When an instructor is logged in Then they can only view data for their own classes and cannot see other instructors' aggregates Given min/max hold caps are editable When the instructor adjusts caps within allowed bounds (e.g., 30s–5m) and confirms Then changes are validated against guardrails, logged with user_id/time, preview projected impact, and take effect for new sessions within 10 minutes

Internal Dashboard: Cohorts, Export, and Audit

Given an internal analyst When they open the A/B dashboard Then they can segment results by class category, time-to-class buckets (<2h, 2–24h, >24h), region, and instructor cohort, with p-values and confidence intervals displayed Given an experiment config change When min/max caps or splits are edited Then an annotation is created on the time series and in the audit log with who/what/when, and all subsequent metrics reflect the new config from the change timestamp Given export needs When the analyst requests CSV for a selected date range Then the export completes within 60 seconds for up to 1,000,000 rows and includes experiment_id, variant, metrics, and segmentation keys

Staged Rollout, Canary, and Kill Switch

Given rollout planning When enabling Adaptive Hold experiment Then the system supports staged percentages per scope (global, region, instructor, class category) starting at 1% canary, then 10%, 25%, 50%, 100% with scheduled or manual ramps Given a critical issue When the kill switch is activated or experimentation service becomes unhealthy for >30 seconds Then all new sessions are routed to Static Hold within 60 seconds and a system-wide alert is issued Given staged rollout states When a rollback is initiated Then the prior stable percentage is restored within 5 minutes and all in-flight sessions retain their current variant (no mid-session flips)

Reliability, Performance, and Privacy

Given assignment requests When a session is created Then variant assignment returns in <50 ms p95 and <150 ms p99 and the service maintains 99.9% monthly availability Given privacy requirements When metrics and logs are stored Then PII (phone, email) is stored separately or hashed, access is restricted by role, and deletion requests propagate to experiment logs within 7 days Given auditability When experiment decisions or overrides occur Then immutable audit logs capture actor, reason, before/after, and are queryable for at least 13 months

Reply Codes

Enable richer actions with a single text: Y2 to claim two seats, Y-PACK to use credits, Y-GIFT to book for a friend, or Y-CARD to switch payment. Students get flexible control without opening a link, and instructors see higher conversion from clear, low-friction replies.

Requirements

Reply Code Parsing & Routing Engine

"As a student replying to a booking text, I want my short code reply to be understood automatically so that my booking action completes without needing to open a link."

Description

Build a robust inbound-SMS interpreter that normalizes and validates reply codes (e.g., Y, Y2, Y-PACK, Y-GIFT, Y-CARD), handles case/spacing/hyphen variations, extracts parameters (e.g., seat count), and deterministically routes to the correct action handler. The engine must be context-aware (class ID, waitlist hold window, user identity, prior messages), idempotent to avoid duplicate bookings, and resilient to ambiguous inputs with clear fallback prompts. It integrates with Classlane’s messaging service, identity, bookings, payments, waitlist, and audit logs, and supports instructor-level enable/disable and alias configuration.

Acceptance Criteria

Normalize and Parse Reply Code Variations

Given inbound SMS text containing supported codes with arbitrary case, spaces, or hyphens (e.g., "y2", "Y-2", " y - 2 ", "Y PACK", "y-pack", "Y - card"), When the engine parses the text, Then it normalizes to canonical codes: "Y", "Y2", "Y-PACK", "Y-GIFT", or "Y-CARD". Given a message with a numeric suffix (e.g., "Y3"), When parsed, Then the seatCount parameter equals the numeric value; seatCount must be an integer between 1 and 9 inclusive; otherwise classify as ERROR:INVALID_SEAT_COUNT. Given a message with a code requiring no parameters (e.g., "Y", "Y-CARD"), When parsed, Then no extraneous parameters are set and normalization preserves canonical form. Given multiple tokens present (e.g., "Y 2 now"), When parsed, Then the engine extracts the single most-confident valid code; If two or more valid codes are detected with equal confidence, Then classify as AMBIGUOUS and do not proceed to action.

Deterministic Routing to Action Handlers

Given a valid canonical code and resolved context, When routing occurs, Then exactly one handler is invoked deterministically: Y->confirm seats=1; Yn->confirm seats=n; Y-PACK->use credits; Y-GIFT->gift booking; Y-CARD->switch payment. Given an instructor alias map (e.g., "YES"->"Y", "PACK"->"Y-PACK"), When an aliased code is received, Then routing resolves to the same handler as its canonical target. Given a disabled code for the instructor, When that code is received, Then no handler is invoked and a context-relevant fallback SMS is sent. Given conflicting alias definitions (two aliases mapping to different targets), When configuration is saved, Then validation fails with a conflict error and previous valid mapping remains active.

Context Awareness and Hold Window Enforcement

Given a reply to a waitlist hold SMS received within the 2-minute hold window, When a valid claim code is parsed, Then the engine resolves classId, userId, seat availability, and applies the claim; If outside the window, Then decline and trigger waitlist next-person flow. Given the conversation lacks classId or userId context, When a valid code is parsed, Then the engine requests disambiguation (e.g., ask for class link) and performs no booking mutation. Given prior messages established seatCount, When the user sends "Y" without a count within the same thread and within 15 minutes, Then the engine uses the last confirmed seatCount if policy allows; otherwise defaults to 1 and informs the user.

Idempotency and Duplicate Message Protection

Given duplicate inbound messages with identical normalized code, parameters, and context within 5 minutes, When processed, Then exactly one booking/payment mutation occurs and subsequent duplicates return a non-mutating confirmation referencing the existing action. Given a handler partially completes and a retry occurs, When retried with the same idempotency key, Then no additional bookings are created and the final state is a single confirmed booking. Given differing codes for the same hold (e.g., "Y2" then "Y"), When the first succeeds, Then later messages within the hold window do not mutate state and instead reply with current status and instructions to modify via link.

Ambiguous or Invalid Input Fallback Prompts

Given a message containing multiple valid codes or mixed intent (e.g., "Y 2 gift"), When parsed, Then classify as AMBIGUOUS and send one clarification SMS listing up to 3 valid options relevant to the current context; no booking mutation occurs. Given an invalid seat count (0, non-numeric, or exceeding available/policy), When parsed, Then send a prompt with the allowed range and do not reserve seats. Given an unsupported or misspelled code, When parsed, Then suggest nearest valid codes using Levenshtein distance <= 2 (max 3 suggestions); if none, send a generic help prompt.

Instructor Enable/Disable and Alias Configuration

Given the instructor has disabled a specific code (e.g., Y-GIFT), When a student sends that code, Then the engine responds with a tailored message and does not route to the handler. Given instructor-defined aliases are submitted, When saving configuration, Then the engine validates for conflicts with existing codes/aliases, reserved words, and regex safety; invalid configurations are rejected with actionable errors. Given multiple instructors with different alias maps, When messages are processed, Then the engine applies only the alias map for the associated instructor/class context; no cross-tenant leakage occurs.

Integration and Audit Logging

Given any processed message (success, decline, ambiguous, error), When completed, Then a single audit log entry is written with correlationId, userId, classId, normalizedCode, parameters, decision, handlerName, idempotencyKey, and timestamps, available for query within 60 seconds. Given calls to bookings, payments, waitlist, identity, or messaging, When invoked by a handler, Then each call is wrapped with retries and compensating actions as configured; failures are logged and the user receives a clear SMS status without partial state left unhandled. Given an outbound SMS is sent as a result of processing, When delivery fails, Then the engine retries once via alternate route (if available) or falls back to a link-based instruction and records the outcome in audit logs.

State-aware Execution & Waitlist Integration

"As a waitlisted student who receives a hold text, I want to confirm my seat with a quick reply so that I can secure it before the hold expires."

Description

Ensure reply code actions respect the two-minute Hold-to-Confirm workflow and current inventory state. When seats are held for a waitlisted student, code execution must atomically confirm within the hold, extend/expire holds appropriately, and trigger backfill if the user declines or times out. Outside waitlist holds, codes should check real-time availability, handle contention with optimistic concurrency, and produce consistent outcomes. System should log transitions and outcomes for reconciliation and customer support.

Acceptance Criteria

Waitlist Hold — Atomic Confirmation via Y2 within 120s

Given a waitlisted student has an active 120-second hold for 2 seats and a valid default payment method on file When the student replies "Y2" within the remaining hold window Then exactly one booking record for 2 seats is created, the card is charged successfully once, the hold is released immediately, inventory decreases by 2, and a confirmation SMS is sent within 5 seconds And no other user is offered those seats after confirmation, and any concurrent processing attempts for the same hold are rejected without additional charges

Waitlist Hold — Decline or Timeout Triggers Backfill

Given a waitlisted student has an active hold for N seats When the student replies "N" or does not reply within 120 seconds Then the hold expires, no charge occurs, a cancellation SMS is sent to the student, and the next waitlisted student is auto-texted within 5 seconds offering N seats And inventory is reserved exclusively for the next waitlisted student for a new 120-second hold, and all state transitions (expire -> offered_to_next) are logged

Open Inventory — Optimistic Concurrency on Simultaneous Claims

Given a class has 1 seat available and two students concurrently send a claim code ("Y" or "Y1") outside any waitlist holds When their requests are processed Then exactly one booking succeeds and receives a confirmation SMS within 5 seconds, the other receives a "Sold out" SMS within 5 seconds, and the final inventory is 0 with no overbooking And the failed request is not charged, and a contention event is logged with both request IDs and outcome codes

Waitlist Hold — Use Credits with Y-PACK

Given a waitlisted student has an active hold for M seats and has at least M credits available When the student replies "Y-PACK" within the hold window Then M credits are deducted atomically, a booking for M seats is created, the hold is released, and a confirmation SMS is sent within 5 seconds And if the student has fewer than M credits, the system replies within 5 seconds with an insufficiency message and payment option, without consuming any credits and while keeping the hold active for its remaining time

Waitlist Hold — Switch Payment Method with Y-CARD

Given a waitlisted student has an active hold and no usable default payment method When the student replies "Y-CARD" within the hold window Then the system sends a secure payment update flow immediately, extends the hold by 60 seconds, and upon successful card update within the extended window confirms the booking and sends a confirmation SMS within 5 seconds And if the card update is not completed before the extended hold expires, the hold is released, no charge occurs, the next waitlisted student is auto-texted within 5 seconds, and the event is logged with outcome=payment_update_timeout

Waitlist Hold — Book for a Friend with Y-GIFT

Given a waitlisted student has an active hold for 1 or more seats and the class is gift-eligible When the student replies "Y-GIFT +<recipient_phone>" within the hold window and has a valid payment method or sufficient credits Then a booking is created assigning one seat per recipient phone provided (up to the held quantity), the payer is the original student, the hold is released, the recipient(s) receive confirmation SMS within 5 seconds, and the original student receives a gift confirmation SMS And if any recipient phone is invalid or opted out, the system responds within 5 seconds with an error for that recipient and does not consume those seats; the hold remains active for the remaining time for valid recipients

System Observability — State Transition Logging and Reconciliation

Given any reply code action (Y, Y1, Y2, Y-PACK, Y-GIFT, Y-CARD) executed under a hold or open inventory When the action completes with Success, Decline, Timeout, Insufficient Inventory, Insufficient Credits, Payment Failure, or Concurrency Conflict Then a structured log entry is written with correlation_id, user_id, class_id, action_code, requested_seats, pre_state, post_state, outcome, timestamps (received_at, processed_at, completed_at), hold_id (if any), and payment_reference (if any), and entries are queryable by support within 60 seconds And daily reconciliation reports show balanced totals for holds, inventory, and bookings with zero mismatches; any mismatch raises an alert within 5 minutes

Quantity-based Seat Claim (Y2, Y3, etc.)

"As a student booking for friends, I want to claim multiple seats with a single text so that I can secure spots quickly without a multi-step checkout."

Description

Support numeric quantity parsing to claim multiple seats with a single reply (e.g., Y2). Validate max seats per booking, class capacity, and instructor policies. If partial capacity remains, offer a downgrade prompt (e.g., only 1 seat left). On success, create a single booking with multiple attendees, reserving placeholders for unnamed guests and providing a follow-up to collect guest details if required. Update availability, roster, taxes/fees, and receipts accordingly.

Acceptance Criteria

Claim Multiple Seats Within Hold Window

Given an invited student receives a hold-to-confirm SMS for a class with at least Q seats available and a 2-minute timer And the student has a valid default payment method on file When the student replies "YQ" where Q is a positive integer between 1 and the maxSeatsPerBooking inclusive, within the 2-minute window Then the system parses Q, validates capacity and policy, and creates a single booking for Q seats atomically And sends a confirmation SMS including class name, date/time, and quantity within 5 seconds And decrements class availability by Q immediately

Enforce Max Seats per Booking Policy

Given maxSeatsPerBooking = N for the class When a student replies "YQ" where Q>N Then the system rejects the claim with a message stating "Max N seats per booking" and suggests "Reply YN to claim N" And no seats are reserved or held

Downgrade Prompt When Requested Quantity Exceeds Remaining Capacity

Given only R seats remain for the class (R>0) When a student replies "YQ" where Q>R and Q<=maxSeatsPerBooking Then the system responds with "Only R left. Reply YR to claim" within 5 seconds And no booking is created until a subsequent valid reply is received And if the student replies "YR" within 2 minutes of the prompt and seats are still available, the system books R seats and confirms And if seats sell out before the "YR" reply, the system informs the student "Sold out" and does not create a booking

Atomic Capacity Check Under Concurrency

Given multiple students reply with "YQ" quantities that in sum exceed remaining capacity When the system processes the replies Then each booking is committed with an atomic capacity check to prevent oversell And the final remaining capacity is never negative And students whose claims cannot be fully satisfied receive either a downgrade prompt (if partial capacity remains) or a sold-out message within 10 seconds

Multi-Attendee Booking Placeholders and Guest Details Collection

Given a booking is confirmed for Q>1 seats and only the primary student’s details are known When the booking is created Then the system creates Q attendee slots with Q-1 placeholders flagged as "Details Needed" And sends a follow-up SMS with a secure link to collect guest names and emails And the roster shows placeholders until details are supplied And if details are not provided within 24 hours, a reminder SMS is sent (max 2 reminders)

Pricing, Taxes/Fees, Receipt, and Reporting for Multi-Seat Booking

Given seat price P, applicable taxes/fees F per seat, and any class-level discounts D applicable per seat When a student successfully books "YQ" Then the system charges Total = Q*(P+F−D) using the student’s default payment method And issues a single receipt showing quantity Q, unit price, taxes/fees, discounts, and total paid And updates revenue and tax reports accordingly for Q seats And the class roster and availability reflect Q new attendees immediately

Invalid or Malformed Quantity Reply Handling

Given the system receives a reply with invalid quantity (e.g., "Y0", "Y-1", "Y", "Ytwo", non-integer, or exceeds system hard limit) When parsing the reply Then the system responds with an error message including a valid example (e.g., "Reply Y1 or Y2") within 5 seconds And no booking, hold, or capacity change occurs And the interaction is logged for analytics

Credit Pack Redemption via Reply (Y-PACK)

"As a student with prepaid credits, I want to use my credits by replying to a text so that I don’t have to re-enter payment details."

Description

Enable students to apply eligible class credits to confirm a booking by replying Y-PACK. Validate credit balance, expiration, product eligibility, and policy rules (e.g., credit-to-seat mapping for multi-seat claims). Support mixed payments when credits are insufficient and reflect accurate ledger movements. Provide clear confirmation or guidance if credits cannot be applied, and update analytics with credit utilization metrics.

Acceptance Criteria

Single-Seat Redemption with Sufficient Eligible Credits

Given a student has an active hold for 1 seat on an eligible class and at least the required credits per seat available When the student replies "Y-PACK" within the hold window Then the system confirms 1 seat and debits the required number of credits using a soonest-expiring-first policy And creates an immutable ledger entry linked to the booking and credit pack with timestamp and idempotency key And does not charge any card on file And sends a confirmation SMS including seat count, credits used, remaining credit balance, and class details And emits a "credit_redeemed" analytics event with userId, classId, seats=1, credits_debited, balance_after, pack_type, redemption_source="reply_code"

Multi-Seat Redemption via Y2-PACK with Credit-to-Seat Mapping

Given a class defines CreditsPerSeat and a student hold allows 2 seats And the student’s eligible credits are greater than or equal to 2 x CreditsPerSeat When the student replies "Y2-PACK" within the hold window Then the system confirms 2 seats And debits credits equal to 2 x CreditsPerSeat prioritized by soonest expiration And records a single consolidated ledger transaction referencing both seats and the credit pack consumption details And sends a confirmation SMS summarizing seats, credits used, remaining balance, and manage link And emits an analytics event with seats=2 and credits_debited=2 x CreditsPerSeat

Mixed Payment When Credits Are Insufficient

Given a class defines CreditsPerSeat and the student requests 2 seats with "Y2-PACK" And the student’s eligible credits are fewer than 2 x CreditsPerSeat but at least CreditsPerSeat When the system processes the reply Then it applies credits to the maximum whole number of seats covered by credits (floor(credits_available / CreditsPerSeat)) And attempts to charge the remaining seats at the class price to the default payment method on file within the hold window And confirms the booking only if the card charge succeeds, with a receipt showing split tender (credits + card) And on success, sends an SMS stating seats confirmed, credits used, card amount charged, and remaining credits And on card failure or no valid payment method, sends an SMS with failure reason and instructions to reply "Y" to pay by card or "Y-CARD" to update a card, and does not confirm seats And creates accurate ledger entries for credits consumed and card charges, with idempotency to prevent duplication

Credit Ineligibility or Expiration Handling

Given the student replies "Y-PACK" and their credits are expired or not eligible for the class When validation runs Then the system rejects the redemption And sends an SMS explaining the reason (expired or ineligible) and offering options: "Reply Y to pay by card" or "Y-CARD" to update payment, plus a link to credit details And makes no ledger changes or holds on funds And emits a "credit_redeem_failed" event with reason_code in {expired, ineligible}

Idempotency and Duplicate Reply Protection

Given the student sends duplicate "Y-PACK" or "Y2-PACK" messages within the same hold window or due to SMS retries When processing these messages Then the system processes exactly one redemption and one set of ledger movements And responds to duplicates with a non-error SMS indicating the booking status (e.g., "Already confirmed") without creating additional bookings or charges And all operations are protected by an idempotency key derived from the message SID and hold token

Instructor and Student Visibility of Credit Usage

Given a booking was confirmed using credits or credits + card When viewing the student receipt SMS and the instructor dashboard Then the student sees seats confirmed, credits used, any card amount charged, remaining credits, and manage link And the instructor sees payment source labeled "Credits" or "Credits + Card" with credits consumed per seat And exported payout/ledger reports include credit debits and card charges with reconciled totals

Analytics and Reporting of Credit Utilization

Given any Y-PACK attempt (success or failure) When the event pipeline processes the transaction Then a corresponding analytics event is recorded with userId, classId, bookingId (if any), seats_requested, seats_confirmed, credits_debited, pack_type, mixed_payment_flag, and failure_reason (if applicable) And the event is queryable in the analytics store within 15 minutes of the reply And metrics dashboards reflect credit utilization rate and mixed-payment conversions for the feature

Gift Booking Flow (Y-GIFT)

"As a student, I want to book a class for a friend with a quick reply so that I can gift them a spot without a complex checkout."

Description

Allow booking on behalf of another person with a single reply. Upon Y-GIFT, reserve the seat(s), then collect recipient name and contact via a short SMS follow-up or secure link. Support payer = sender (default) and optional credit application. Send the recipient a confirmation and calendar invite, and reflect gift status on the roster. Enforce privacy preferences, gift notes, and refund/transfer policies as configured by the instructor.

Acceptance Criteria

Single-reply gift booking success path

Given a class has at least one available seat and the sender has a valid default payment method on file When the sender replies "Y-GIFT" and submits a valid recipient name and contact (SMS-capable phone or email) within 2 minutes via follow-up SMS or secure link Then the system places an immediate hold on one seat, validates the recipient contact, and confirms the booking upon successful charge And the recipient receives a confirmation and calendar invite And the sender receives a confirmation SMS including gift status and amount charged And the roster updates in real time to show the recipient as attending with a "Gift" badge and payer = sender visible to the instructor

Hold timeout and seat release on incomplete gift

Given a seat hold is started by a "Y-GIFT" reply When recipient details are not provided and validated within 2 minutes Then the hold automatically expires, the seat is released, and no charges or credit deductions occur And any payment pre-authorization is voided And the sender is notified that the hold expired with instructions to restart the gift booking

Gift booking for multiple seats

Given a class has N available seats and the sender initiates a gift booking for M seats (1 < M ≤ N) When the sender supplies M recipient names and contacts or marks specific seats as "+1 unnamed guest" before the hold expires Then the system holds M seats, validates provided contacts, and confirms bookings for recipients with completed details upon successful payment And any seats marked as "+1 unnamed guest" remain reserved under the gift with a secure link for the sender to complete details later without releasing confirmed seats And if M exceeds available seats at any point, the sender is informed of the shortfall and no charge occurs until a revised seat count is confirmed

Apply credits to a gift booking

Given the sender has an available credit balance and instructor settings allow credits on gifts When the sender opts to apply credits during the "Y-GIFT" flow Then credits are applied first to cover the seat(s), any remainder is charged to the default payment method, and no charge occurs if credits fully cover the amount And confirmations and receipts clearly indicate the number of credits used and any supplemental charge

Privacy preferences for anonymous gifting

Given the instructor allows anonymous gifting and the sender selects "hide my name from recipient" When the gift booking is confirmed Then recipient-facing communications show the gifter as "A friend" and do not reveal the sender’s identity or contact And the roster shows the attendee with a "Gift (Anonymous)" badge while the payer = sender is visible only to the instructor/staff And recipient contact information is not shared with other attendees

Gift note capture and delivery

Given the sender chooses to include a gift note up to 280 characters and content passes profanity/blocked-terms checks When the gift booking is confirmed Then the note appears in the recipient confirmation and in the calendar invite description (if supported by the calendar provider) And the note is visible to the instructor in the roster/booking details but not visible to other attendees And if the note exceeds the character limit or contains blocked terms, the sender is prompted to edit before completion

"As an admin, I want fine-grained access controls and audit logs so that we protect sensitive data and can prove compliance."

Description

Implement granular permissions for viewing, exporting, and configuring gift settings, separating finance, ops, and instructor roles. All changes to rules, mappings, and instrument adjustments must be captured with who/when/what before/after details and immutable audit logs. Provide exportable audit trails for compliance and SOC2 needs, with filters by user, action, and time range. Surface high-risk changes (e.g., disabling expirations, bulk adjustments) with review/approval workflows and notifications. Integrate with Classlane’s orgs and team management to inherit roles and SSO where available.

Product Details

Vision & Mission

Problem & Solution

Details & Audience

User Personas

Schedule-Syncing Sam

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Gifting Grace

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Touring-Teacher Tasha

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Metrics-Minded Maya

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Space-Sharing Sergio

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Calendar-Blocking Ben

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Product Features

Adaptive Hold

Requirements

Adaptive Hold Duration Engine

Description

Acceptance Criteria

Response Latency Tracking

Description

Acceptance Criteria

Instructor Controls & Caps

Description

Acceptance Criteria

Dynamic Waitlist Messaging

Description

Acceptance Criteria

Edge-case & Fallback Logic

Description

Acceptance Criteria

Impact Analytics & A/B Testing

Description

Acceptance Criteria

Reply Codes

Requirements

Reply Code Parsing & Routing Engine

Description

Acceptance Criteria

State-aware Execution & Waitlist Integration

Description

Acceptance Criteria

Quantity-based Seat Claim (Y2, Y3, etc.)

Description

Acceptance Criteria