Playground Environments
The playground system provides free-tier trial environments for prospective users. It manages a fixed pool of 16 playground slots with automatic lifecycle management, waitlisting, and conversion to paid subscriptions. Served by PlaygroundController at /api/v1/playground.
How Playground Works
New users sign up for a playground slot. If a slot is available, it is allocated immediately with a 14-day expiration. If all slots are occupied, the user is added to a waitlist and notified when a slot becomes available.
User PlaygroundController PlaygroundService
| | |
|--- POST /signup ---------->| |
| |--- allocateSlot() -------->|
| | |--- Check availability
| | |--- Allocate or waitlist
|<-- SignupResponse ---------|<-- AllocationResult --------|Slot Lifecycle
| State | Description |
|---|---|
AVAILABLE | Slot is free and can be allocated |
ALLOCATED | Slot is assigned to a user |
EXPIRED | Slot's 14-day period has ended |
GRACE_PERIOD | User is in the post-expiry grace period |
PURGED | Slot has been cleaned up and data removed |
CONVERTED | User converted to a paid subscription |
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/playground/signup | Request a playground slot |
| POST | /api/v1/playground/waitlist | Join the waitlist explicitly |
| POST | /api/v1/playground/waitlist/claim | Claim waitlist slot |
| GET | /api/v1/playground/status | Get playground status for user |
| GET | /api/v1/playground/slots/available | Get available slot count |
| GET | /api/v1/playground/waitlist/position | Get waitlist position |
| POST | /api/v1/playground/convert | Convert to paid customer |
| POST | /api/v1/playground/slots/:slotId/activity | Record activity |
Signup Response
{
"allocated": true,
"addedToWaitlist": false,
"alreadyAllocated": false,
"slotId": "uuid",
"slotNumber": 7,
"expiresAt": "2026-02-26T10:00:00Z",
"message": "Playground slot 7 allocated! Expires in 14 days."
}Waitlist Management
When no slots are available, users are placed on a FIFO waitlist. The waitlist response includes the position and estimated wait time.
Conversion to Paid
{
"tenantId": "uuid",
"planCode": "professional",
"paymentMethodId": "pm_abc123"
}Converting preserves all data and configurations from the playground environment.
Admin Operations
| Endpoint | Description |
|---|---|
GET /api/v1/playground/admin/slots | List all slots with status |
GET /api/v1/playground/admin/waitlist | View entire waitlist |
POST /api/v1/playground/admin/slots/:slotId/purge | Manually purge a slot |
POST /api/v1/playground/admin/process-expired | Process expired slots |
POST /api/v1/playground/admin/process-grace-period | Process grace periods |
POST /api/v1/playground/admin/process-waitlist | Process waitlist allocations |