How unmesh-varade/calstudio works
1. High-level shape
- CalStudio is a two-part system: a React frontend and an Express backend.
- The frontend handles both the admin dashboard and the public booking experience.
- The backend owns all scheduling rules, booking state, persistence, and email notifications.
2. Frontend boundary
- The frontend is a Vite app using React Router for navigation and TanStack Query for server-state fetching/caching.
- Its structure is feature-oriented: pages for route screens, layouts for major shells, features for domain-specific forms, components for reusable UI, and lib for API/timezone helpers.
- This separation keeps booking flows and dashboard flows in the same app but with distinct screens and shared primitives.
3. Backend boundary
- The backend is a layered Express API with routes → controllers → services → Prisma database access.
- validations use Zod-style request validation before controllers execute.
- middleware covers request validation, 404 handling, and error normalization.
- utils contain shared scheduling/time helpers and HTTP error types.
4. Persistence and schema
- PostgreSQL is the system of record, accessed through Prisma.
- The schema is evolved through Prisma migrations under backend/prisma/migrations.
- Seed and cleanup scripts exist, which suggests the repo is designed for repeatable local setup and controlled test data.
5. Core domain model
- The main domain revolves around a single organizer profile, event types, availability rules, bookings, booking questions, and answers.
- Event types define duration, buffer time, slug, title/description, and custom booking questions.
- Availability is stored separately from event types, so schedule rules can be reused across multiple event types.
6. Scheduling and slot generation
- Scheduling logic is concentrated in backend services and utilities rather than the UI.
- Timezone-aware slot computation uses the organizer’s schedule timezone, while bookings are stored in UTC.
- The backend filters out existing bookings, applies buffer windows, and prevents overlap before exposing slots or creating a booking.
- This is the most important architectural boundary because it protects correctness across public booking and rescheduling flows.
7. Admin workflows
- Admin API routes cover event-type CRUD, availability updates, booking listing, booking cancellation, admin-initiated rescheduling, and “request-reschedule” flows.
- The frontend dashboard pages mirror those capabilities: event types, availability, bookings, and booking detail/reschedule screens.
- The backend’s admin.service, booking.service, availability.service, and event-type.service likely encapsulate the business rules behind those screens.
8. Public booking workflows
- Public routes expose a profile page, event-type detail page, available slots, booking creation, confirmation, and manage-booking actions.
- Guest actions use secure booking tokens for cancellation and rescheduling, which creates a separate boundary from admin actions.
- The frontend public pages and booking components guide the user through date selection, timezone selection, question answering, and final confirmation.
9. Notification pipeline
- Booking lifecycle events trigger email notifications through a dedicated email service plus a booking-notification service.
- The repo supports confirmation, cancellation, reschedule confirmation, and request-reschedule emails.
- SMTP is the only external delivery dependency mentioned, so notification sending is an internal backend concern with environment-based configuration.
10. API organization
- Routes are grouped by concern: health, event types, availability, bookings, and public booking endpoints.
- This yields a clean separation between admin API surface and public API surface.
- The public routes are especially important architecturally because they serve unauthenticated user flows while still operating on token-protected booking records.
11. Operational setup and deployment
- The frontend is deployed to Vercel, while the backend runs as a hosted Node/Express service.
- The frontend talks to the backend through VITE_API_BASE_URL; the backend is configured with DATABASE_URL, CORS origin, and SMTP settings.
- No external calendar provider is integrated, so all availability and booking coordination stays inside this application and its database.
12. Testing focus
- The repo includes backend tests for scheduling behavior, which is consistent with scheduling being the riskiest part of the system.
- That implies architecture validation is centered on time/slot correctness rather than UI snapshot testing.
Main entry points: router.jsx Router · booking.service.js Booking engine · prisma.js Prisma client · public-booking-page.jsx Public pages
Components 19
Frontend
React/Vite app for public booking and admin dashboard
- App shell · Bootstraps providers, router, and global app wiring
frontend/src/main.jsx - Router · Defines route structure for public and dashboard flows
frontend/src/app/router.jsx - Layouts · Marketing and dashboard shells shared across screens
frontend/src/layouts - Public pages · Booking, profile, cancel, and reschedule user-facing pages
frontend/src/pages/public-booking-page.jsx - Dashboard pages · Admin screens for event types, availability, bookings, and rescheduling
frontend/src/pages/dashboard-event-types-page.jsx - Booking UI · Date, timezone, questions, slots, and summary panels
frontend/src/components/booking - Domain forms · Feature-oriented forms for event types and availability
frontend/src/features - API client · Frontend server-state access and request helpers
frontend/src/lib/api.js - Time helpers · Timezone and date utilities used across booking flows
frontend/src/lib/timezones.js
Backend
Express API, scheduling logic, persistence, and notifications
- Express app · Wires middleware, routes, and error handling
backend/src/app.js - API routes · Route composition for health, admin, and public endpoints
backend/src/routes/index.js - Validations · Zod-style request validation for admin and booking inputs
backend/src/validations - Controllers · Translate requests into service calls for each API concern
backend/src/controllers - Admin services · Event type, availability, and admin booking workflows
backend/src/services/admin.service.js - Booking engine · Slot generation, overlap checks, booking state, and serializer
backend/src/services/booking.service.js - Notifications · Booking lifecycle email orchestration and SMTP delivery
backend/src/services/booking-notification.service.js - Scheduling utils · Shared scheduling, time conversion, and HTTP error helpers
backend/src/utils/scheduling.js - Prisma client · Database access layer used by services and repositories
backend/src/db/prisma.js
Persistence
Prisma schema, migrations, and seed/cleanup scripts
- Schema & migrations · Prisma schema, migrations, seed, and clear scripts
backend/prisma/schema.prisma
Connections 21
- App shell → Router: uses · App entry mounts routing and providers
- Router → Layouts: wraps · Routes are organized by shell/layout
- Router → Public pages: serves · Public booking and profile flows
- Router → Dashboard pages: serves · Dashboard and management flows
- Public pages → Booking UI: composes · Public flows use shared booking widgets
- Dashboard pages → Domain forms: uses · Admin screens rely on feature forms
- Booking UI → Time helpers: formats · Booking widgets use timezone/date helpers
- Public pages → API client: fetches · Public pages call backend APIs for slots and booking actions
- Dashboard pages → API client: fetches · Dashboard screens call backend APIs for CRUD and actions
- Express app → API routes: mounts · Express app mounts API route groups
- API routes → Validations: guards · Routes apply request validation before handlers
- API routes → Controllers: dispatches · Routes map to HTTP controllers
- Controllers → Admin services: calls · Admin endpoints delegate domain work to services
- Controllers → Booking engine: calls · Booking endpoints delegate slot and booking logic
- Admin services → Prisma client: persists · Admin logic reads and writes through Prisma
- Booking engine → Scheduling utils: uses · Scheduling rules depend on shared time helpers
- Booking engine → Prisma client: reads/writes · Booking engine checks availability and stores bookings
- Booking engine → Notifications: triggers · Booking lifecycle events emit email notifications
- Notifications → Prisma client: reads · Notification flows can inspect booking state
- Prisma client → Schema & migrations: implements · Prisma client is backed by schema and migrations
- Validations → Scheduling utils: shares · Validation may reuse common error/time helpers