Automated Booking System Architecture: Synchronizing Custom Calendars with Google Calendar API

For service firms, consulting practices, and medical clinics, offering a self-serve appointment scheduling portal is an effective way to improve bookings. While widgets like Calendly or Acuity offer basic setups, they are difficult to customize and require recurring subscription fees.

By building a custom booking system integrated directly with the Google Calendar API, you retain control of the customer database, eliminate brand distraction, and avoid third-party costs.

This engineering guide provides the system architecture blueprint to handle OAuth 2.0 authentication, listen for booking slot availability, and handle real-time sync.

1. System Architecture Diagram

A custom booking system needs to reconcile database records with the consultant's Google Calendar.

• Frontend: Visitor views a grid of available time slots.
• Database: Holds booking status, consultant schedules, and reservation records.
• Google Calendar API: Confirms availability, blocks slots, and sends invites.
• Webhook Sync: Syncs event updates when a consultant manually reschedules in Google Calendar.

2. Handling OAuth 2.0 for Calendar Access

To read and write to a consultant's Google Calendar, your application must obtain access and refresh tokens using Google's OAuth 2.0 flow.

Obtaining Tokens:

Store the returned refresh_token in a secure database table. Your app will use this token to generate short-lived access_token parameters dynamically:

`javascript

import { google } from "googleapis";

const oauth2Client = new google.auth.OAuth2(

process.env.GOOGLE_CLIENT_ID,

process.env.GOOGLE_CLIENT_SECRET,

process.env.GOOGLE_REDIRECT_URL

);

// Retrieve access token using stored refresh token

oauth2Client.setCredentials({

refresh_token: process.env.GOOGLE_REFRESH_TOKEN

});

`

3. Querying Availability (Preventing Double Booking)

Before showing open slots to a visitor, check the Google Calendar API for existing events to prevent double-booking.

`javascript

async function checkAvailability(timeStart, timeEnd) {

const calendar = google.calendar({ version: "v3", auth: oauth2Client });

const response = await calendar.freebusy.query({

requestBody: {

timeMin: timeStart,

timeMax: timeEnd,

items: [{ id: "primary" }] // Primary Google Calendar

}

});

const busySlots = response.data.calendars.primary.busy;

return busySlots.length === 0; // Returns true if slot is empty

}

`

4. Writing Bookings to Google Calendar

Once the user completes the booking form (and payment, if integrated), write the event directly to Google Calendar and attach a video meeting link automatically:

`javascript

async function createCalendarEvent(bookingDetails) {

const calendar = google.calendar({ version: "v3", auth: oauth2Client });

const event = {

summary: Consultation: ${bookingDetails.clientName},

description: bookingDetails.notes,

start: { dateTime: bookingDetails.startTime, timeZone: "Asia/Colombo" },

end: { dateTime: bookingDetails.endTime, timeZone: "Asia/Colombo" },

attendees: [{ email: bookingDetails.clientEmail }],

conferenceData: {

createRequest: {

requestId: "secure-booking-id-" + Date.now(),

conferenceSolutionKey: { type: "hangoutsMeet" } // Automatically attaches Google Meet link

}

}

};

const response = await calendar.events.insert({

calendarId: "primary",

resource: event,

conferenceDataVersion: 1,

sendUpdates: "all" // Sends calendar invite and meeting details to client

});

return response.data;

}

`

5. Syncing Backwards (Google Calendar to Website)

If a consultant deletes or reschedules a meeting directly inside their Google Calendar mobile app, the website database must update to match.

Setting Up a Watch Channel:

Use Google Calendar's Watch API to establish a push notification channel that sends POST webhooks to your server when changes occur:

`javascript

async function registerCalendarWebhook() {

const calendar = google.calendar({ version: "v3", auth: oauth2Client });

await calendar.events.watch({

calendarId: "primary",

requestBody: {

id: "unique-watch-channel-id",

type: "web_hook",

address: "https://yourdomain.com/api/webhooks/calendar-sync"

}

});

}

`

Building your booking tool around Google's API ensures that schedules are updated in real-time, bookings are confirmed instantly, and operations run smoothly without external platform subscriptions.