Ray Davis Portfolio

Full-stack software engineering — front-end product, back-end APIs, real-time & AI integrations, application security, CI/CD, and AI-orchestrated delivery on self-hosted infrastructure.

🔗 Live demo → demo.ardeeweb.com

A writeup of work I designed and shipped for a production multi-tenant SaaS platform (Next.js App Router on Firebase / Google Cloud, serving multiple isolated business tenants from one codebase). I work across the stack: the front-end product UI customers and operators use every day, the back-end APIs and data model behind it, the security controls that keep tenants isolated, and the delivery pipeline that ships it all. Specific project internals are kept generic, but the mechanisms and patterns are real — and the live platform is linked above.

Contents

• At a glance — Frontend · Backend and APIs · Security · CI/CD and delivery
• How the guards actually work
• AI-orchestrated development and a self-hosted delivery fleet
• Technical appendix

At a glance

Frontend

• Built a reusable component system for a mobile-first admin. A declarative ResponsiveList primitive renders one typed dataset as a compact table on desktop and stacked cards on mobile, adopted across ~26 admin screens — plus shared page-header, loading-skeleton, and form primitives. Why it matters: one description drives both layouts, so mobile parity comes for free instead of being duplicated and drifting.
• Designed a palette-driven theming system shared by admin and public surfaces. Tenants brand their site from a single accent colour or an uploaded logo; a colour-math layer (luminance, darken/lighten, mix, contrast-aware text) derives a polished, readable light and dark theme automatically. Why: non-technical operators get an on-brand, accessible site without touching a colour wheel.
• Shipped a full per-tenant landing-page editor — a real WYSIWYG CMS. Multi-section editor (hero, pricing, team, gallery, testimonials, FAQ, and more) with drag-to-reorder, per-section visibility, and real-time live preview across multiple surfaces (hero carousel, full mini-page, and section-by-section), each rendering the exact public component. Why: operators see precisely what visitors will see, edited live, with no publish-and-pray loop.
• Engineered two animation engines, accessibility-first. TextFx (gradient/shadow/outline/shimmer effects plus typewriter, reveal-on-scroll, word-stagger, and sheen animations) and SeasonalEffectLayer (emoji particle systems and ambient backgrounds with intensity and per-section targeting). Both fully honour prefers-reduced-motion and use Intersection Observer for lazy reveals. Why: expressive, on-brand motion that never compromises performance or accessibility.
• Built complex, stateful customer and operator UIs. End-to-end food ordering (cart with local-storage persistence, modifier/ingredient customization with live price recalculation, multi-step PayPal checkout, and polling order tracking), real-time analytics dashboards, a live RBAC permission matrix that resolves effective access as you edit, and phone-first auth + MFA-enrollment flows. Why: the hard parts of a product live in stateful UI — these are the screens that actually carry the business.
• Built an advanced, URL-addressable data grid for the operator queue. Per-column filtering with a type-ahead that suggests both matching values and live row previews; multiple values OR within a column and a per-filter AND/OR with SQL-style precedence rendered as bracketed groups with a plain-English “showing tickets where…” summary; saved views as one-tap chips with a per-user default view; group-by; and a cross-tenant scope selector — every piece encoded in the URL (so a filtered view is a shareable link) and consolidated into one responsive Filters sheet on mobile. Why: operators slice a busy queue exactly how they think, and complex boolean logic stays legible instead of mysterious.

Backend and APIs

• Modeled a multi-tenant domain and served it through a typed API layer. Every API route runs through a single wrapper that declares its access level and resolves tenant context server-side; reads and writes are tenant-scoped by construction. Why: the data model and the authorization model are enforced in one place, not scattered per-handler.
• Integrated third-party services behind clean server boundaries. PayPal and Stripe for checkout, BigQuery + GA4 for analytics aggregation, SMS/TOTP providers for auth, and Cloud Functions for background and AI-assisted features (content/theme generation, document drafting) — credentials kept server-side, never in the client bundle. Why: third-party keys and logic stay off the client, and each integration has one well-defined seam.
• Built a payment-provider abstraction so each tenant chooses PayPal or Stripe per checkout area. One PaymentProvider seam serves two models behind a single interface — PayPal inline (create-order → server capture) and Stripe hosted Checkout (redirect, confirmed by a per-tenant, signature-verified, fail-closed webhook) — with server-authoritative pricing throughout and per-tenant processor credentials isolated in Secret Manager. Why: a tenant can switch processors per area (store / food / appointments / subscriptions) without forking the checkout, and every money path flows through one audited seam.
• Built real-time and aggregation-heavy data paths. Server-side dashboard aggregation across Firestore + BigQuery with safe fallbacks and Promise.all parallelism; polling-based live order/status updates with proper setup/teardown; optimistic updates with rollback on failure. Why: fast, resilient data flows that degrade gracefully when a source is unavailable.
• Validated every write with schemas. Zod schema validation on all write paths, with auth checks preceding any data access and no internal error detail leaked to clients. Why: malformed or hostile input is rejected at the edge, consistently.
• Built a real-time AI phone agent on a dedicated streaming service. Inbound calls connect to a Gemini Live voice agent over a separate Cloud Run WebSocket service that bridges Twilio Media Streams ⇄ Gemini — bidirectional G.711 μ-law ↔︎ PCM audio conversion, live barge-in, and spoken-consent recording — and the conversation is transcribed into a structured support ticket. Why: a natural-language phone front door that turns a call into actioned work — and it lives in its own scalable service because request/response hosting can’t hold a long-lived socket.
• Shipped an AI-assisted support ticketing system. Tenant-configurable request types (intents), each with a typed deliverable checklist; an AI pass auto-detects the intent and pre-fills the deliverables from the call transcript, voicemail, email, or a public web form — every model output re-validated server-side, never trusted blindly — and the live phone agent gathers an intent’s items conversationally. Plus assignment with cross-tenant escalation and a re-auth-gated approval workflow executed by a Cloud Function. Why: structured intake on every channel, with AI doing the first pass and a human confirming.
• Grew ticketing into the product’s operational spine. Intents gained nested deliverable checklists with per-deliverable lifecycle states and auto-rollup; state transitions fire approval-driven notifications (email + in-app, with an SMS channel built fail-closed behind carrier approval); customers self-serve their items via a tokenized magic link or an authenticated portal; staff author intents conversationally with an AI assistant (every draft re-validated against the schema and human-saved — the model never writes data); and unmatched customer requests become candidates a staff member promotes into reusable intents, distilled PII-free into a cross-tenant template corpus the platform operator curates and pushes back out. Why: one structured workflow engine now spans intake, fulfilment, and continuous improvement across every tenant.
• Completed two-sided payments — customer checkout and platform billing. On top of per-tenant customer checkout (PayPal/Stripe), the platform now bills tenants via PayPal Subscriptions from a separate platform account: catalog → billing-plan sync and a signature-verified, idempotent webhook that maps subscription lifecycle (active / past-due-in-grace / cancelled) onto each tenant’s entitlement state — shipped inert behind a kill-switch until configured. Why: the same entitlement engine that gates features now has a real revenue source wired into its one extension point.
• Grew ticketing into a self-explaining, self-improving recipe engine. Beyond structured intake, a request type (intent) now carries an optional instruction runbook that live-renders its captured field values into ready-to-run steps (an injection-safe template engine — values are escaped and spliced in after rendering); a known-issues loop where staff flag a snag against a step and curated fixes feed back into the recipe; an explainer layer that teaches an unfamiliar adopter what this is / why it matters / what you get, plus an AI “adapt this to your situation” flow that tailors the recipe to the adopter (human-confirmed, never auto-applied); and owner-shared templates that copy a recipe across tenants — where an explicit allow-list projection guarantees the shared/adopted copy can never carry an internal field, a secret, or another tenant’s data. Why: intents don’t just gather — they instruct, teach, adapt, and travel between businesses, every cross-tenant surface allow-list-safe by construction.
• Shipped an AI “guided build” authoring mode. Instead of a one-shot prompt, the assistant asks rounds of selectable questions (with recommendations), then synthesizes the answers into a draft that lands in the review editor — never auto-saved — with a persisted session so an in-progress build can be resumed. Why: a non-technical operator authors a complex structured recipe by answering questions, and a human confirms before anything is written.
• Routed every AI call through one governed chokepoint. All LLM egress flows through a single seam with a mandatory scrubber, a hard never-send list (card numbers / private keys block the call; other secrets are redacted in place), content-free provenance logging, per-tenant AI sub-processor disclosure, and — the part that makes it hold — a CI guard that fails the build if any new AI feature reaches a model without going through it. Why: a new AI feature inherits data-governance for free, and structurally cannot skip it.
• Delivered two billable, governance-heavy add-ons. A compliance portal (upload a policy → AI extracts controls → controls auto-verify → humans attest, with the platform itself supported as a subject) and an investor / business-plan portal (an authenticated, presentable plan with PDF export, an allow-list investor projection, and AI section-drafting). Why: revenue features where the hard part is the data boundary and the human-in-the-loop, not the CRUD.

Security

• Deny-by-default API authorization across 400+ endpoints. A single withRoute wrapper that every API handler must use, declaring a typed access level (public / authenticated user / tenant member / specific permission / tenant owner / superadmin / machine-cron / machine-webhook) plus automatic tenant-scoping. Why it matters: makes “accidentally unprotected” impossible and directly addresses broken access control — the #1 category in the OWASP Top 10.
• Turned the audit into an enforced invariant. A CI gate fails the build if any new route ships without a declared access level. Why: stops access-control regressions as the team and surface area grow — security that can’t silently rot.
• Full route authorization audit + remediation. Classified every endpoint by required access and fixed 6 critical tenant-scoped mutation gaps. Why: closed cross-tenant data-tampering holes before launch.
• Extended deny-by-default to per-tenant feature gating. A single declarative gate — withRoute({ feature }) for APIs and a matching guard for pages — returns 404 when a tenant lacks a feature (enabled and, when entitlement enforcement is on, paid/comped), so off features reveal nothing. A CI manifest fails any feature route missing its declaration, and a data-driven test harness proves every feature seals when off. Why: the same one-place, can’t-silently-rot discipline as the access gate — now for what each tenant is allowed to use, and the chokepoint where billing entitlement plugs in.
• Least-privilege RBAC with step-up auth. Base role + per-tenant membership role + granular permission grants and permission groups, plus per-permission re-authentication and approval gates (fresh-session enforcement) on sensitive actions. Why: minimizes blast radius and forces re-verification for high-risk operations.
• Enforced multi-tenant isolation in the database layer. Default-deny Firestore Security Rules with server-resolved tenant context, continuously proven by an automated rules-test suite that runs against the Firestore emulator in CI. Why: one tenant can never read or write another tenant’s data — and it’s verified on every PR, not assumed.
• Extended the platform’s most sensitive boundary along three deliberate dimensions. The one authorization chokepoint every route flows through now safely supports: (1) a cross-tenant read — operators view tickets across every tenant they belong to (superadmin across all, bounded + paginated), authorization derived server-side from memberships, a client-supplied tenant list only ever narrowing it; (2) an opt-in cross-tenant write — acting on another tenant’s ticket is allowed only via a fresh, permission-specific membership resolution in that ticket’s tenant (never the session’s claims), fail-closed, scoped to the ticket surface, with a forbidden foreign record returning 404 (not 403) so status codes can’t become a cross-tenant existence oracle; and (3) a cross-scope dimension (below). Why: genuinely useful cross-tenant workflows without ever letting the guard be coaxed into leaking a tenant the caller has no access to — each loosening is opt-in, fresh-resolved, and fail-closed.
• Built a 3rd tenancy level (workspaces / partner portals) as a walled sub-scope. Extended the access model from two levels (platform → tenant) to three (platform → tenant → workspace): a “scoped principal” (e.g. a factory a business partners with) sees only records in the workspace(s) they’re assigned. It’s deny-by-default — a scoped user can reach only explicitly workspace-partitioned routes (any other tenant-permission route 403s), with the record’s workspace resolved server-side from the stored doc, a hard permission ceiling (a tenant can never grant a scoped user a sensitive permission, enforced at four layers), and server-side field redaction that deletes sensitive fields from the DTO before it’s serialized (never sent, not UI-hidden). Onboarding is invite-only (single-use, expiring, workspace-scoped tokens). Why: the same isolation discipline as the cross-tenant guard, one level down — a permanent new boundary built deliberately, mutation-tested, and reviewed. Scope, stated honestly: the enforcement wall is real, live and tested; the surfaces that would make it a shipped product are not. Records are partitioned by a workspaceId the server resolves from the stored document, but no admin UI assigns one, and the per-workspace login branding the invite flow reads is designed rather than wired. The boundary was the interesting engineering and it is finished; the product on top of it was not pursued (DEC-392).
• Multiple equal tenant owners. Ownership authority moved from a single-owner field to tenant membership role, so a tenant can have several co-owners; granting/revoking the owner role is itself owner-only, under a re-authentication gate, and can’t be used to self-escalate. Why: real organizations have more than one owner — modeled without opening a privilege-escalation path.
• A locked-down public self-service surface. Customers fill ticket deliverables through a single-ticket-scoped, expiring, high-entropy magic-link token — the tenant and ticket are resolved only from the stored token (no caller-supplied ids, so no IDOR), the page returns a whitelist projection that never exposes internal fields, and file uploads are refused outright. Why: customer self-service that opens no cross-tenant or data-exfiltration hole — security-reviewed before it shipped.
• A PII boundary on cross-tenant aggregation. The platform-operator view of request shapes across all tenants runs through a pure projection that emits only structural definitions (labels, field types) and provably strips raw request text, captured values, and identifiers — driven to a 100% mutation-test score. Why: the operator learns what to template from without ever seeing one tenant’s customer data.
• Secrets moved out of the database into Google Secret Manager, with per-tenant isolation and least-privilege IAM. Why: credentials become rotatable, access-controlled, and never co-located with application data.
• Hardened a necessarily-public Cloud Run WebSocket service. Twilio can’t present Google IAM, so the streaming endpoint must accept public connections — I compensated with a connection-token check on the socket (rejecting any stream the app didn’t authorize), a fixed callback origin that closed a secret-exfiltration path (a public socket could otherwise be coaxed into POSTing the service’s bearer token to an attacker-supplied URL), a dedicated least-privilege runtime service account replacing a project-Editor default, call duration/idle caps, a non-root container, and image vulnerability scanning. Why: defense-in-depth and least privilege for an endpoint that can’t sit behind IAM.
• Hardened HTTP responses. Per-request nonce Content-Security-Policy (strict-dynamic, object-src 'none', no unsafe-eval) plus HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy. Why: layered defense against XSS, clickjacking, and MIME-sniffing.
• Hardened the server/client data boundary (Next.js App Router), audited against Next.js’s data-security guidance. Centralized every secret behind a single server-only config module, returned minimal explicit DTOs from each data-access read (never raw database records), validated dynamic route parameters at the access wrapper, and applied React’s taint APIs so the session user and credential objects throw if ever passed to the browser. Why: makes private data and secrets structurally unable to reach the client — defense-in-depth above the deny-by-default API layer.
• Modern authentication rework. Phone-first sign-up with required email, email verification, password reset, passwordless email-link, account linking, and SMS/TOTP multi-factor authentication; every sign-up is bound to its tenant via a formal customer-membership record kept isolated from staff/admin tooling. Why: stronger identity assurance, real account recovery, and clean customer-vs-operator separation.
• Detection and auditability. Structured security-event logging with Google Cloud-native email alerting and a scheduled daily security report. Why: you can’t respond to what you can’t see.
• Supply-chain & repository security. Automated secret scanning (gitleaks) in CI, Dependabot for dependency CVEs, and a clean fresh-history repository migration to purge a previously-committed credential from Git history. Why: prevent secret leakage going forward and remove already-leaked material from the past.
• Made every security invariant drift-proof with a CI coverage guard. The recurring discipline: when the rule is “every X must do Y,” it’s backed by a build-failing guard that catches a new X that isn’t covered — so security can’t rot as the surface grows. Live guards enforce that every route declares access, every route under a feature prefix declares its gate, every ticket mutation logs to the audit ledger, every AI call scrubs, every platform page self-gates, and every cross-tenant isolation surface is registered. Why: the strongest control is the one a human can’t forget to apply.
• Redaction is an allow-list, never a block-list. Every customer-, scoped-, or adopter-facing projection is built from an explicit whitelist of safe fields — so a newly-added internal field can never leak by omission (a block-list would leak it the moment someone adds one). Proven by “a new field can’t leak” tests and driven onto the mutation-testing list. Why: the safe default has to be structural, not remembered.
• Ran a self-directed audit that fixed three vulnerability classes, not three bugs. Each root shape was fixed structurally and locked with a new CI guard: a page layout mistaken for an auth boundary (every protected page now self-gates, enforced by a guard), a permission rebuilder that failed open (re-defaulted to least-privilege via an allow-list), and best-effort writes that silently mis-scoped platform-level data (routed to correctly-scoped collections + a guard). Why: fixing the class and adding the guard beats fixing the instance and hoping.

CI/CD and delivery

• Multi-stage CI gating every pull request: lint, type-check, unit tests with enforced coverage floors, the route-access security gate, production build, Cloud Functions build, Firestore rules tests, browser E2E smoke, and secret scan. Why: nothing reaches the main branch without clearing the full quality + security bar.
• Made the gate unbypassable via branch protection on the main branch — all checks required, no force-push, no branch deletion. Why: process guarantees only hold if they can’t be skipped.
• Browser-level E2E smoke (Playwright) asserting the unauthenticated auth redirect and the actual security headers served over the wire. Why: validates the full middleware → HTTP stack a unit test can’t reach.
• Hands-free scheduled production canary that exercises real phone-auth sign-in against the deployed environment nightly (using provider test numbers, so no real SMS). Why: continuous “is production actually working end-to-end” signal with no manual steps.
• Environment-parity automation that checks config drift between production and staging and re-verifies the live security headers post-deploy. Why: keeps two environments in lockstep and confirms headers survive the CDN/edge.
• Two-environment delivery (production + staging/demo) on managed container hosting, with documented rollout and rollback runbooks. Why: safe, reversible progressive delivery.
• Branch-gated promotion to production. Staging auto-deploys from the main branch; production tracks a separate protected branch, so every change bakes on staging and reaches production only via an explicit, reviewable promote (the data-layer rules deployed alongside as a deliberate step). Why: fast iteration on staging with a deliberate, reversible gate before customers see anything.
• Consolidated the pipeline to cut billed minutes without dropping coverage — collapsed ~12 per-PR jobs into a handful, kept the slow/baking suites running as non-blocking post-merge checks, and de-duplicated work across jobs. Why: a leaner feedback loop and a smaller CI bill while every gate still runs.
• Built per-client clone tooling — a deterministic strip-transform, not a hand-forked branch. A codemod-driven pipeline reproducibly produces a per-client build by removing chosen feature modules and platform-operator surfaces from a clean checkout, regenerating exactly the secrets the remainder needs (names/placeholders only, never values), and proving the result green through the full gate (type-check → route-access → lint → build → test) before it ships. Main stays the single source of truth; each variant is a pure function of (main, a per-client config), so the clone can’t silently drift. Why: onboard a new client-owned deployment as a repeatable transform with the CI gates as its correctness proof — no maintained fork.
• Pipeline efficiency without cutting coverage: parallelized jobs, auto-cancellation of superseded runs, heavy jobs gated to PRs only, and the production build artifact shared with the E2E job instead of rebuilt. Why: faster feedback while keeping every check.

How the guards actually work

The security model rests on a few load-bearing ideas — each enforced in one place, and drift-proofed by CI so it can’t quietly rot as the codebase grows.

One authorization chokepoint every route flows through

Every API handler is wrapped by a single withRoute function that, before the handler body runs, resolves the tenant server-side (from the verified session or route — never the request body), checks a typed access level (public / user / member / permission / owner / superadmin / machine-cron / machine-webhook), enforces a cross-tenant scope guard (an admin of tenant A can’t act on tenant B by changing a path param), applies any per-permission re-auth / approval gate, and logs a security event. The same wrapper carries the feature-gate and the cross-scope (workspace) guard. So access, tenancy, sub-scope, and entitlement are all decided in one audited seam — not re-implemented per handler, where one of them is eventually forgotten.

Every enforced invariant has a CI coverage guard

The pattern that ties it together: whenever the rule is “every X must do Y,” a build-failing guard catches a new X that isn’t covered. A family of check:* guards enforces that every route declares access, every route under a feature prefix declares its gate, every ticket mutation writes to the audit ledger, every AI call routes through the scrubber, every platform page self-gates its own auth (a page layout is not an auth boundary), and every cross-tenant isolation surface is registered in a ledger. The point isn’t any single check — it’s that “someone will remember to do the secure thing” is replaced by “the build fails if they don’t.”

Isolation and redaction are server-side, allow-list by construction

Cross-tenant (and cross-scope) isolation lives in the query and the guard, not the UI — sensitive fields are deleted from the response, not hidden in the page. A forbidden foreign record returns 404, not 403, so status codes can’t become a cross-tenant existence oracle. And every customer-, scoped-, or adopter-facing projection is built from an explicit allow-list of safe fields — never a block-list — so a newly-added internal field can’t leak by omission. The critical projections and guards sit on a mutation-testing list that verifies the tests actually catch a deliberate break.

All AI egress is governed at one chokepoint

Every LLM call routes through a single governed seam: a mandatory scrubber, a hard never-send list (card numbers / private keys block the call), content-free logging, and a CI guard that fails the build if a new AI feature reaches a model without going through it. A feature inherits the governance for free — and structurally cannot skip it.

AI-orchestrated development and a self-hosted delivery fleet

How the work gets built

A large share of the recent work was delivered by architecting and driving AI coding agents — decomposing a feature into a grounded plan, dispatching parallel agents to build slices in isolated worktrees, and running each change through the full gate (type-check, tests, the security guards, a focused security review) before it merges. The discipline is human-in-the-loop and never-auto-merge: agents propose, a human reviews and approves, and production deploys stay a deliberate, separate step. It’s the same “suggest, don’t act” rule the product’s own AI features follow — applied to the way the product itself is built.

A self-hosted fleet, one role per box

To support that workflow — and to keep a private repo’s CI affordable — I’m standing up a small fleet of self-hosted machines, each with a single deliberate role, physically separated so that resource contention, failures, and trust boundaries never bleed across:

The governing principle is centralize shared services, isolate contended or untrusted compute: the hub seeds and observes everyone; the compute boxes are specialists that never interfere. Only two of them ever face production — error ingestion and AI inference — reached over an authenticated tunnel with a fail-closed circuit-breaker, so a home machine can never take production down and can never leak a privacy-mandated AI task to the cloud. (Production connectivity + failover: planned.)

Technical appendix

Frontend architecture & component system

• Stack: Next.js App Router (React, server + client components) with MUI 7 (the sx system + Emotion) as the single design system. (An earlier Tailwind layer was removed in favor of MUI-only after it had fallen out of use; a CI guard now fails the build if Tailwind — a dependency, config, or class — is reintroduced.)
• ResponsiveList — a typed ResponsiveColumn[] descriptor (header, render, alignment, per-breakpoint visibility, optional primary column) drives a desktop table or a mobile card stack from one definition; adopted across ~26 admin screens. A single useIsMobile hook (MUI useMediaQuery at the sm breakpoint) is the one source of truth for the breakpoint.
• Shared admin chrome: responsive PageHeader (title/subtitle left, actions right; stacks on mobile), PanelSkeleton loading states, and shared button/form primitives — organized as a domain-split component library (admin, landing, payment, blog, documents).
• Responsive landing system: 30+ public landing sections built on MUI Grid v2 with object-valued responsive props ({ xs, sm, md }), consistent spacing/padding tokens, and adaptive hero/gallery/CTA layouts.

Theming & customization

• Three-tier theme model: built-in presets, per-mode (light/dark) colour overrides, and seasonal themes that activate manually or by date range — all per tenant.
• Brand-aware generation: brandTheme() / boldTheme() derive a complete, readable token set (bg, surface, border, text, textMuted, accent, …) from a single accent; logo upload triggers dominant-colour extraction (paletteToThemeTokens). A colour-math utility layer (luminance, darken/lighten, saturate, mix, contrastText) keeps results legible in both modes.
• Live preview: multiple in-editor surfaces (hero carousel, full scaled mini-page, and per-section preview) render the real public components with the active theme + seasonal effect resolved via pickActiveTheme(), wrapped in error boundaries so half-typed values never crash the editor.

Feature UIs (stateful client work)

• Food ordering, end to end: menu with stock/availability and single/multi-select modifier groups + ingredient edits and live price recalculation; a cart context persisted to local storage with quantity aggregation; a multi-step checkout (fulfillment → customer info → payment) with PayPal SDK integration; and order tracking via 15-second polling with a visual status stepper.
• Operator tooling: real-time analytics hub (Firestore + BigQuery), food menu/modifier CRUD with nested arrays and derived pricing, an order board with a state-machine for valid status transitions and optimistic updates, and a markdown document editor with split-pane preview and AI drafting.
• Access-control UI: a live permission matrix that recomputes effective access (groups ∪ direct grants − revocations) as you toggle, with approval/re-auth override controls gated behind a re-auth hook.

Backend, APIs & integrations

• API layer: withRoute(options, handler) wraps every route; access kinds are typed and the tenant source is explicit (cookie / path / hostname / none). Cross-tenant requests are rejected and logged.
• Integrations: PayPal and Stripe (checkout, behind one provider seam), BigQuery + GA4 (analytics aggregation with safe fallbacks), SMS/TOTP (auth factors), and Cloud Functions for background + AI-assisted generation (content, themes, document drafts) — all server-side, never shipped to the client bundle.
• Data handling: Zod validation on all write paths; auth precedes data access; rate limiting on high-value endpoints; App Check on payment endpoints; no internal error details returned to clients.

Real-time voice agent (Twilio Media Streams ⇄ Gemini Live)

• A separate Cloud Run WebSocket service (its own deployable, like the Cloud Functions package) hosts the long-lived socket the request/response app host can’t. Twilio <Connect><Stream> streams call audio in; the service bridges it to a Gemini Live session and streams the agent’s audio back.
• Audio path: caller G.711 μ-law 8 kHz ↔︎ PCM16 (16 kHz in / 24 kHz out) with linear resampling, plus barge-in (clears the playback buffer when the caller talks over the agent). The working model + message shape were pinned by empirically probing the live API (only one model holds a bidirectional session; the documented names errored).
• App as orchestrator: the inbound voice webhook returns the stream TwiML, speaks the recording-consent line, and passes the tenant’s opener + an intent catalog as stream parameters; on hang-up the transcript is POSTed back and becomes a ticket with AI intent detection + triage.
• Security: a connection-token check gates the public socket; the transcript callback targets a fixed server-side origin (never caller input); a dedicated least-privilege service account; hard duration + idle caps; non-root container; image vulnerability scanning.

AI-assisted ticketing & intents

• Intents are tenant-configured request types with typed deliverables (text / number / date / single-choice / yes-no / file). A ticket stores a snapshot of the chosen intent’s deliverable definitions + captured values + provenance, so later edits to an intent never disturb existing tickets.
• AI auto-detect classifies a new ticket’s text into one of the tenant’s intents and extracts deliverable values; a pure validator coerces the model output against the real definitions (a choice must be a real option, files are never accepted from public input) so the model is never trusted blindly. It runs across the voice agent, voicemail, inbound email, and a public website intake form.
• Supporting workflow: a re-auth-gated approval flow with an idempotent Cloud Function executor, assignment with cross-tenant escalation to a platform queue, and per-tenant notification controls; call recordings are linked to tickets and streamed back through an authenticated in-app player (recording media is never exposed directly).
• Deliverable engine: deliverables can nest one level and define their own ordered lifecycle states (one flagged “complete”); completion auto-rolls-up (a parent completes when its children do) and a pure, heavily-unit-tested progress function drives the % shown on every ticket. The on-ticket value is a frozen snapshot of the definitions + captured values + per-field status history, so editing an intent never disturbs existing tickets.
• Approval-driven notifications: entering a state flagged “notify” dispatches to the configured recipients over email + an in-app feed (an SMS channel is built but fail-closed behind carrier/A2P approval). Dispatch is best-effort and fired after the state commit, so a notification failure can never roll back the state change.
• Customer self-service fill: customers complete their deliverables via a tokenized magic link (single-ticket-scoped, expiring) or an authenticated portal; submitted values land as a customer-sourced status for staff to confirm. The public surface returns only a whitelist projection and refuses files.
• Conversational AI authoring (distinct from AI detection): staff describe an intent in natural language and refine it turn-by-turn; a Gemini generator proposes a full draft each turn, a pure coercer guarantees the draft always satisfies the real schema (caps nesting, drops invalid types/options), and nothing persists until a human reviews and saves through the existing validated write path — the model never touches the database.
• Templates + request-driven improvement: the platform operator authors global intent templates and pushes a deep-copied, independent fork into chosen tenants (idempotent — never clobbering a tenant’s customizations). Conversely, unmatched customer requests are captured as candidates a staff member promotes into reusable intents; a PII-stripping projection rolls candidate + intent shapes into a cross-tenant corpus the operator templates from.
• Value suggestions, approval-gated: free-entry deliverables autocomplete from a per-field pool of previously-confirmed values — staff-confirmed values join automatically, customer-submitted values queue for staff approval, and the pool is staff-only (never surfaced on the customer fill page, verified by test).
• Instruction runbooks (self-executing recipes): an intent can carry a markdown template with {{field}} placeholders and {{#if}}/{{#unless}} blocks that live-renders against a ticket’s captured values into ready-to-run steps. The render engine is a trust boundary — field values are HTML/markup-escaped and spliced in after the template renders (via a sentinel), so a hostile field value can’t inject template logic.
• A known-issues learning loop: staff flag a snag (a question or error) against a specific step of an intent instance; resolved snags are curated into the intent’s de-duplicated known-issues, which can seed the runbook’s “known issues” section — the recipe improves from real use. Snag content is internal-only (excluded from the customer allow-list) and fail-closed at every gate.
• A self-explaining, adaptive layer: an intent carries an explainer (what / why / what-you-get) that’s AI-draftable and hand-editable; an AI “adapt to your situation” flow reuses the guided-elicitation + field-helper engines to ask an adopter about their context and propose tailored pre-fills + a “how this fits you” summary — human-confirmed, never auto-applied. Everything an adopter sees is built from projectIntentExplainerForAdopter, an allow-list projection that provably never emits an internal field, the raw runbook, approver ids, or another tenant’s data.
• Cross-tenant recipe sharing (copy-on-adopt): an owner publishes an intent/template into a per-owner shared library; another tenant adopts a deep, independent copy (never a live link), with the explainer surviving the publish→adopt boundary only through the allow-list projection — so a shared recipe onboards the adopter without leaking the author’s internals.
• A Collab workspace per ticket + AI field-analysis: a documentation surface (links / notes / files) alongside each ticket, where a curated item can be promoted into the intent’s reusable reference material through a redaction gate that carries only human-entered metadata (never file bytes, storage paths, or author ids).

AI data governance

• One egress chokepoint (genai.ts). Every LLM/embedding call — intent detection, conversational + guided authoring, the explainer/adapt flows, compliance extraction, business-plan drafting, the phone agent — routes through a single governed function. Direct model calls fail a CI coverage guard.
• Mandatory scrubber + hard never-send. Text parts are scrubbed by sensitivity level (low / pii / restricted, defaulting restricted when unset — fail-closed); card numbers and private keys block the call, other secret categories are hard-redacted in place with a logged security event. Provenance logs are content-free (model / task / tenant / categories — never the content).
• Trust boundaries on every model output. Each AI feature repairs the model’s raw output through a pure, mutation-tested coerce* function that guarantees a structurally-valid result and never throws — dropping hallucinated field keys, capping sizes, clamping enums — so a bad model response degrades gracefully instead of corrupting data. Nothing an AI produces is auto-saved; it lands in a review surface a human confirms.
• An on-prem routing hook sits after the scrubber, so privacy-sensitive tasks can later be served by a self-hosted model without touching the call sites.

Authentication & sessions

• Server-side Firebase session cookies (httpOnly, secure, SameSite) as the primary auth mechanism; short-lived ID tokens exchanged server-side.
• Cookie revocation checked on every request so a disabled/role-changed account loses access immediately; refresh tokens revoked on privilege changes.
• Generic auth error responses (no account-existence or reason leakage).
• Phone-first + email/password + federated sign-in; email verification, password reset, passwordless email-link; MFA via TOTP and SMS with a sign-in resolver for the multi-factor-auth-required challenge.

Authorization (deny-by-default + RBAC)

• withRoute(options, handler) wraps every API route; access kinds are typed and tenant source is explicit (cookie / path / hostname / none). Cross-tenant requests are rejected and logged as security events.
• A standalone script (run in CI) asserts every route.ts declares access via withRoute or an explicit, reasoned exemption comment — enforcing, not advisory.
• RBAC resolves effective permissions from (assigned groups ∪ direct grants) − revocations; owner/admin get implicit full access; staff are granted explicitly. Sensitive actions additionally require a fresh session (re-auth) and/or approval per a configurable policy.

Feature gating & entitlements

• One chokepoint decides feature availability: tenantHasFeature returns true only when a feature is enabled and (when entitlement enforcement is on) entitled (paid or comped). The withRoute({ feature }) option and a requireFeatureOr404 page guard both read it, so an off feature returns 404 at API, page, and nav alike — never revealing which layer or that the feature exists.
• Can’t-silently-rot: a route→feature manifest in CI fails any handler under a feature prefix that doesn’t declare its feature:, and a data-driven harness iterates the live feature set, asserting each one seals (404) when disabled and is unreachable cross-tenant.
• Entitlement engine: a pure resolver maps a tenant’s billing state (comped / active / trialing / past-due-within-grace) to its entitled feature set; a superadmin comp grants access, and a global kill-switch ships enforcement dark (default off → behaves as enabled-only) so it can be turned on deliberately. Why: the billing model plugs into the exact same gate that already protects features — paid access is one composition, not a parallel system.

Payments (provider abstraction)

• A PaymentProvider interface abstracts the processor so checkout code is provider-agnostic. Two implementations behind it: PayPal (inline — create order, client approves, server captures) and Stripe (hosted Checkout Session → redirect → confirmed asynchronously by webhook). A merchant-context parameter (tenant vs platform) lets the same seam serve a tenant’s own customers and platform billing.
• Per-context selection: each tenant picks PayPal or Stripe independently for store / food / appointments / subscriptions; the resolver only honors a provider that’s actually configured, so a checkout never routes to an unusable one. PayPal stays the default and its existing flows are unchanged.
• Webhook discipline: every Stripe webhook verifies the per-tenant signing secret before any mutation and fails closed; only a paid session activates; prices are re-derived server-side (never trusted from the event); and food reserves inventory at session-create (mirroring the cash path) so there’s no oversell and no post-payment refund, releasing the hold on an expired event. Per-tenant processor secrets live in Secret Manager, never the client.
• Platform billing (the other side of the seam): tenants subscribe to the platform via PayPal Subscriptions from a separate platform account (distinct from the per-tenant customer-checkout creds). A “sync to PayPal” step turns the catalog into billing plans; a signature-verified, idempotent webhook (events claimed by id, released on write-failure so a retry re-applies) maps ACTIVATED / UPDATED / CANCELLED / PAYMENT.FAILED onto a tenant’s billing state with absolute (non-cumulative) grace handling, which the entitlement resolver then reads. Shipped inert (clean 503) until platform creds are configured, then flipped on by a kill-switch. The tenant resolves from the subscription’s signed custom_id, never caller input.

Multi-tenant isolation

• Firestore Security Rules: a default-deny catch-all, server-resolved tenant config (clients can’t assert their own tenant), and write-locks on shared catalog/public content. Sensitive collections are Admin-SDK-only (no direct client access).
• Tenant isolation is covered by an emulator-backed rules test suite in CI plus an authorization-matrix test that probes each route’s required access.

Secrets management

• No secrets in source control (.env* gitignored; gitleaks enforces it in CI).
• Google Secret Manager is the canonical store; per-tenant third-party credentials (payments, email) are isolated and reach the runtime via the hosting platform’s secret injection — never the client bundle.

Input validation & API hardening

• Zod schema validation on all write paths; auth check precedes any data access; rate limiting on high-value endpoints; no internal error details returned to clients; App Check on payment endpoints.

Data-layer hardening (server/client boundary)

• Audited the app against Next.js’s data-security guide and closed the gaps: a single server-only config module is the only thing that reads process.env (one audit point for every secret); data-access reads return field-mapped DTOs rather than raw documents; dynamic route params ([id], [tenantId]) are validated by an optional Zod schema on the withRoute wrapper — after the auth check, so a malformed param never precedes a 401/403; and React’s taint APIs (experimental.taint) flag the session user and tenant-secret objects so they can’t be serialized to a Client Component.

HTTP security headers / CSP

• Per-request nonce CSP with strict-dynamic and a tight allowlist (auth/reCAPTCHA, payments) — no unsafe-eval, object-src 'none', base-uri 'self', form-action 'self'. Baseline headers (HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy) set in middleware and verified live post-deploy.

Security testing (four layers)

1. Firestore/Storage Rules tests (emulator) — tenant isolation and default-deny.
2. Authorization-matrix tests — every route’s access kind + permission.
3. Input-validation tests — schema rejection on write paths.
4. Browser E2E (Playwright) — auth redirect + real security headers over HTTP. Plus a scheduled live auth canary against the deployed site.

Monitoring, logging & alerting

• Structured security-event logging (auth denials, cross-tenant attempts, privilege changes); Google Cloud-native metric/log alerts emailed to owners; a daily security report; a service-inventory/monitoring catalog with live status.

Supply-chain & repository security

• gitleaks (CI), Dependabot (CVEs), branch protection with required checks, and a fresh-history repo migration to eliminate a leaked key from all reachable history.

CI pipeline (jobs)

Lint · Type check · Unit tests (coverage floors enforced) · Route access gate · Next.js build · Cloud Functions build · Firestore rules tests · E2E smoke (Playwright) · Secret scan (gitleaks) — parallelized, cancel-in-progress on superseded runs, heavy jobs gated to PRs, build artifact reused by E2E. All required by branch protection on the main branch.

Deployment & environments

• Managed container hosting (Cloud Build → Cloud Run) across production and staging/demo; per-environment secret injection; rollout/rollback and DNS-cutover runbooks; an env-parity workflow guarding config + region consistency.
• Staging-gated promotion: the main branch auto-deploys to staging; production tracks a separate protected branch, so a release is an explicit branch promote (with the Firestore rules/indexes deployed alongside as a deliberate, out-of-band step) — changes bake on staging first and reach production only on demand.

Representative incident-style fixes

• Diagnosed and fixed a CSP directive blocking reCAPTCHA that broke phone-auth in the browser — traced from console errors to the exact frame-src/connect-src gaps, patched with a unit-tested header change, and verified the corrected header live in production.
• Resolved an authorized-domains misconfiguration (auth/captcha-check-failed) by reading the live Identity Platform config via the admin API and adding the serving hostnames — a fix grounded in the actual deployed state rather than guesswork.
• Diagnosed silent production-deploy failures. New Secret Manager secrets had been granted to the runtime service account, but the managed host’s build service account lacked access — so every build failed at secret resolution while the app silently kept serving an old revision. Surfaced it via the rollouts API (the console list was stale), fixed it with the platform’s dedicated secret-grant tooling, recovered both environments, and recorded the gotcha so it can’t recur. Why: a pipeline that fails closed-but-silent is more dangerous than one that fails loud.