mp-pilates/docs/TIME_SLOT_INDEX.md

Time-Slot & Scheduling System - Documentation Index

This directory contains comprehensive documentation of the NestJS backend time-slot and scheduling system for the pilates studio booking platform.

📚 Documentation Files

1. TIME_SLOT_SCHEDULING_SYSTEM.md (966 lines, 24KB)

Most comprehensive reference - Full system analysis with all details

Contents:

• Executive Summary
• Data Models (WeekTemplate, TimeSlot, Booking) with Prisma schema
• SlotGeneratorService (4 key methods: generateSlots, cleanupExpiredSlots, checkExpiredMemberships, completeBookings)
• TimeSlotService (queries and management)
• TimeSlotController & AdminTimeSlotController (all endpoints)
• SchedulerService (4 daily cron jobs at 02:00, 02:30, 03:00, 22:00 UTC)
• BookingService (integration with time slots)
• Data Flow Diagrams
• DTOs & Request/Response examples
• Shared Constants & Enums
• File Structure Summary
• Key Architectural Patterns
• Example Scenarios
• Testing Guide
• Configuration & Environment
• Performance Considerations
• Security Notes
• Future Enhancement Ideas

When to use: Deep dive into how the system works, understanding all components

---

2. TIME_SLOT_QUICK_REFERENCE.md (355 lines, 9KB)

Quick lookup guide - Essential information at a glance

Contents:

• File Locations (all key files in one table)
• Key Concepts (WeekTemplate, TimeSlot, Booking)
• Daily Scheduler Jobs (quick table with times and purposes)
• Important Methods (TypeScript signatures for all key methods)
• API Endpoints (member and admin endpoints with request/response)
• Status Values (all enum values explained)
• Key Logic (booking creation & cancellation flows in pseudocode)
• Weekday Mapping (ISO standard vs JavaScript)
• Database Constraints
• Configuration
• Common Errors (troubleshooting table)
• Testing
• Development Workflow
• Architecture Highlights

When to use: Quick lookup while coding, API reference, debugging errors

---

3. TIME_SLOT_DIAGRAMS.md (606 lines, 25KB)

Visual references - ASCII diagrams and flowcharts

Contents:

1. Data Model Relationships (entity diagram)
2. Daily Scheduler Timeline (24-hour cron schedule visualization)
3. Booking Lifecycle (detailed creation and cancellation flows)
4. Slot Generation from Template (step-by-step with example)
5. User Booking Flow (frontend → backend interaction)
6. State Transitions (TimeSlot, Booking, Membership status flows)
7. Timezone & Date Handling (UTC, local time conversion)
8. Error Handling Tree (decision tree for POST /booking and cancellation)
9. Integration Points (module dependencies)

When to use: Understanding the big picture, presenting to team, tracing flow execution

---

🔍 Key Information at a Glance

Source Code Locations

Backend Time-Slot System:
├── packages/server/src/time-slot/
│   ├── slot-generator.service.ts     (172 lines)
│   ├── time-slot.service.ts          (142 lines)
│   ├── time-slot.controller.ts       (93 lines)
│   ├── time-slot.module.ts
│   └── dto/
│       ├── query-slots.dto.ts
│       ├── create-manual-slot.dto.ts
│       └── week-template.dto.ts
│
├── packages/server/src/scheduler/
│   ├── scheduler.service.ts          (55 lines)
│   └── scheduler.module.ts
│
├── packages/server/src/booking/
│   ├── booking.service.ts            (367 lines)
│   ├── booking.controller.ts          (82 lines)
│   ├── booking.module.ts
│   └── dto/
│       └── create-booking.dto.ts
│
├── packages/server/prisma/
│   └── schema.prisma                 (Models: WeekTemplate, TimeSlot, Booking)
│
└── packages/shared/src/
    ├── constants.ts                  (Slot generation, capacity defaults)
    ├── enums.ts                      (TimeSlotStatus, BookingStatus, etc.)
    └── types/
        └── time-slot.ts              (Type definitions)

Daily Scheduler (UTC)

Time	Job	Method
02:00	Generate 14 days of slots	SlotGeneratorService.generateSlots(14)
02:30	Close expired OPEN slots	SlotGeneratorService.cleanupExpiredSlots()
03:00	Expire memberships	SlotGeneratorService.checkExpiredMemberships()
22:00	Complete past bookings	SlotGeneratorService.completeBookings()

Important Constants

DEFAULT_SLOT_CAPACITY = 1              (private lessons)
SLOT_GENERATION_DAYS = 14              (days ahead to auto-generate)
DEFAULT_CANCEL_HOURS_LIMIT = 2         (hours before slot to allow refund)

API Endpoints

Member:

GET    /time-slot/available?date=YYYY-MM-DD
GET    /time-slot/:id
POST   /booking
PUT    /booking/:id/cancel
GET    /booking/my
GET    /booking/my/upcoming

Admin:

GET    /admin/week-template
PUT    /admin/week-template
POST   /admin/time-slot/manual
PUT    /admin/time-slot/:id/close
POST   /admin/generate-slots
GET    /admin/bookings

---

🎯 Common Tasks & Where to Find Info

Task	Reference
Understand slot generation algorithm	TIME_SLOT_SCHEDULING_SYSTEM.md § 2.2 or DIAGRAMS § 4
See all API endpoints	QUICK_REFERENCE § "API Endpoints" or TIME_SLOT_SCHEDULING_SYSTEM.md § 4
Booking creation logic	TIME_SLOT_DIAGRAMS.md § 3 or QUICK_REFERENCE § "Key Logic"
Weekday mapping (ISO vs JS)	QUICK_REFERENCE § "Weekday Mapping" or DIAGRAMS § 7
Cancellation refund policy	TIME_SLOT_SCHEDULING_SYSTEM.md § 6.1 or DIAGRAMS § 3
Scheduler jobs timeline	QUICK_REFERENCE § "Daily Scheduler Jobs" or DIAGRAMS § 2
Error handling	QUICK_REFERENCE § "Common Errors" or DIAGRAMS § 8
Data model relationships	DIAGRAMS § 1 or TIME_SLOT_SCHEDULING_SYSTEM.md § 1
Configuration & setup	QUICK_REFERENCE § "Configuration" or TIME_SLOT_SCHEDULING_SYSTEM.md § 14
Performance tips	TIME_SLOT_SCHEDULING_SYSTEM.md § 15 or QUICK_REFERENCE § "Performance Tips"
Module dependencies	DIAGRAMS § 9 or TIME_SLOT_SCHEDULING_SYSTEM.md § 11.2
Testing	TIME_SLOT_SCHEDULING_SYSTEM.md § 13 or QUICK_REFERENCE § "Testing"

---

📋 System Overview

What It Does

This system manages the complete lifecycle of time slots and bookings for a pilates studio:

1. Automated Slot Generation: Every day at 02:00 UTC, generates 14 days of time slots from reusable weekly templates
2. Capacity Management: Tracks slot capacity and prevents overbooking
3. Booking Management: Allows members to book slots with their memberships
4. Cancellation & Refunds: Members can cancel with conditional refunds (within 2-hour window)
5. Membership Expiration: Automatically expires memberships by date or used sessions
6. Cleanup: Marks past slots as closed and completed bookings as finished

Key Concepts

• WeekTemplate: Defines recurring schedule (e.g., "Monday 09:00-10:00")
• TimeSlot: Individual class instance (e.g., "April 10, 2026 09:00-10:00")
• Booking: User's reservation (links user + slot + membership)
• Status Tracking: OPEN → FULL → CLOSED (slots) and CONFIRMED → COMPLETED (bookings)

Architecture Highlights

✅ Idempotent - Safe to re-run slot generation ✅ Transactional - ACID compliance for bookings ✅ Automated - 4 daily cron jobs maintain state ✅ Flexible - Supports TIMES, DURATION, and TRIAL memberships ✅ Scalable - Batch operations, proper database indexes ✅ Secure - Role-based access, comprehensive validation

---

🚀 Getting Started

For New Developers

1. Start with: TIME_SLOT_QUICK_REFERENCE.md

   • Get oriented with file locations and key methods

2. Then read: TIME_SLOT_DIAGRAMS.md § 1 (Data Model)

   • Understand how entities relate

3. Deep dive: TIME_SLOT_SCHEDULING_SYSTEM.md § 2

   • Study the SlotGeneratorService algorithm

4. Explore the code: Read actual source files for implementation details

For System Integration

1. Review TIME_SLOT_DIAGRAMS.md § 9 (Integration Points)
2. Check the module imports in app.module.ts
3. Understand dependencies in QUICK_REFERENCE.md § "Configuration"

For API Integration

1. Start with TIME_SLOT_QUICK_REFERENCE.md § "API Endpoints"
2. See examples in TIME_SLOT_SCHEDULING_SYSTEM.md § 12
3. Check DTOs in TIME_SLOT_SCHEDULING_SYSTEM.md § 8

For Debugging

1. Check common errors in QUICK_REFERENCE.md § "Common Errors"
2. Trace error handling in DIAGRAMS.md § 8
3. Review actual error handling in source code

---

📖 Reading Recommendations by Role

Backend Developer

1. TIME_SLOT_SCHEDULING_SYSTEM.md (all)
2. TIME_SLOT_DIAGRAMS.md (all)
3. Source code in packages/server/src/time-slot/

Frontend Developer

1. TIME_SLOT_QUICK_REFERENCE.md (API Endpoints section)
2. TIME_SLOT_SCHEDULING_SYSTEM.md § 12 (Example Scenarios)
3. TIME_SLOT_DIAGRAMS.md § 5 (User Booking Flow)

DevOps / Sysadmin

1. TIME_SLOT_SCHEDULING_SYSTEM.md § 14 (Configuration)
2. TIME_SLOT_QUICK_REFERENCE.md § "Daily Scheduler Jobs"
3. TIME_SLOT_DIAGRAMS.md § 2 (Scheduler Timeline)

Product Manager

1. TIME_SLOT_SCHEDULING_SYSTEM.md § "Executive Summary"
2. TIME_SLOT_DIAGRAMS.md § 3 & 5 (Booking flows)
3. TIME_SLOT_QUICK_REFERENCE.md § "Architecture Highlights"

QA / Tester

1. TIME_SLOT_QUICK_REFERENCE.md (all)
2. TIME_SLOT_SCHEDULING_SYSTEM.md § 13 (Testing Guide)
3. TIME_SLOT_SCHEDULING_SYSTEM.md § 12 (Example Scenarios)

---

🔗 Related Documentation

• Database Schema: See packages/server/prisma/schema.prisma (lines 113-168)
• Shared Types: See packages/shared/src/types/ and enums.ts
• Authentication: See booking endpoints require JwtAuthGuard
• Membership System: See BookingService integration with MembershipService
• Studio Config: See StudioService for cancelHoursLimit

---

📊 Document Statistics

File	Lines	Size	Topics
TIME_SLOT_SCHEDULING_SYSTEM.md	966	24KB	17 comprehensive sections
TIME_SLOT_QUICK_REFERENCE.md	355	9KB	15 quick-lookup sections
TIME_SLOT_DIAGRAMS.md	606	25KB	9 visual flowcharts
Total	1,927	58KB	Complete system coverage

---

🎓 Learning Path

Entry Level
├─ README.md (this file)
├─ TIME_SLOT_QUICK_REFERENCE.md (20 min read)
└─ TIME_SLOT_DIAGRAMS.md § 1 (5 min)

Intermediate
├─ TIME_SLOT_DIAGRAMS.md (all, 15 min)
├─ TIME_SLOT_QUICK_REFERENCE.md (re-read, 15 min)
└─ TIME_SLOT_SCHEDULING_SYSTEM.md § 1-6 (30 min)

Advanced
├─ TIME_SLOT_SCHEDULING_SYSTEM.md (full, 60 min)
├─ Source code reading (packages/server/src/time-slot/)
└─ Prisma schema study

Expert
└─ Code review + contributions

---

🤝 Contributing

When adding features or making changes:

1. Update the code in packages/server/src/time-slot/ and related modules
2. Update tests in __tests__/ directories
3. Update documentation in this docs folder if behavior changes
4. Use the Quick Reference as checklist for all affected pieces

---

❓ FAQ

Q: Where do time slots come from? A: Auto-generated from WeekTemplates every day at 02:00 UTC by generateSlots(14).

Q: Can I disable slot generation? A: Yes, make templates isActive: false or disable the cron job in scheduler.service.ts.

Q: How is capacity managed? A: bookedCount increments on booking, slot status becomes FULL when bookedCount >= capacity.

Q: What if I cancel a booking? A: bookedCount decrements; if within 2-hour window, membership refunded; slot status restored if was FULL.

Q: Timezone support? A: All times stored in UTC. Scheduler uses UTC times (02:00, 02:30, etc.). See DIAGRAMS § 7.

Q: How are memberships expired? A: Automatically by scheduler job at 03:00 UTC daily; marks EXPIRED if date passed or USED_UP if sessions depleted.

---

📞 Quick Reference Card

Status Values

• TimeSlot: OPEN | FULL | CLOSED
• Booking: CONFIRMED | CANCELLED | COMPLETED | NO_SHOW
• Membership: ACTIVE | EXPIRED | USED_UP

Key Dates & Times

• Slot generation: Daily 02:00 UTC (14 days ahead)
• Cleanup: Daily 02:30 UTC
• Membership check: Daily 03:00 UTC
• Booking completion: Daily 22:00 UTC
• Cancellation window: 2 hours before slot (configurable)

Key Files

• Slot generation: slot-generator.service.ts
• Slot queries: time-slot.service.ts
• Booking logic: booking.service.ts
• Database: prisma/schema.prisma