Odessa Symphony Guild

QuickBooks OAuth 2.0

Full Intuit OAuth flow: authorization endpoint, callback handler, token exchange, and secure storage. Tokens encrypted at rest with AES-256-GCM using environment-managed keys. Automatic access token refresh on expiry, including refresh-token expiry handling.

Payment → Invoice reconciliation

Signed webhook endpoint for Intuit payment notifications with HMAC-SHA256 signature verification using timingSafeEqual. Resolved the non-obvious event modeling problem: Payment events don't directly contain Invoice IDs — you have to traverse Payment.Line[].LinkedTxn[] to find them. Automating paid-status sync in Supabase required understanding this structure from the QB API docs and logs.

Edge-compatible session security

Admin session validation originally used Node.js crypto — which breaks on the Next.js Edge runtime. Rewrote HMAC-SHA256 verification using Web Crypto API (crypto.subtle) for full Edge middleware compatibility. httpOnly, sameSite=strict, secure cookies with 8-hour bounded lifetime.

3-step enrollment flow

Student registration with React Hook Form + Zod step-aware validation. Dynamic guardian system (1–4 guardians) with useFieldArray, relationship selection, and a "same address as Guardian 1" checkbox that auto-copies fields. Zod superRefine enforces cross-field rules: at least one guardian email required for invoice delivery.

Live dues and reCAPTCHA

Dues and late fees loaded from a settings API at runtime with resilient hardcoded fallback. Grade-aware membership logic auto-assigns freshman pricing. Google reCAPTCHA v2 on the client with server-side token verification to prevent bot submissions.

Legal consent and e-signature

Media release authorization embedded directly into the signup flow — capturing guardian consent, social media opt-out, e-signature, and submission timestamp. Stored per-student alongside the enrollment record.

Graceful degradation

QuickBooks failures at any stage — invoice creation, customer lookup, payment link generation — do not block student registration persistence. The enrollment saves to Supabase first; QB operations are best-effort with logged errors and retry paths.

Admin tooling

Real-time roster with search, grade filter, paid/unpaid filter, KPI summary cards, and one-click payment status toggle. Print-optimized layout with hidden controls. Pricing panel for 6 configurable dues/fee keys with live updates reflected immediately on the public join form.

Security

• —AES-256-GCM encryption for QuickBooks OAuth tokens at rest
• —HMAC-SHA256 webhook signature verification with timingSafeEqual (timing-safe comparison)
• —Web Crypto API (crypto.subtle) for Edge-compatible admin session validation
• —httpOnly, sameSite=strict, secure session cookies with 8-hour lifetime
• —All /admin/* routes protected via Next.js middleware with Edge-compatible session verification
• —Secure response headers: no-cache, nosniff, DENY framing on all sensitive API routes

Database

• —Supabase migration set covering students, encrypted QB tokens, settings, guardian expansion, and media-release fields
• —Flexible 1–4 guardian arrays mapped to 36 relational DB columns with zero data loss for existing records
• —Student records scoped by school year for clean multi-year data isolation
• —Backward compatibility: supports both new guardian_N_* columns and legacy mom_*/dad_* records in display
• —Supabase service role key for trusted server-side operations; RLS preserved for public routes

QuickBooks

• —Customer find-or-create flow keyed by primary email to avoid duplicate payer records
• —Invoices with due dates, line items, and ACH/credit-card online payment enabled (AllowOnlinePayment: true)
• —Multi-recipient invoice delivery for additional guardian email addresses
• —intuit_tid correlation IDs logged on all QB API calls for production debugging
• —MOCK_PAYMENT_MODE feature flag with singleton mock QB client — full local dev without live credentials

Frontend

• —React Hook Form + Zod with step-aware validation and progressive completion UX
• —useFieldArray for dynamic guardian management with add/remove and conditional field copying
• —Zod superRefine for cross-field business rules across dynamic arrays
• —Live phone number formatting during keypress for student and guardian inputs
• —Live dues loaded from settings API with resilient hardcoded fallback