Architecture

Tech stack

The say-no: don't build your own payments

A driving-school SaaS handling instructor payouts touches real money and real PCI scope the moment it stores a card number or moves funds between parties. Building that in-house means: PCI-DSS compliance work, dispute/chargeback handling, KYC for every instructor, and an ongoing regulatory burden that has nothing to do with what makes DriveDesk useful. Stripe Connect (Express accounts) does all of this — instructor onboarding via Stripe's hosted KYC flow, automatic payouts to their own bank account, and built-in dispute tooling — for a transaction fee that is cheaper than the engineering time it would take to build a worse version in-house. This isn't a placeholder decision to revisit later; it's permanent.

System architecture

A single Next.js application serves three logical surfaces from one codebase: the instructor/admin dashboard, the pupil booking PWA, and a set of API routes/server actions that both talk to. Supabase Postgres is the single source of truth; Stripe and Twilio are called from server-side routes only — no payment or SMS logic ever runs client-side. Scheduled jobs (reminder SMS sends, package-balance checks, nightly no-show-risk scoring once that feature ships) run via Vercel Cron hitting dedicated API routes, avoiding the need for a separate job-queue service at this scale.

Pupil PWA ──┐
            ├──> Next.js (Vercel) ──> Supabase Postgres (RLS)
Instructor  │         │
Dashboard ──┘         ├──> Stripe Connect (payments, payouts)
                       ├──> Twilio (SMS)
                       └──> Resend (email)

Data model

Core tables (fields abbreviated to what matters for build decisions):

Row-level security in Supabase scopes every query by instructor_id (or school_id for admins), so an instructor's Postgres role can only ever see their own pupils, bookings, and payment records — enforced at the database layer, not just in application code.

APIs & integrations

• Stripe Connect: Express account creation per instructor at onboarding; Payment Intents for single lessons and packages; webhooks (payment_intent.succeeded, charge.refunded, account.updated) drive booking/payment status updates.
• Twilio: outbound SMS only in MVP (reminders, booking-link invites); inbound SMS handling deferred.
• Resend: transactional email templates for receipts and booking confirmations, triggered from the same server actions that handle Stripe webhooks.
• Google/Apple Calendar (fast-follow, not MVP): one-way sync of an instructor's bookings out to their personal calendar, via Google Calendar API and CalDAV respectively.

Auth model — dual instructor/pupil

Instructors and school admins authenticate via Supabase Auth magic link (email-based, no password to remember or reset — instructors are not power users of software and password-reset support tickets are avoidable friction). Pupils authenticate via phone number + one-time SMS code, since a pupil arriving via an invite link should never hit a "create a password" wall. Both identity types map to a single users table with a role enum (instructor, school_admin, pupil), and Postgres RLS policies branch on that role to scope data access. Session tokens are short-lived JWTs issued by Supabase; refresh handled client-side by the Supabase SDK.

Security & scaling

• All PII (pupil phone numbers, names) encrypted at rest by Supabase's underlying Postgres encryption; no card data ever touches DriveDesk's own database — Stripe holds it entirely.
• Pupils under 17 with a provisional licence are a safeguarding-adjacent population: DriveDesk stores only what's operationally necessary (name, phone, licence status, lesson notes) and nothing else — no unnecessary personal data fields exist to be misused or breached.
• At the scale this product will realistically reach in year one (low thousands of instructors, tens of thousands of bookings/month), a single Postgres instance and serverless Next.js deployment on Vercel has no meaningful scaling risk. Read-heavy calendar queries are indexed on (instructor_id, scheduled_at); this is a straightforward CRUD workload, not a systems-scaling problem.

Where AI genuinely fits — and its guardrails

Two AI features are scoped for the "Intelligence" roadmap phase (see 02 — Product), deliberately not in MVP, because both need real booking history to be worth anything:

1. No-show risk flagging. A model (or, initially, a simple weighted heuristic before any ML is justified) flags a booking as elevated no-show risk based on factors like lead time since booking, pupil's prior cancellation history, and day/time. This is surfaced to the instructor as a soft flag on the booking card ("this pupil has cancelled last-minute 2 of their last 5 bookings") — never used to auto-cancel or auto-charge. The instructor always makes the final call.
2. Lesson-note summarisation. Instructor's freeform notes across several lessons are summarised into a short, structured progress update a pupil (or a parent, for under-18 pupils) can read — "steady improvement on roundabouts, still building confidence with reverse parking." The instructor reviews and can edit the summary before it's shown to the pupil; it is never sent unreviewed.

Guardrail principle for both: AI here assists an instructor's judgement, it never replaces it, and nothing AI-generated reaches a pupil or affects money without a human in the loop first. Neither feature ships until there's enough real usage data (a few months of live bookings) to make the outputs meaningful rather than a novelty bolted on for launch.