About this app

Architecture

The web application is a Next.js 16 App Router deployment on Vercel, rendered with React 19. The user interface is Bootstrap 3 served through the UC San Diego Decorator v5 bundle, self-hosted with the app. The admin console manages templates, campaigns, invitations, consent documents, interviews, analysis results, and exports. The interview participant flow is token based: the participant opens a personal invitation link, accepts the consent notice, passes the microphone check, and starts the voice interview.

The realtime audio call does not run through Vercel. The participant browser connects directly to Vapi over WebRTC (Daily.co transport) using the Vapi browser SDK. The app assembles a transient Vapi assistant immediately before each call. That assistant includes the current interview template, consent script, participant context, resume state, configured voice, model choice, per-call duration cap, and tool definitions, but it does not include server secrets. Because the assistant configuration transits the participant's browser, the server keeps a hash of the prompt, tools, duration cap, recording settings, and metadata and compares it with what Vapi actually ran at the end of the call. A mismatch parks the interview for human review and it is never analyzed.

Vapi sends status updates, tool calls, transcripts, summaries, and end-of-call reports back to /api/vapi/webhook. The webhook endpoint verifies the org-level Vapi secret, stores every webhook behind an idempotency gate, resolves the call session by the Vapi call id bound by the token-authenticated browser, ignores tool calls and reports from superseded or never-connected sessions, updates the call session, and kicks off the finalization path. Cron sweeps reconcile missed or delayed events, so webhooks are the fast path and polling is the durability backstop.

Neon Postgres (with pgvector) is the source of truth, accessed through Drizzle. It stores campaigns, invitations, interview state, call sessions, stitched transcripts, redacted transcripts, analysis runs, process records, embeddings, clusters, themes, consent events, email events, and an LLM usage ledger. Postgres also acts as the queue for analysis work: each run has a stage cursor, attempt count, lease, cost ledger, model flags, and status. Admin sign-in uses Auth.js v5 email magic links; email goes through Resend; audio recordings are copied to Vercel Blob; scheduled jobs run on Vercel Cron.

Participant flow

1. Invitation: Resend sends a magic link from the verified sender. Links are personal, expire by campaign policy, and rotate whenever they are resent or copied.
2. Written consent: the participant accepts a versioned written consent notice before any call starts. The click is recorded as a consent event pinned to the document version.
3. Voice session: the app mints a call session and transient Vapi assistant. The participant speaks with the voice agent in the browser. Only one call may be live per interview; starting again from another device takes over the interview and ends the superseded call.
4. Spoken consent: the agent reads the consent script and calls the confirm_consent tool with the participant's answer. The participant's own words are stored as evidence. Section completion is refused until a verbal yes is on record, so the agent cannot skip past consent. A verbal decline after content has been captured withdraws the interview and records a withdrawal event.
5. Tool calls: the agent marks sections complete and can pause at the participant's request. Duplicate tool-call deliveries replay the stored result instead of acting twice.
6. Pause and resume: a pause requested by voice or by the Pause button stays a pause, as does a dropped connection or a call that hits the duration cap. Every pause extends the link's resume window by seven days. The next call receives a progress summary and resumes at the next unfinished section.
7. Completion: when the agent concludes the call with spoken consent on record, the transcript is stitched across sessions, the invitation is marked complete, a receipt can be sent, and analysis is queued. If the agent concludes a call without spoken consent on record, the interview is paused for re-confirmation rather than completed, and the same check blocks finalization and analysis.

Voice stack

Analysis pipeline

The analysis pipeline is deliberately staged so each expensive or risky task has a narrow job. A run can resume from its last completed stage and can be re-run without changing prior successful runs until the new run succeeds. Pipeline version: 1.0.

Retries distinguish real errors from interruptions. An error attempt is counted against the run; a lease reclaim (a crash, a deploy, or the sweep's time budget expiring mid-stage) re-queues the run from its stage cursor without consuming an attempt, and is capped separately. Every model call has its own wall-clock timeout, and a run that trips the cost ceiling is failed permanently rather than retried.

Each run has a hard cost circuit breaker of shown to signed-in admins. On-prem Triton stages are recorded as zero marginal LLM cost; direct/cloud model usage is estimated from token counts.

Model routing

Analysis calls use model specs in the form onprem:<id>, cloud:<id>, or anthropic:<id>. Bare model IDs are treated as direct Anthropic models for backward compatibility. The current environment reports:

Fallback policy. When a structured stage's primary model fails or returns invalid output, the run tries the on-campus fallbacks first and a cloud model only when a cloud key is configured. Redaction never falls back to a cloud model unless the operator explicitly opts in; without an on-campus answer it fails closed. Every fallback or off-campus call is recorded on the analysis run and shown on the admin interview page, and a complete usage ledger records model, tokens, cost, and on-campus status for every pipeline stage, dossier, Ask chat turn, and nightly adjudication call.

Prompt versions: redact v2, extract v2, cluster v1, themes v2, dossier v1.

Privacy and data boundaries

• Raw transcript text is stored so administrators can audit interviews, but the analysis pipeline redacts before downstream extraction, embeddings, clustering, and Ask retrieval.
• Deterministic regex rules remove common identifiers such as SSNs, UCSD PID-shaped IDs, emails, phone numbers, dates, and titled personal names before the redaction models run.
• Two on-campus redaction models are each instructed to remove third-party names and personal identifiers while preserving systems, departments, job roles, buildings, and process vocabulary; their answers are unioned. Redaction runs only on campus infrastructure unless the operator explicitly opts into a cloud model.
• Campaigns can anonymize reports so FDE-facing views refer to people by role and department rather than name or email. Viewers never see or export participant names or emails on any campaign.
• Theme synthesis and Ask use active successful analysis outputs; failed and superseded analysis runs are not counted in current campaign themes.
• Audio recording is campaign-controlled. If a retention period is configured, the daily retention job deletes expired recordings, strips raw transcript and recording fields from stored webhook payloads, and removes the raw per-call transcript from analyzed call sessions. The redacted transcript in the analysis tables is the durable copy; rows are never deleted.
• Consent is versioned and captured twice: click-through consent before the call and spoken confirmation during the call. Both are enforced server-side, and the participant's spoken words are stored as evidence.

Operations and reliability

The app uses Vercel Cron and Postgres leases instead of a separate queue service. The call sweep reconciles Vapi calls whose end-of-call report never arrived, retries recording fetches that failed, and closes sessions that were minted but never bound to a call. The analysis sweep resumes queued or lease-expired analysis runs, reminders send pending follow-ups, the retention job expires overdue invitations, auto-finalizes paused interviews after 48 hours of inactivity, and enforces recording and transcript retention, and the nightly recluster job keeps campaign rollups current.

All important external inputs are made idempotent. Vapi webhooks are stored before processing and duplicate tool calls replay their stored result, email sends are logged as email events, analysis stages are wipe-and-rewrite or versioned where appropriate, and successful re-analysis supersedes prior successful runs only after the new run completes.

Access and security

• Admin sign-in uses emailed magic links with an allowlist; there are no passwords. A disabled admin loses access on their next request because the session is re-checked against the user record, and the last active owner cannot be demoted or disabled.
• Roles are owner, admin, fde, and viewer. Viewers see aggregate views and exports only; person-level and dossier exports are refused for viewers on non-anonymized campaigns, and the Service Owner report is name-masked for them.
• Every admin server action validates its input with zod (ids, bounded integers, model-id allowlist, real email addresses, bounded invite metadata). Magic-link requests, invitation sends, reminders, invite-link minting, and report emails are rate limited.
• CSV exports neutralize spreadsheet formula prefixes. Exports and API responses are marked non-cacheable.
• In production the server validates its required configuration on the first request that needs it and fails with a clear message rather than falling back to a localhost default.
• Every page carries Strict-Transport-Security, nosniff, frame denial, a strict referrer policy, a Permissions-Policy that allows the microphone only from this origin, and an enforced Content Security Policy with a per-request script nonce. Invitation and sign-in tokens are stored only as SHA-256 hashes. Vapi webhooks are checked against the org-level shared secret with a constant-time comparison; Resend webhooks are signature-verified.

Verification

Continuous integration runs the typecheck, lint, the unit-test suite, a production build, a dependency audit, a prompt-version consistency check, and a schema-drift check that fails if the database schema changed without a committed migration.

Two live-lifecycle regressions drive the real interview routes and webhook handler against a running dev server with synthetic Vapi events, then let the analysis pipeline run on the on-prem models. The happy path covers consent, sections, end of call, and analysis. The integrity-gates run covers section completion refused before spoken consent, a voice pause staying a pause, duplicate tool-call replay, device takeover neutralizing the old call, an agent-concluded call without consent being paused rather than completed, a verbal decline abandoning the interview, and the analysis run recording no off-campus use. A golden-fixture suite runs the whole pipeline on four synthetic personas with planted identifiers and known ground truth.

None of these replace a real voice call. Audio, turn-taking, and the agent actually calling the tools are only proven live.

Release Notes