Data flow diagram

Signup and first signin

sequenceDiagram
  autonumber
  participant U as User
  participant B as Browser
  participant V as Vercel Middleware
  participant A as NextAuth API
  participant F as Firebase Auth
  participant D as Firestore
  participant S as SendGrid

  U->>B: Enter email
  B->>V: POST /api/auth/signin
  V->>A: verified request
  A->>F: create or locate user
  A->>D: record createUser event (auditLog)
  A->>S: send magic-link email
  S-->>U: delivers email
  U->>B: clicks link
  B->>A: callback with token
  A->>D: create session, log signIn
  A-->>B: sets __Secure-next-auth.session-token
  B-->>U: signed in

Resume AI generation

sequenceDiagram
  autonumber
  participant U as User
  participant B as Browser
  participant V as Vercel
  participant Z as Request validation
  participant C as AI audit handler
  participant G as Vercel AI Gateway
  participant O as OpenAI
  participant D as Firestore

  U->>B: clicks "Optimize"
  B->>V: POST AI request
  V->>Z: validate body
  Z->>C: call model
  C->>G: chat completion (store: false)
  G->>O: forwards
  O-->>G: completion
  G-->>C: completion
  C->>D: write AI audit metadata (model, tokens, durations; no prompt/completion)
  Note over C: Generated content is user-reviewable; users review and edit drafts before use.
  C-->>V: completion
  V-->>B: response
  B-->>U: shows draft (user reviews + edits)

> The diagram above shows the canonical AI request path with shared request validation and metadata-only AI audit instrumentation.

Subscription (Stripe)

sequenceDiagram
  autonumber
  participant U as User
  participant B as Browser
  participant A as HiringCoachAI API
  participant SA as Stripe API
  participant SUI as Stripe Checkout / Payment Element
  participant SWH as Stripe Webhook
  participant D as Firestore

  U->>B: click "Upgrade"
  B->>A: start checkout or embedded payment flow
  A->>SA: create Checkout Session, PaymentIntent, or SetupIntent
  SA-->>A: session URL or client secret
  A-->>B: return session URL or client secret
  B->>SUI: redirect or render Stripe-controlled payment UI
  U->>SUI: enters card details (never touches HiringCoachAI)
  SUI->>SA: tokenize, verify, and authorize payment
  SA->>SWH: payment or subscription status event
  SWH->>A: signed webhook
  A->>D: update subscription and billing status
  D-->>B: next page reflects plan

Cardholder data, including primary account number (PAN), card verification value (CVV), and card-track data, is entered only into Stripe-controlled hosted or embedded payment UI. HiringCoachAI receives and stores Stripe identifiers and billing-state metadata, such as customer, subscription, checkout-session, payment-intent, setup-intent, invoice, charge, refund, and dispute identifiers. HiringCoachAI does not receive, store, process, or transmit PAN, CVV, or card-track data.

Data subject export

sequenceDiagram
  autonumber
  participant U as User
  participant A as /api/account/export
  participant D as Firestore

  U->>A: GET /api/account/export (auth + 5/hr rate limit)
  A->>D: read users/{uid} + recursively walk all subcollections
  A->>D: read subscriptions/{uid}
  A->>D: read linked auth/session, audit, AI-audit, and pilot program rows
  A->>D: write auditLog row (action=account.dsr.export)
  A-->>U: JSON download (Content-Disposition: attachment)

> Current implementation note: the export covers users/{uid} + subcollections, subscriptions/{uid}, linked accounts, sessions, authTokens, metadata-only auditLog and aiCallAudit rows, and top-level pilot membership, pilot-admin assignment, pilot-session, pilot-event, and pilot user-daily-rollup rows tied to the user. Vendor-side Stripe customer export, SendGrid contact export, analytics-vendor export, and OAuth-provider export are handled through the DSR workflow with the applicable provider rather than the self-service JSON export. The current flow is synchronous JSON.

Account deletion

sequenceDiagram
  autonumber
  participant U as User
  participant A as /api/account/delete/*
  participant D as Firestore
  participant ST as Stripe
  participant SG as SendGrid

  U->>A: /challenge
  A->>D: write challenge token (15-min TTL)
  A->>SG: email confirm link
  U->>A: /confirm (reauthed)
  A->>D: verify fresh deletion challenge and mark deletion processing
  A->>ST: cancel / verify Stripe subscription if needed
  A->>D: cascade delete user subcollections and linked auth/session rows
  A->>D: delete pilot admin access; anonymize pilot usage rows
  A->>D: record deleted_users audit (365d)
  A->>SG: send deletion confirmation email
  A-->>U: deletion completion or billing-cleanup status

Change log

Date	Change
2026-04-24	Initial diagrams
2026-05-12	Updated DSR export and deletion diagrams to match the current account export and deletion service, including linked pilot program records, anonymized pilot usage retention, and final self-service deletion semantics.