SmartSchedule Healthcare — Enterprise AI-Powered Scheduling SaaS

Status

This case study documents an architecture in active development. The infrastructure is complete and the core scheduling API is being built. The aim here is to capture the engineering decisions made before a line of application code was written — the architecture, the tradeoffs, and the reasoning — because those decisions are harder to reconstruct after the fact.

The problem

Most clinics in East Africa coordinate appointments over WhatsApp. This works until it doesn't: a message gets missed, a reschedule isn't tracked, a patient shows up for a cancelled slot. The staff member who knows the schedule is on leave. There's no audit trail, no reminder system, and no visibility into patterns — which patients no-show, which slots are chronically underbooked, which providers are overloaded.

SmartSchedule replaces that with a centralised scheduling system. The MVP scope is deliberately narrow: reliably book, modify, and cancel appointments; deliver confirmations via channels clinics already use; produce an auditable event log. No AI no-show prediction in the MVP — that comes after the core scheduling loop is proven.

Architecture

Three services, each with a single responsibility:

Scheduling API — the core. REST and event interfaces for appointment lifecycle management. Built for idempotency: every mutation is safe to retry. Every state change emits an event to Azure Service Bus for downstream consumers.

Identity Service — OAuth2-compatible, supporting Azure AD B2C for clinic staff SSO and a lightweight local provider for patient accounts. Patients shouldn't need an enterprise identity provider to book an appointment.

Notification Service — consumes scheduling events from Service Bus and handles delivery across WhatsApp, SMS, and email with durable fallback semantics. Delivery receipts feed back into the scheduling service for audit purposes.

Infrastructure as code from day one

The entire stack — three environments (dev, staging, production) — is defined in Terraform before any application code was deployed. Environment state files live in Azure Storage with blob locking to prevent concurrent modifications.

The reason for doing this upfront rather than retrofitting it later: retrofitting IaC onto a running system means reconciling manual changes that have drifted from what the code describes. Starting with Terraform means the code is always the source of truth. Running terraform plan in CI against staging has already caught two configuration changes that would have caused environment drift.

PHI handling and HIPAA-aligned controls

Patient names, phone numbers, and appointment details are Protected Health Information. Full HIPAA compliance — including Business Associate Agreements with Azure and formal risk assessments — is out of scope for the MVP and will be completed before any production deployment with real patient data. What is in scope now:

• Encryption at rest: Azure SQL Transparent Data Encryption enabled on all environments
• Encryption in transit: TLS 1.3 enforced at the application perimeter
• PHI scrubbing in telemetry: a TelemetryProcessor strips or hashes PHI fields before they reach Application Insights — this was the most labour-intensive control to implement correctly
• Audit logging: every scheduling API mutation emits a structured audit event; PHI fields are redacted before export to Azure Storage
• Data residency: South Africa North as primary region; East Africa availability is limited in Azure, so this is the closest compliant option

The PHI scrubbing work took longer than expected. Tracing where patient data could leak into incidental logs required iterative sweeps through every code path that touches appointment records.

CI/CD pipeline

Three gated pipelines in Azure DevOps:

PR pipeline — build, unit tests, SonarQube quality gate (coverage ≥ 80%, no critical issues). PR is blocked if the gate fails. No exceptions.

Staging pipeline — build, test, SonarQube gate, Docker image push to Azure Container Registry, terraform plan against staging (no apply), deploy to staging via App Service deployment slots, integration test suite against staging endpoints.

Production pipeline — manual approval gate, terraform apply to production with diff review, blue/green deployment via slot swap, smoke tests post-deploy with automatic rollback if they fail within 5 minutes.

The terraform plan step in the staging pipeline has been the most valuable addition. It surfaces infrastructure drift before it reaches production and makes every deployment reviewable.

Current status and roadmap

Expected MVP: Q2 2026. The MVP scope is the Scheduling Service, Identity Service, and Notification Service — sufficient for a pilot clinic to replace manual WhatsApp scheduling.

What I've learned so far

Event sourcing adds complexity that needs justification. For a scheduling system, a full event-sourced model introduces operational overhead that isn't warranted at MVP scale. The architecture uses a pragmatic hybrid: an append-only audit event log for compliance purposes, combined with a canonical relational view for fast reads. This gives the audit trail without the query complexity of rebuilding state from events.

Terraform revealed drift I didn't know existed. Running terraform plan in CI against staging caught a manual change to a Redis cache configuration that had been applied directly to the portal. Without the plan step, that change would have been silently overwritten on the next deployment.

PHI scope creep is real. Every time I thought I'd found all the places patient data could appear in logs or telemetry, I found another one. Building PHI classification into the data model early — rather than auditing for it later — would have saved significant time.

For repository and implementation details: github.com/edogola4