Architecture

info

This page covers the architecture of the Cal.com scheduling stack including component roles, data flow, and external integrations.

Meeting scheduling series

1. Meeting scheduling
2. Architecture - You are here
3. Manifests
4. Flux integration
5. Operations

Overview

The stack provides a complete scheduling solution with calendar integration, video conferencing, and email notifications.

Components

Cal.com

Cal.com is the scheduling engine that handles booking pages, availability management, and integrations.

Aspect	Configuration
Image	calcom/cal.com:v6.1.3
Port	3000
Database	PostgreSQL via Prisma ORM
Migrations	Init container on startup

PostgreSQL

PostgreSQL stores all Cal.com data including users, bookings, and configuration.

Aspect	Configuration
Image	postgres:16.4-alpine
Port	5432
Storage	NFS-backed PVC
Security context	fsGroup: 999

Cloudflare Tunnel

Cloudflare Tunnel provides secure ingress without exposing ports to the internet.

Aspect	Configuration
Hostname	cal.example.com
Service	https://ingress-nginx-controller.ingress-nginx.svc.cluster.local:443
Origin CA	Cluster-issued certificate

External integrations

Cal.com connects to external services for calendar sync, video meetings, and email.

Google Calendar

Aspect	Details
Purpose	Read availability, create events
Auth	OAuth 2.0 with refresh tokens
Scopes	calendar.events, calendar.readonly
Callback	https://cal.example.com/api/integrations/googlecalendar/callback

Zoom

Aspect	Details
Purpose	Auto-generate meeting links
Auth	OAuth 2.0
Scopes	meeting:write
Callback	https://cal.example.com/api/integrations/zoomvideo/callback

Email via shared email-relay

Aspect	Details
Purpose	Confirmation and reminder emails
Namespace	email-relay (shared infrastructure)
Components	mx-validator → Mailpit → smtp2graph
MX validation	Rejects emails to domains without MX records
Auth	Microsoft Graph API OAuth (modern authentication)
Why	Microsoft Security Defaults blocks SMTP AUTH (legacy)

The email-relay is shared infrastructure used by multiple applications. See Email relay for deployment details.

Data flow

Booking flow

OAuth callback flow

OAuth integrations require the public URL to be reachable before configuration.

This creates a two-phase deployment requirement:

1. Deploy Cal.com first (get domain live)
2. Configure OAuth redirect URLs after domain is reachable

Access methods

URL	Purpose	Route
https://cal.example.com	Public bookings	Cloudflare Tunnel → ingress → ClusterIP
http://cal.example.local:3000	Internal admin	LoadBalancer service (LAN only)

OAuth callbacks always redirect to the public URL. The internal URL is for admin tasks and bypasses Cloudflare WAF rules.

Resource requirements

Component	Memory	Storage	Replicas
Cal.com	~512MB	-	1
PostgreSQL	~256MB	5Gi	1

Total estimates:

• Memory: ~768MB
• Storage: ~5Gi

Namespace layout

The namespace contains Cal.com resources with dependencies on:

• ingress-nginx namespace for ingress controller
• email-relay namespace for email delivery

Spam protection

Cal.com is protected by multiple layers that prevent spam bookings and unauthorized access.

Protection layers

Layer	Protection	Blocks
Cloudflare WAF	Block /signup, /auth paths	Unauthorized account creation
Cloudflare IP Rules	Admin path allowlist	Unauthorized admin access
MX Validator	DNS MX record lookup	Fake email domains
Email Verification	Requires email round-trip	Unverified bookers

How MX validation works

When Cal.com sends a confirmation email:

1. Email goes to email-relay.email-relay.svc.cluster.local:25
2. mx-validator extracts the recipient domain
3. DNS lookup checks for MX records
4. If no MX records exist, email is rejected with 550 error
5. Cal.com receives the rejection, blocking the booking confirmation

Combined with Cal.com's "Requires booker email verification" setting, this prevents bookings from fake or non-existent email addresses. See Operations for configuration details.