Architecture

Overview

HiringCoachAI is a Next.js application on Vercel, backed by Firebase/GCP, with integrations for payments, email, AI generation, TTS, STT, and analytics. Public traffic for hiringcoach.ai is currently proxied through Cloudflare DNS / edge before reaching Vercel.

Component diagram

flowchart LR
  subgraph Browser["User's browser"]
    UI[Next.js React UI]
  end

  subgraph Cloudflare["Cloudflare edge"]
    CF[DNS / reverse proxy]
  end

  subgraph Edge["Vercel Edge"]
    MW[Middleware: auth, CSP, rate limit]
  end

  subgraph App["Vercel serverless (Next.js API + pages)"]
    API[API routes<br/>request validation]
    CRON[Cron jobs]
    AG[AI Gateway routes]
  end

  subgraph Firebase["Firebase / GCP"]
    AUTH[Firebase Auth]
    FS[(Firestore)]
    GCS[(Cloud Storage<br/>backup/export only)]
    TASK[Cloud Tasks]
    TTS[Google TTS]
    BAK[(Backup bucket<br/>versioned + soft delete)]
  end

  subgraph Payments["Stripe"]
    STRIPE[Stripe hosted Elements / Checkout]
    WH[Webhook handler]
  end

  subgraph AI["AI providers"]
    VAG[Vercel AI Gateway]
    OAI[OpenAI]
    PPX[Perplexity]
    EL[ElevenLabs]
    DG[Deepgram]
  end

  subgraph Comms["Messaging"]
    SG[SendGrid]
    MC[Mailchimp]
  end

  subgraph Observe["Observability"]
    SEN[Sentry]
    AMP[Amplitude]
    MIX[Mixpanel]
    HJ[Hotjar]
    GA[GA / GTM]
    META[Meta Pixel]
  end

  UI -->|HTTPS| CF
  CF --> MW
  MW --> API
  API --> AUTH
  API --> FS
  API --> GCS
  API --> TASK
  API --> AG
  AG --> VAG
  VAG --> OAI
  VAG --> PPX
  API --> EL
  API --> DG
  API --> TTS
  API --> SG
  API --> MC
  STRIPE --> WH
  WH --> FS
  CRON --> FS
  CRON --> BAK
  App --> SEN
  UI --> AMP
  UI --> MIX
  UI --> HJ
  UI --> GA
  UI --> META

Trust boundaries

1. Browser <-> Cloudflare / Vercel Edge: HTTPS, Cloudflare DNS / reverse proxy, Vercel edge, CSP, and HSTS. Cloudflare edge minimum TLS is set to TLS 1.2 and TLS 1.3 is enabled. 2. Vercel Edge <-> Next.js serverless: Vercel-managed edge-to-function routing. Middleware enforces route guards with NextAuth JWTs and may add a short-lived internal bearer token for admin API routes after admin-session validation. Deployment provenance and edge controls are handled through Vercel platform controls and change-management evidence. 3. App <-> Firebase: Server routes use the Firebase Admin SDK initialized from service-account or application-default credentials. Admin SDK calls bypass Firestore Security Rules, so server routes and service modules must enforce authorization before reads/writes. Firestore Security Rules enforce default-deny tenant isolation for browser/client SDK access. 4. App <-> Stripe: API keys held in environment variables. Webhooks are signature-verified in production using the raw body, the stripe-signature request header, and the webhook signing secret; a development-only override exists for local testing and is not enabled in production. 5. App to AI providers: API keys held in environment variables on the hosting platform; per-request storage or transcript-exposure controls are set where available (store: false on covered OpenAI Chat Completions and Responses requests; redact: true on Deepgram transcription requests), verified by an automated check that runs in local compliance checks and the scheduled/manual security workflow. AI calls routed through our internal AI audit handler also write metadata-only audit rows (model, endpoint, token counts, timing; never prompt or completion content). 6. App <-> SendGrid / Mailchimp: API keys held in environment variables with sender/list configuration.

Runtimes

• Next.js version: see package.json
• Node.js: 22.x
• Edge Middleware: Vercel Edge Middleware (Vercel-managed runtime)
• Serverless Functions: Vercel Fluid Compute, Node.js runtime

Data stores

• Firestore (primary OLTP store; Firestore Security Rules enforce tenant isolation)
• Cloud Storage (backup/export buckets and platform-managed function source buckets; user file uploads are not live in production yet)
• No production Redis/cache data store is currently used for rate limiting; the current implementation uses the app's existing rate-limiter utilities.

Networking

• Cloudflare is active for public DNS and reverse proxying of hiringcoach.ai; Cloudflare edge minimum TLS is set to TLS 1.2. Network controls include Cloudflare managed protections documented in the security overview, Vercel platform edge protections, and application-level rate limiting.
• Vercel-managed TLS, HSTS preload, HTTP/3
• Application security headers applied at the request middleware and platform configuration layers
• Vercel platform edge protection and automatic DDoS mitigation apply.
• Live Google Cloud review on 2026-05-07 confirmed the current application traffic path uses Vercel and Cloudflare edge controls rather than Google Cloud load-balancing controls.
• Outbound HTTP from server code to user-controlled URLs is routed through a shared SSRF-blocking helper that rejects private CIDRs and cloud-metadata IPs.

Identity

• NextAuth JWT-based sessions
• Firebase Auth / NextAuth as identity layer (OAuth + email magic link). Application-level TOTP MFA is available as an opt-in user setting on /account/security; the NextAuth JWT carries the MFA-verified state and middleware redirects enrolled-but-unverified sessions to challenge before access. Current administrative accounts are required by policy to use Google Account MFA at the identity-provider layer.
• Firebase tokens carry signed identity claims. Authorization in production checks administrator status against an authoritative server-side store of administrator records; non-administrator users have user-scoped access enforced by Firestore Security Rules.
• Request middleware checks administrator status for admin paths; Firestore Security Rules enforce user-scoping by the authenticated user identifier and the same authoritative admin-status check (not trusted from client-supplied claims).

Observability

• Sentry for errors and performance (10% trace sample in prod)
• LogTape + Sentry for structured logging
• Firestore auditLog for selected auth, account, admin, and consent events; retention target is 2 years and is enforced by the retention runner
• Vercel production/preview log drain to Sentry for selected sources, including firewall, redirect, external, build, and static

CI/CD

• GitHub Actions include manual CI workflows for type check, lint, build, and smoke testing, plus a configured weekly/manual security workflow for npm audit, Semgrep, CodeQL, SBOM, patch verification, unauthenticated ZAP baseline DAST, and compliance audits.
• Branch-protection posture, force-push controls, and required status checks are described in change management.
• Vercel deploys the production branch; rollback is available through Vercel.

Change log

Date	Change
2026-04-24	Initial diagram
2026-05-07	Added verified Cloudflare edge presence, Vercel log drain, Cloud Armor absence, and current audit-log retention enforcement.
2026-05-11	Removed non-production Chrome extension from the current-state architecture boundary.