# singhsanket143/calendlyproject architecture

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

- Interactive diagram: https://gitdiagram.com/singhsanket143/calendlyproject
- Repository: https://github.com/singhsanket143/calendlyproject

## Overview

#### Purpose and entry points
This is a TypeScript backend for scheduling: users define event types and availability, generate bookable slots, accept bookings, and trigger calendar/notification workflows. Process startup is split between HTTP server/bootstrap and Temporal worker runtime: `src/server.ts`, `src/app.ts`, `src/temporal/worker.ts`.

#### HTTP API composition
`src/app.ts` assembles Express middleware and feature routers. Route groups isolate user management, availability, event types, bookings, Google integration, and public event booking surfaces: `src/routers/user.router.ts`, `src/routers/booking.router.ts`, `src/routers/public-event.router.ts`. Request validation, user-ID enforcement, and centralized error/not-found handling form the API boundary: `src/middlewares/validate.ts`, `src/middlewares/require-user-id.ts`, `src/middlewares/error-handler.ts`.

#### Scheduling domain and persistence
The durable domain is modeled in Prisma and evolved through migrations, covering users, event types, availability rules/exceptions, slots, and bookings: `prisma/schema.prisma`, `prisma/migrations/20260627172340_added_slots/migration.sql`, `prisma/migrations/20260627172950_added_bookings/migration.sql`. Repositories are the database access boundary, separating services from Prisma/client implementation: `src/repositories/db-client.ts`, `src/repositories/availability.repository.ts`, `src/repositories/booking.repository.ts`.

#### Availability-to-slot pipeline
Availability APIs feed availability service logic, which combines rules and exceptions and delegates slot materialization/generation. Slots have distinct repository and service layers, indicating generated availability is persisted and then queried independently for booking: `src/services/availability.service.ts`, `src/services/slot-generation.service.ts`, `src/services/slot.service.ts`. Generation is also represented as a Temporal workflow, allowing it to run outside the request lifecycle: `src/temporal/workflows/slot-generation.workflow.ts`.

#### Booking orchestration
Booking requests enter controllers/routes, pass DTO validation, and are orchestrated through the booking service into booking and slot persistence. The likely transactional boundary is preventing a slot from remaining available once booked; implementation responsibility is concentrated in `src/services/booking.service.ts`, `src/repositories/booking.repository.ts`, and `src/repositories/slot.repository.ts`. Booking completion initiates asynchronous notification/calendar work rather than coupling those integrations directly to HTTP responses.

#### External integrations and asynchronous runtime
Temporal provides workflow execution for slot generation, booking notification, and Google Calendar operations; worker/client configuration bridges application code to the Temporal service: `src/temporal/client.ts`, `src/temporal/workflows/booking-notification.workflow.ts`, `src/temporal/workflows/google-calendar.workflow.ts`. Google setup and calendar service form the calendar provider boundary: `src/utils/google-setup.ts`, `src/services/google-calender.service.ts`. Email notifications use a Nodemailer configuration and booking-specific mailer: `src/config/nodemailer.ts`, `src/mailer/booking.mailer.ts`. Local infrastructure is represented by `docker-compose.yml` and Temporal dynamic configuration under `temporal/dynamicConfig/development-sql.yaml`.

Main entry points: [`src/services/booking.service.ts`](https://github.com/singhsanket143/calendlyproject/blob/main/src/services/booking.service.ts) (Booking service), [`src/services/availability.service.ts`](https://github.com/singhsanket143/calendlyproject/blob/main/src/services/availability.service.ts) (Availability service), [`src/repositories/slot.repository.ts`](https://github.com/singhsanket143/calendlyproject/blob/main/src/repositories/slot.repository.ts) (Slot repository), [`src/temporal/worker.ts`](https://github.com/singhsanket143/calendlyproject/blob/main/src/temporal/worker.ts) (Temporal worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_server["Server bootstrap<br/>startup<br/>[server.ts]"]
  node_app["Express app<br/>api composition<br/>[app.ts]"]
  node_api_boundary["API boundary middleware<br/>[validate.ts]"]
  node_user_routes["User routes<br/>router<br/>[user.router.ts]"]
  node_event_booking_routes["Booking surfaces<br/>routers<br/>[booking.router.ts]"]
end

subgraph group_scheduling["Scheduling Domain"]
  node_availability_service["Availability service<br/>domain service"]
  node_booking_service{{"Booking service<br/>orchestrator<br/>[booking.service.ts]"}}
  node_slot_generation_service["Slot generation<br/>domain service"]
  node_slot_service["Slot service<br/>domain service<br/>[slot.service.ts]"]
  node_availability_repository["Availability repository"]
  node_booking_repository["Booking repository"]
  node_slot_repository["Slot repository<br/>[slot.repository.ts]"]
  node_prisma[("Scheduling database<br/>Prisma schema<br/>[schema.prisma]")]
end

subgraph group_async["Async Workflows"]
  node_temporal_client["Temporal client<br/>workflow client<br/>[client.ts]"]
  node_temporal_worker["Temporal worker<br/>worker runtime<br/>[worker.ts]"]
  node_slot_workflow["Slot generation workflow<br/>Temporal workflow"]
  node_notification_workflow["Booking notification workflow<br/>Temporal workflow"]
  node_calendar_workflow["Google Calendar workflow<br/>Temporal workflow"]
end

subgraph group_integrations["External Integrations"]
  node_calendar_service["Google Calendar service<br/>provider service"]
  node_booking_mailer["Booking mailer<br/>notification adapter<br/>[booking.mailer.ts]"]
end

node_server -->|"starts"| node_app
node_app -->|"applies"| node_api_boundary
node_api_boundary -->|"guards"| node_user_routes
node_api_boundary -->|"guards"| node_event_booking_routes
node_user_routes -->|"manages availability"| node_availability_service
node_event_booking_routes -->|"books slots"| node_booking_service
node_availability_service -->|"reads rules"| node_availability_repository
node_availability_service -->|"generates slots"| node_slot_generation_service
node_slot_generation_service -->|"persists slots"| node_slot_repository
node_slot_service -->|"queries slots"| node_slot_repository
node_booking_service -->|"checks availability"| node_slot_service
node_booking_service -->|"creates booking"| node_booking_repository
node_booking_service -->|"reserves slot"| node_slot_repository
node_availability_repository -->|"accesses"| node_prisma
node_booking_repository -->|"accesses"| node_prisma
node_slot_repository -->|"accesses"| node_prisma
node_availability_service -.->|"starts generation"| node_temporal_client
node_booking_service -.->|"starts follow-up work"| node_temporal_client
node_temporal_worker -->|"executes"| node_slot_workflow
node_temporal_worker -->|"executes"| node_notification_workflow
node_temporal_worker -->|"executes"| node_calendar_workflow
node_slot_workflow -->|"materializes"| node_slot_generation_service
node_notification_workflow -->|"sends email"| node_booking_mailer
node_calendar_workflow -->|"syncs calendar"| node_calendar_service

click node_server "https://github.com/singhsanket143/calendlyproject/blob/main/src/server.ts"
click node_app "https://github.com/singhsanket143/calendlyproject/blob/main/src/app.ts"
click node_api_boundary "https://github.com/singhsanket143/calendlyproject/blob/main/src/middlewares/validate.ts"
click node_user_routes "https://github.com/singhsanket143/calendlyproject/blob/main/src/routers/user.router.ts"
click node_availability_service "https://github.com/singhsanket143/calendlyproject/blob/main/src/services/availability.service.ts"
click node_event_booking_routes "https://github.com/singhsanket143/calendlyproject/blob/main/src/routers/booking.router.ts"
click node_booking_service "https://github.com/singhsanket143/calendlyproject/blob/main/src/services/booking.service.ts"
click node_slot_generation_service "https://github.com/singhsanket143/calendlyproject/blob/main/src/services/slot-generation.service.ts"
click node_slot_service "https://github.com/singhsanket143/calendlyproject/blob/main/src/services/slot.service.ts"
click node_availability_repository "https://github.com/singhsanket143/calendlyproject/blob/main/src/repositories/availability.repository.ts"
click node_booking_repository "https://github.com/singhsanket143/calendlyproject/blob/main/src/repositories/booking.repository.ts"
click node_slot_repository "https://github.com/singhsanket143/calendlyproject/blob/main/src/repositories/slot.repository.ts"
click node_prisma "https://github.com/singhsanket143/calendlyproject/blob/main/prisma/schema.prisma"
click node_temporal_client "https://github.com/singhsanket143/calendlyproject/blob/main/src/temporal/client.ts"
click node_temporal_worker "https://github.com/singhsanket143/calendlyproject/blob/main/src/temporal/worker.ts"
click node_slot_workflow "https://github.com/singhsanket143/calendlyproject/blob/main/src/temporal/workflows/slot-generation.workflow.ts"
click node_notification_workflow "https://github.com/singhsanket143/calendlyproject/blob/main/src/temporal/workflows/booking-notification.workflow.ts"
click node_calendar_workflow "https://github.com/singhsanket143/calendlyproject/blob/main/src/temporal/workflows/google-calendar.workflow.ts"
click node_calendar_service "https://github.com/singhsanket143/calendlyproject/blob/main/src/services/google-calender.service.ts"
click node_booking_mailer "https://github.com/singhsanket143/calendlyproject/blob/main/src/mailer/booking.mailer.ts"

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_server,node_app,node_api_boundary,node_user_routes,node_event_booking_routes toneBlue
class node_availability_service,node_booking_service,node_slot_generation_service,node_slot_service,node_availability_repository,node_booking_repository,node_slot_repository,node_prisma toneAmber
class node_temporal_client,node_temporal_worker,node_slot_workflow,node_notification_workflow,node_calendar_workflow toneMint
class node_calendar_service,node_booking_mailer toneRose
```

## Components

### HTTP API

- [Server bootstrap](https://github.com/singhsanket143/calendlyproject/blob/main/src/server.ts): startup · `src/server.ts`
- [Express app](https://github.com/singhsanket143/calendlyproject/blob/main/src/app.ts): api composition · `src/app.ts`
- [API boundary middleware](https://github.com/singhsanket143/calendlyproject/blob/main/src/middlewares/validate.ts): middleware · Validation, user identity, and centralized error handling. · `src/middlewares/validate.ts`
- [User routes](https://github.com/singhsanket143/calendlyproject/blob/main/src/routers/user.router.ts): router · `src/routers/user.router.ts`
- [Booking surfaces](https://github.com/singhsanket143/calendlyproject/blob/main/src/routers/booking.router.ts): routers · Authenticated and public booking endpoints. · `src/routers/booking.router.ts`

### Scheduling Domain

- [Availability service](https://github.com/singhsanket143/calendlyproject/blob/main/src/services/availability.service.ts): domain service · Combines availability rules and exceptions. · `src/services/availability.service.ts`
- [Booking service](https://github.com/singhsanket143/calendlyproject/blob/main/src/services/booking.service.ts): orchestrator · Coordinates booking creation and slot reservation. · `src/services/booking.service.ts`
- [Slot generation](https://github.com/singhsanket143/calendlyproject/blob/main/src/services/slot-generation.service.ts): domain service · Materializes bookable slots from availability. · `src/services/slot-generation.service.ts`
- [Slot service](https://github.com/singhsanket143/calendlyproject/blob/main/src/services/slot.service.ts): domain service · Queries persisted bookable slots. · `src/services/slot.service.ts`
- [Availability repository](https://github.com/singhsanket143/calendlyproject/blob/main/src/repositories/availability.repository.ts): repository · `src/repositories/availability.repository.ts`
- [Booking repository](https://github.com/singhsanket143/calendlyproject/blob/main/src/repositories/booking.repository.ts): repository · `src/repositories/booking.repository.ts`
- [Slot repository](https://github.com/singhsanket143/calendlyproject/blob/main/src/repositories/slot.repository.ts): repository · `src/repositories/slot.repository.ts`
- [Scheduling database](https://github.com/singhsanket143/calendlyproject/blob/main/prisma/schema.prisma): Prisma schema · Users, event types, availability, slots, and bookings. · `prisma/schema.prisma`

### Async Workflows

- [Temporal client](https://github.com/singhsanket143/calendlyproject/blob/main/src/temporal/client.ts): workflow client · `src/temporal/client.ts`
- [Temporal worker](https://github.com/singhsanket143/calendlyproject/blob/main/src/temporal/worker.ts): worker runtime · `src/temporal/worker.ts`
- [Slot generation workflow](https://github.com/singhsanket143/calendlyproject/blob/main/src/temporal/workflows/slot-generation.workflow.ts): Temporal workflow · `src/temporal/workflows/slot-generation.workflow.ts`
- [Booking notification workflow](https://github.com/singhsanket143/calendlyproject/blob/main/src/temporal/workflows/booking-notification.workflow.ts): Temporal workflow · `src/temporal/workflows/booking-notification.workflow.ts`
- [Google Calendar workflow](https://github.com/singhsanket143/calendlyproject/blob/main/src/temporal/workflows/google-calendar.workflow.ts): Temporal workflow · `src/temporal/workflows/google-calendar.workflow.ts`

### External Integrations

- [Google Calendar service](https://github.com/singhsanket143/calendlyproject/blob/main/src/services/google-calender.service.ts): provider service · `src/services/google-calender.service.ts`
- [Booking mailer](https://github.com/singhsanket143/calendlyproject/blob/main/src/mailer/booking.mailer.ts): notification adapter · `src/mailer/booking.mailer.ts`

## Connections

- Server bootstrap → Express app: starts
- Express app → API boundary middleware: applies
- API boundary middleware → User routes: guards
- API boundary middleware → Booking surfaces: guards
- User routes → Availability service: manages availability
- Booking surfaces → Booking service: books slots
- Availability service → Availability repository: reads rules
- Availability service → Slot generation: generates slots
- Slot generation → Slot repository: persists slots
- Slot service → Slot repository: queries slots
- Booking service → Slot service: checks availability
- Booking service → Booking repository: creates booking
- Booking service → Slot repository: reserves slot
- Availability repository → Scheduling database: accesses
- Booking repository → Scheduling database: accesses
- Slot repository → Scheduling database: accesses
- Availability service → Temporal client: starts generation
- Booking service → Temporal client: starts follow-up work
- Temporal worker → Slot generation workflow: executes
- Temporal worker → Booking notification workflow: executes
- Temporal worker → Google Calendar workflow: executes
- Slot generation workflow → Slot generation: materializes
- Booking notification workflow → Booking mailer: sends email
- Google Calendar workflow → Google Calendar service: syncs calendar