Clinical SaaS & Booking Automation with Native OAuth Calendar Sync and Atomic Lead Conversion

The Bottleneck

Psychologists, therapists, and zootherapy clinics historically relied on generic tools, spreadsheets, and disjointed software to manage appointment schedules, clinical histories, and lead intake. This created severe operational bottlenecks: real-time availability was impossible to calculate accurately, leading to double-bookings and scheduling gaps that eroded patient trust. Manual data duplication between web-form leads and clinical patient files consumed administrative hours and introduced transcription errors. Clinical notes existed in silos across unstructured documents, compromising longitudinal tracking of psychological histories, medications, and session progress.

Meanwhile, static websites with no optimized rendering, schema markup, or local SEO metadata left these practices invisible to high-intent regional search queries, driving up Customer Acquisition Cost (CAC) and forcing reliance on expensive offline referral networks.

Architecture & Automation

The platform is engineered as a monolithic SaaS on Laravel 12 and PHP 8.2, using a dual-database strategy (SQLite for local rapid testing, MySQL for production persistence on a VPS). The monolith choice eliminates inter-service network latency, guarantees ACID transactional integrity, and minimizes deployment cost—critical for small clinical practices operating on lean infrastructure budgets.

Dynamic SSR Interface: Built with Laravel Breeze, Tailwind CSS 3, and AlpineJS. Pages are server-side rendered with minimal JavaScript bundles, keeping Largest Contentful Paint (LCP) and Interaction to Next Paint (INP) low without the runtime overhead of a full SPA framework.

Native Event-Driven Calendar Sync: Rather than relying on heavy third-party vendor packages, synchronization is handled natively. An Eloquent observer on the Appointment model hooks into created, updated, and deleted events to invoke GoogleCalendarService. This service manages the full OAuth 2.0 flow, refresh token rotation (with a 5-minute pre-expiration safety margin), and direct REST payloads to the Google Calendar API. This eliminates vendor abstraction bloat and keeps token lifecycle logic inside the application boundary.

Atomic Lead-to-Patient Conversion Pipeline: The LeadController encapsulates the prospect-to-patient transition inside a database transaction (DB::beginTransaction()). When a lead is marked converted, the system atomically instantiates a new Patient profile, migrates lead notes, locates matching services (with intelligent fallbacks), registers a confirmed Appointment in the linked Google Calendar, and flips the lead status to converted. This ensures zero data loss, no orphan records, and no partial state exposure under failure.

Asynchronous Lead Ingestion: The application exposes webhook endpoints for external automation:

• /api/webhook/n8n: Direct integration with n8n workflows for parsing and storing lead data from advertising funnels.
• /api/webhook/whatsapp: Ingests incoming communication logs and delivery status hooks.

Custom Availability Engine: The /api/disponibilidad/{user}/{date} endpoint calculates free slots in real time. It fetches availability configurations for the requested day of the week and applies an array_diff against existing bookings (requested_time on leads plus confirmed appointments), returning a precise list of open windows to the booking UI.

Comprehensive Clinical Vault: The relational schema captures deep clinical context: psychiatric_history, medical_conditions, current_medication, reason_for_consultation, and per-session progress reports through the patient_sessions table. Eloquent eager loading (Patient::with('appointments'), Lead::with('specialist')) prevents N+1 query execution patterns on dashboard and detail views.

Honeypot Anti-Spam Layer: PublicController@storeLead includes a hidden _honeypot field. Automated bots populating this trap are blocked immediately with a 403 HTTP status, eliminating the need for friction-inducing CAPTCHA widgets and preserving public form conversion rates on mobile devices.

Performance & Local SEO Stack: PHP OPcache and Laravel configuration caching are enabled in production to minimize TTFB. Dynamic routing in PublicController maps specific therapy categories to specialized SEO metadata (custom titles, meta descriptions, FAQ sections, and icons), targeting local intent for the "Guacara, Carabobo" region to lower organic CAC.

┌─────────────┐     ┌──────────────────────────────────────────────┐
│   Patient   │────▶│         Laravel 12 Monolith                  │
│  (Browser)  │     │  (PHP 8.2 / Tailwind 3 / AlpineJS / Breeze) │
└─────────────┘     │                                              │
                    │  ┌─────────┐ ┌─────────┐ ┌─────────────┐   │
                    │  │  Lead   │ │ Patient │ │ Appointment │   │
                    │  │  Model  │ │ Model   │ │   Model     │   │
                    │  │+Webhook │ │+Sessions│ │+Observer    │   │
                    │  │ Ingest  │ │+History │ │+Calendar    │   │
                    │  └────┬────┘ └────┬────┘ └──────┬──────┘   │
                    └───────┼───────────┼─────────────┼──────────┘
                            │           │             │
              ┌─────────────┘           │             │
              ▼                         ▼             ▼
       ┌──────────────┐        ┌────────────────┐  ┌─────────────┐
       │   MySQL      │        │ Google Calendar│  │     n8n     │
       │ (Production) │        │ API (OAuth 2.0)│  │  Webhook    │
       │              │        │+ Token Refresh │  │  Ingestion  │
       └──────────────┘        └────────────────┘  └─────────────┘
       
       ┌──────────────┐
       │   SQLite     │
       │  (Local/Dev) │
       └──────────────┘

Measurable ROI

Scheduling Conflicts:

Manual calendar cross-referencing and generic booking tools → Real-time availability API with array_diff slot calculation against active bookings.

• Before: 15–20% double-booking rate and frequent scheduling gaps causing patient no-shows.
• After: Zero double-bookings; slots exposed dynamically to the public booking surface with real-time accuracy.

Lead-to-Patient Onboarding:

Manual transcription of web-form data into clinical files → Atomic LeadController transaction with auto-provisioned Patient profile, calendar event, and service mapping.

• Before: 10–15 minutes of administrative data entry per new patient; frequent transcription errors and duplicate records.
• After: <2 seconds atomic conversion with zero orphan records and guaranteed calendar sync.

Clinical Data Integrity:

Fragmented notes across unstructured documents and spreadsheets → Centralized relational vault with patient_sessions, psychological history, medication tracking, and session progress reports.

• Before: Inability to run longitudinal analysis or retrieve full patient context quickly; compliance risk from missing records.
• After: Complete clinical timeline accessible in a single eager-loaded query.

Public Form Conversion:

Visible CAPTCHA challenges adding friction to lead capture → Hidden honeypot field blocking bots with an immediate 403.

• Before: CAPTCHA drop-off rates of 5–10% on mobile devices, directly reducing funnel throughput.
• After: Zero visible friction; spam blocked at the controller layer without user intervention.

Local SEO Visibility:

Static HTML with no schema or localized metadata → Dynamic therapy-category routing with tailored titles, meta descriptions, and FAQ structures for regional therapeutic intent.

• Before: Near-zero organic visibility for local therapy searches in the target region.
• After: Search-engine optimized surface targeting specific local modalities, driving measurable organic impression growth and reducing paid acquisition dependency.

Calendar Sync Reliability:

Manual appointment entry into Google Calendar with no bidirectional sync → Native OAuth 2.0 integration with 5-minute token pre-refresh and event lifecycle hooks.

• Before: Missed appointments due to stale calendar state and manual update lag.
• After: Real-time, bidirectional sync with automated token lifecycle management and fault-tolerant refresh logic.