Voxandra

Voxandra is an AI platform for multilingual business calls. It translates both sides of live phone conversations, provides private guidance while people talk, and turns each call into a reviewed Call Record.

It runs in production at voxandra.com. This repository is the full app: the Next.js frontend, the Convex backend, and the realtime media worker that carries translated calls.

What it does

• Live Voice Translation. You call from the browser, Voxandra dials the other person, and each side hears the other in their own language. Before the conversation starts, a spoken disclosure plays to both people.
• Live Guidance. While you talk, you get private prompts that only you can see.
• Call Records. After the call you get a transcript with speakers labeled, an AI note, extracted details, contacts, and reminders. You review them before they're saved to your workspace.
• Calls library. Search past calls by meaning, ask questions across them, and get a brief before your next call.
• Read-only MCP server. AI clients can read a workspace's reviewed Call Records through /api/mcp, using personal API keys created in the app.
• Billing. Plans, prepaid calling credits, top-ups, and per-destination rates priced from Twilio's own rate data.

Stack

Layer	Technology
Web app	Next.js (App Router), React, TypeScript, Tailwind CSS
Backend and database	Convex (queries, mutations, actions, crons)
Auth	Convex Auth: email codes, password, and Google
Telephony	Twilio Voice (browser calling, Media Streams, two-leg bridge)
Speech and AI	OpenAI (transcription, extraction, embeddings, realtime guidance) and Palabra (speech-to-speech translation)
Realtime media	Standalone Node WebSocket worker (scripts/realtime-media-worker.mjs)
Billing	Stripe
Email	Resend
Analytics	PostHog EU, browser only, no session replay

Repository layout

src/app/          Next.js routes: public site, /app (signed-in), API routes, webhooks
src/components/   UI, grouped by area (landing, dashboard, calls, memory, dialer, ...)
src/lib/          Shared logic: pricing, billing, Twilio, AI prompts, MCP, rate tables
convex/           Backend: schema, functions, crons, auth, Stripe and Twilio flows
scripts/          Realtime media worker, test suite, smoke tests, rate sync
docs/             Supporting notes and evals

Longer-form docs are in the repo root:

• AGENTS.md: the working guide for anyone, human or AI, changing this code. Covers architecture rules, product rules, and guardrails.
• ARCHITECTURE.md: background on auth, workspaces, and the data model.
• REALTIME_WORKER_RUNBOOK.md: how the translation worker is deployed and operated.

Getting started

Prerequisites

• Node.js 24
• A Convex account (the free tier is enough)
• An OpenAI API key
• A Resend API key, or Google OAuth credentials, so you can sign in. Without one of them, sign-in codes are never delivered.

Twilio, Stripe, Palabra, and PostHog are optional for running the app locally.

1. Install

git clone https://github.com/areia-ai/voxandra.git
cd voxandra
npm install
cp .env.example .env.local

2. Create your Convex deployment

npx convex dev

On the first run you'll be asked to log in and create a project. This writes your own CONVEX_DEPLOYMENT and NEXT_PUBLIC_CONVEX_URL into .env.local, replacing the example values. Keep it running: it pushes backend changes as you edit convex/.

3. Set up auth

In a second terminal, generate the Convex Auth signing keys:

npx @convex-dev/auth

This sets JWT_PRIVATE_KEY, JWKS, and SITE_URL on your Convex deployment.

4. Set backend secrets

Convex functions read their secrets from the Convex deployment, not from .env.local:

npx convex env set OPENAI_API_KEY sk-...

npx convex env set RESEND_API_KEY re_...

For Google sign-in, also set AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET the same way.

5. Run the app

npm run dev

Open http://localhost:3000, sign in, and a personal workspace is created for you.

Configuration

.env.example lists every variable with comments. They're read in three places, and several must match across them:

Where	How it's set	Examples
Next.js app (Vercel)	.env.local locally, project env in production	NEXT_PUBLIC_*, TWILIO_* for webhook validation, STRIPE_SECRET_KEY, MCP_CONVEX_SECRET, REALTIME_STREAM_SIGNING_SECRET
Convex	npx convex env set NAME value	OPENAI_API_KEY, RESEND_API_KEY, AUTH_*, TWILIO_* call limits and allowlists, STRIPE_CONVEX_WEBHOOK_SECRET, MCP_CONVEX_SECRET
Realtime worker	The worker host's environment	OPENAI_* realtime models, PALABRA_API_KEY, REALTIME_* tuning, REALTIME_CONVEX_WORKER_SECRET, REALTIME_STREAM_SIGNING_SECRET

Optional features stay off until you configure them:

• Phone calls: fill in the TWILIO_* block and set NEXT_PUBLIC_TWILIO_CALLING_ENABLED=true. Calls only go to destinations in TWILIO_ALLOWED_COUNTRIES or TWILIO_ALLOWED_NUMBERS that have a rate row. Refresh rates with npm run sync:twilio-rates.
• Translated calls: need the realtime worker (npm run realtime:worker) reachable over a public WebSocket URL set as REALTIME_MEDIA_STREAM_URL, plus the bridge flags described in the runbook.
• Billing: use Stripe test-mode keys and point a Stripe webhook at /api/stripe/webhook.
• Analytics: set NEXT_PUBLIC_POSTHOG_KEY. Leave it blank and nothing is sent.

Commands

Command	What it does
npm run dev	Start the Next.js dev server
npx convex dev	Sync and watch Convex functions
npm test	Run the full regression suite (no live calls or payments)
npm run lint	Lint
npm run build	Production build
npm run realtime:worker	Run the realtime media worker
npx convex codegen	Regenerate Convex types after schema or API changes

The test:*-smoke, probe:*, eval:*, and prewarm:* scripts call paid provider APIs. Read the script before you run it.

Contributing

Pull requests are open. CONTRIBUTING.md covers the contributor license agreement you'll be asked to sign along the way (individual or entity), where to report bugs and security issues, and the checks to run before opening a PR.

Never commit secrets, real phone numbers, or customer data. Use placeholder values in tests and docs.

License

Voxandra is licensed under the GNU Affero General Public License v3.0. If you run a modified version as a network service, you must make your modified source available to its users.