ConvAI

ConvAI is an AI conversation-intelligence MVP for business calls. It records or ingests a conversation, turns the transcript into structured diligence signals, and presents a report with a deal-quality score, claims, contradictions, red flags, strengths, blind spots, and follow-up questions.

This repository is portfolio-ready as a full-stack TypeScript monorepo: Express API, PostgreSQL/Supabase persistence, BullMQ worker, staged LLM pipeline, Next.js dashboard, Expo mobile app, and shared domain models.

Demo

Watch the product demo: ConvAI portfolio demo

The fastest reviewer path is the deterministic web demo. It does not require Clerk, Postgres, Redis, AssemblyAI, or LLM keys.

corepack enable
pnpm install
pnpm demo:web

Open http://localhost:3000, then:

1. Click Try sample call and open Northstar Seed Pitch.
2. Review the score, summary, strengths, red flags, evidence-backed claims, and follow-up checklist.
3. Open the transcript.
4. Use Export to download the sample report as JSON.
5. Go to Upload transcript, paste or upload a .txt transcript, and run the local portfolio analyzer.

Demo mode is controlled by NEXT_PUBLIC_DEMO_MODE=true and uses the sample dataset in apps/web/lib/demoData.ts.

Product Features

• Session dashboard with ready, processing, and error states.
• Recruiter-friendly start screen with sample-call and upload-transcript paths.
• Session detail page with score gauge, timeline, report summary, evidence-backed claims, red flags, strengths, and follow-up checklist.
• Transcript viewer with speaker labels and timestamps.
• Local transcript upload demo that produces a quick structured analysis without external services.
• JSON report export for sharing or downstream analysis.
• Expo mobile flow for creating sessions, recording audio locally, ending sessions, and viewing report status.
• AssemblyAI webhook handling for transcript persistence.
• BullMQ worker that runs the AI pipeline and stores reports.
• Staged LLM pipeline for segmentation, business extraction, claim analysis, contradiction detection, scoring, and report generation.

Architecture

flowchart LR
  Mobile["Expo mobile app"] --> API["Express API"]
  Web["Next.js dashboard"] --> API
  API --> DB[("PostgreSQL / Supabase")]
  API --> WS["WebSocket audio ingestion"]
  API --> AAI["AssemblyAI transcription"]
  AAI --> Webhook["Transcript webhook"]
  Webhook --> DB
  Webhook --> Queue["BullMQ / Redis"]
  Queue --> Worker["Pipeline worker"]
  Worker --> Pipeline["AI pipeline"]
  Pipeline --> LLM["Gemini or Anthropic"]
  Pipeline --> DB
  Web --> Demo["Local demo dataset"]

Loading

Workspaces

• packages/shared - shared TypeScript domain types and constants.
• packages/api - Express API, PostgreSQL access, webhooks, WebSocket ingestion, BullMQ queue, report export.
• packages/ai-pipeline - staged LLM analysis pipeline.
• apps/web - Next.js dashboard with live API mode and deterministic demo mode.
• apps/mobile - Expo mobile app with session creation, local recording, and report views.

Full Setup

corepack enable
pnpm install
cp .env.example .env

For the full live workflow, fill these values in .env:

• DATABASE_URL - Supabase/Postgres connection string.
• CLERK_SECRET_KEY and NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY - Clerk auth keys.
• LLM_PROVIDER - gemini or anthropic.
• GEMINI_API_KEY or ANTHROPIC_API_KEY - selected LLM provider key.
• ASSEMBLYAI_API_KEY and ASSEMBLYAI_WEBHOOK_SECRET - transcription and webhook verification.
• UPSTASH_REDIS_URL - BullMQ queue connection.
• NEXT_PUBLIC_DEMO_MODE=false - use live API data instead of the sample dataset.

Apply the database schema:

pnpm --filter @convai/api db:migrate

Run services:

pnpm --filter @convai/api dev
pnpm --filter @convai/api worker
pnpm --filter web dev
pnpm --filter mobile start

Default local ports:

• API: http://localhost:3001
• Web: http://localhost:3000
• Expo Metro: http://localhost:8081

Verification

pnpm test
pnpm type-check
pnpm lint
pnpm build

Current test coverage focuses on the highest-risk MVP contracts:

• AI pipeline orchestration and stage JSON validation.
• API row-to-domain mappers.
• AssemblyAI webhook secret verification.

API smoke check:

curl http://localhost:3001/health

Authenticated API checks require a Clerk JWT:

curl -H "Authorization: Bearer <token>" http://localhost:3001/v1/sessions

Implementation Status

Implemented:

• DB-backed users, sessions, transcripts, reports, and report export.
• AssemblyAI webhook persistence and BullMQ queue handoff.
• Pipeline worker that stores generated reports and updates session status.
• WebSocket audio chunk persistence.
• Mobile session creation, local recording, session ending, and report fetch.
• Deterministic web demo mode for portfolio review.
• Local transcript-upload demo for recruiter testing without external credentials.
• Focused tests for AI pipeline and API service contracts.

Known gaps:

• PDF export intentionally returns 501; JSON export is implemented.
• Mobile recording is local, but upload/finalization into the transcription workflow is not finished.
• Clerk mobile auth screens are placeholders around the token storage flow.
• Search, filters, and manual reprocessing are intentionally disabled until server-side support exists.
• Integration tests with a real database/auth token are still future hardening work.