# unmesh-varade/calstudio architecture

> Architecture diagram of the GitHub repository unmesh-varade/calstudio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unmesh-varade/calstudio
- Repository: https://github.com/unmesh-varade/calstudio

## Overview

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: [`frontend/src/app/router.jsx`](https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/app/router.jsx) (Router), [`backend/src/services/booking.service.js`](https://github.com/unmesh-varade/calstudio/blob/main/backend/src/services/booking.service.js) (Booking engine), [`backend/src/db/prisma.js`](https://github.com/unmesh-varade/calstudio/blob/main/backend/src/db/prisma.js) (Prisma client), [`frontend/src/pages/public-booking-page.jsx`](https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/pages/public-booking-page.jsx) (Public pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React/Vite entry<br/>[main.jsx]"]
  node_frontend_router["Router<br/>navigation<br/>[router.jsx]"]
  node_frontend_layouts["Layouts<br/>shells"]
  node_frontend_pages_public["Public pages<br/>screens"]
  node_frontend_pages_admin["Dashboard pages<br/>screens"]
  node_frontend_booking_ui["Booking UI<br/>components"]
  node_frontend_features["Domain forms<br/>feature modules"]
  node_frontend_api["API client<br/>[api.js]"]
  node_frontend_time["Time helpers<br/>date/time utils<br/>[timezones.js]"]
end

subgraph group_backend["Backend"]
  node_backend_app["Express app<br/>API bootstrap<br/>[app.js]"]
  node_backend_routes["API routes<br/>routing<br/>[index.js]"]
  node_backend_validations["Validations<br/>request schemas"]
  node_backend_controllers["Controllers<br/>HTTP handlers"]
  node_backend_services_admin["Admin services<br/>business logic<br/>[admin.service.js]"]
  node_backend_services_booking["Booking engine<br/>scheduling logic<br/>[booking.service.js]"]
  node_backend_notifications["Notifications<br/>email pipeline"]
  node_backend_utils["Scheduling utils<br/>time rules<br/>[scheduling.js]"]
  node_backend_prisma[("Prisma client<br/>db access<br/>[prisma.js]")]
end

subgraph group_data["Persistence"]
  node_backend_schema["Schema & migrations<br/>PostgreSQL model<br/>[schema.prisma]"]
end

node_frontend_app -->|"uses"| node_frontend_router
node_frontend_router -->|"wraps"| node_frontend_layouts
node_frontend_router -->|"serves"| node_frontend_pages_public
node_frontend_router -->|"serves"| node_frontend_pages_admin
node_frontend_pages_public -->|"composes"| node_frontend_booking_ui
node_frontend_pages_admin -->|"uses"| node_frontend_features
node_frontend_booking_ui -->|"formats"| node_frontend_time
node_frontend_pages_public -->|"fetches"| node_frontend_api
node_frontend_pages_admin -->|"fetches"| node_frontend_api
node_backend_app -->|"mounts"| node_backend_routes
node_backend_routes -->|"guards"| node_backend_validations
node_backend_routes -->|"dispatches"| node_backend_controllers
node_backend_controllers -->|"calls"| node_backend_services_admin
node_backend_controllers -->|"calls"| node_backend_services_booking
node_backend_services_admin -->|"persists"| node_backend_prisma
node_backend_services_booking -->|"uses"| node_backend_utils
node_backend_services_booking -->|"reads/writes"| node_backend_prisma
node_backend_services_booking -->|"triggers"| node_backend_notifications
node_backend_notifications -->|"reads"| node_backend_prisma
node_backend_prisma -->|"implements"| node_backend_schema
node_backend_validations -->|"shares"| node_backend_utils

click node_frontend_app "https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/main.jsx"
click node_frontend_router "https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/app/router.jsx"
click node_frontend_layouts "https://github.com/unmesh-varade/calstudio/tree/main/frontend/src/layouts"
click node_frontend_pages_public "https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/pages/public-booking-page.jsx"
click node_frontend_pages_admin "https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/pages/dashboard-event-types-page.jsx"
click node_frontend_booking_ui "https://github.com/unmesh-varade/calstudio/tree/main/frontend/src/components/booking"
click node_frontend_features "https://github.com/unmesh-varade/calstudio/tree/main/frontend/src/features"
click node_frontend_api "https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/lib/api.js"
click node_frontend_time "https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/lib/timezones.js"
click node_backend_app "https://github.com/unmesh-varade/calstudio/blob/main/backend/src/app.js"
click node_backend_routes "https://github.com/unmesh-varade/calstudio/blob/main/backend/src/routes/index.js"
click node_backend_validations "https://github.com/unmesh-varade/calstudio/tree/main/backend/src/validations"
click node_backend_controllers "https://github.com/unmesh-varade/calstudio/tree/main/backend/src/controllers"
click node_backend_services_admin "https://github.com/unmesh-varade/calstudio/blob/main/backend/src/services/admin.service.js"
click node_backend_services_booking "https://github.com/unmesh-varade/calstudio/blob/main/backend/src/services/booking.service.js"
click node_backend_notifications "https://github.com/unmesh-varade/calstudio/blob/main/backend/src/services/booking-notification.service.js"
click node_backend_utils "https://github.com/unmesh-varade/calstudio/blob/main/backend/src/utils/scheduling.js"
click node_backend_prisma "https://github.com/unmesh-varade/calstudio/blob/main/backend/src/db/prisma.js"
click node_backend_schema "https://github.com/unmesh-varade/calstudio/blob/main/backend/prisma/schema.prisma"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_router,node_frontend_layouts,node_frontend_pages_public,node_frontend_pages_admin,node_frontend_booking_ui,node_frontend_features,node_frontend_api,node_frontend_time toneBlue
class node_backend_app,node_backend_routes,node_backend_validations,node_backend_controllers,node_backend_services_admin,node_backend_services_booking,node_backend_notifications,node_backend_utils,node_backend_prisma toneAmber
class node_backend_schema toneMint
```

## Components

### Frontend

React/Vite app for public booking and admin dashboard

- [App shell](https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/main.jsx): React/Vite entry · Bootstraps providers, router, and global app wiring · `frontend/src/main.jsx`
- [Router](https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/app/router.jsx): navigation · Defines route structure for public and dashboard flows · `frontend/src/app/router.jsx`
- [Layouts](https://github.com/unmesh-varade/calstudio/tree/main/frontend/src/layouts): shells · Marketing and dashboard shells shared across screens · `frontend/src/layouts`
- [Public pages](https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/pages/public-booking-page.jsx): screens · Booking, profile, cancel, and reschedule user-facing pages · `frontend/src/pages/public-booking-page.jsx`
- [Dashboard pages](https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/pages/dashboard-event-types-page.jsx): screens · Admin screens for event types, availability, bookings, and rescheduling · `frontend/src/pages/dashboard-event-types-page.jsx`
- [Booking UI](https://github.com/unmesh-varade/calstudio/tree/main/frontend/src/components/booking): components · Date, timezone, questions, slots, and summary panels · `frontend/src/components/booking`
- [Domain forms](https://github.com/unmesh-varade/calstudio/tree/main/frontend/src/features): feature modules · Feature-oriented forms for event types and availability · `frontend/src/features`
- [API client](https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/lib/api.js): client · Frontend server-state access and request helpers · `frontend/src/lib/api.js`
- [Time helpers](https://github.com/unmesh-varade/calstudio/blob/main/frontend/src/lib/timezones.js): date/time utils · Timezone and date utilities used across booking flows · `frontend/src/lib/timezones.js`

### Backend

Express API, scheduling logic, persistence, and notifications

- [Express app](https://github.com/unmesh-varade/calstudio/blob/main/backend/src/app.js): API bootstrap · Wires middleware, routes, and error handling · `backend/src/app.js`
- [API routes](https://github.com/unmesh-varade/calstudio/blob/main/backend/src/routes/index.js): routing · Route composition for health, admin, and public endpoints · `backend/src/routes/index.js`
- [Validations](https://github.com/unmesh-varade/calstudio/tree/main/backend/src/validations): request schemas · Zod-style request validation for admin and booking inputs · `backend/src/validations`
- [Controllers](https://github.com/unmesh-varade/calstudio/tree/main/backend/src/controllers): HTTP handlers · Translate requests into service calls for each API concern · `backend/src/controllers`
- [Admin services](https://github.com/unmesh-varade/calstudio/blob/main/backend/src/services/admin.service.js): business logic · Event type, availability, and admin booking workflows · `backend/src/services/admin.service.js`
- [Booking engine](https://github.com/unmesh-varade/calstudio/blob/main/backend/src/services/booking.service.js): scheduling logic · Slot generation, overlap checks, booking state, and serializer · `backend/src/services/booking.service.js`
- [Notifications](https://github.com/unmesh-varade/calstudio/blob/main/backend/src/services/booking-notification.service.js): email pipeline · Booking lifecycle email orchestration and SMTP delivery · `backend/src/services/booking-notification.service.js`
- [Scheduling utils](https://github.com/unmesh-varade/calstudio/blob/main/backend/src/utils/scheduling.js): time rules · Shared scheduling, time conversion, and HTTP error helpers · `backend/src/utils/scheduling.js`
- [Prisma client](https://github.com/unmesh-varade/calstudio/blob/main/backend/src/db/prisma.js): db access · Database access layer used by services and repositories · `backend/src/db/prisma.js`

### Persistence

Prisma schema, migrations, and seed/cleanup scripts

- [Schema & migrations](https://github.com/unmesh-varade/calstudio/blob/main/backend/prisma/schema.prisma): PostgreSQL model · Prisma schema, migrations, seed, and clear scripts · `backend/prisma/schema.prisma`

## Connections

- 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