Ravendr

Voice-first research demo. Click the mic, say a topic, get a cited briefing back.
Every step is a Render Workflow task.

What it does

Tap the mic and say a research topic. Anything works: "Tell me about the Battle of Hastings", "List every tribe in the Bible", "Compare React Server Components and Remix loaders". About sixty seconds later, you get a cited briefing on screen, read aloud in a synthesized voice.

Behind the scenes the app classifies your ask, plans a fan-out of search queries, hits You.com in parallel, writes the briefing with Anthropic Sonnet, and verifies it for completeness. Every one of those steps runs as its own Render Workflow task that you can open in the dashboard, inspect, and replay.

Stack

	Platform	Job
	Render Workflows	Orchestrator. Every step of the pipeline runs as its own retriable, observable Render task.
	AssemblyAI Voice Agent	Speech in, speech out. A single streaming WebSocket that handles transcription, LLM reasoning, and text-to-speech.
	Mastra	Agent runtime. Powers the classifier, planner, synthesizer, and verifier (Anthropic Sonnet 4 under the hood, see ANTHROPIC_MODEL in src/config.ts).
	You.com Research	The search layer. One call per planned angle, fanned out in parallel.

Architecture

Prerequisites

Account / Tool	Why
Render	Hosts the web service, Postgres, and Workflow runner.
AssemblyAI	Voice Agent API key.
Anthropic	API key for the Mastra agents (Sonnet).
You.com	Search API key.
Node 22+	Local development.
Postgres	Local development (Render Postgres in production).

Configuration

Required environment variables on both the web service and the workflow service unless noted otherwise:

Variable	Description	Source
DATABASE_URL	Postgres connection string.	Render auto-injects from the ravendr-db Blueprint. Set it manually for local dev.
ANTHROPIC_API_KEY	Used by every Mastra agent.	https://console.anthropic.com
YOU_API_KEY	Used by search_branch.	https://you.com/platform
ASSEMBLYAI_API_KEY	Used by voice_session.	https://www.assemblyai.com/app
ANTHROPIC_MODEL	Override the LLM (default claude-sonnet-4-20250514).	Optional.
RENDER_API_KEY	Web service only. Used to dispatch and cancel Workflow runs.	https://dashboard.render.com/settings/api-keys
WORKFLOW_SLUG	Web service only. Slug of the Workflow service (default ravendr-workflow).	Your Render dashboard.

Run locally

cp .env.example .env       # fill in API keys
createdb ravendr           # local Postgres
npm install
npm run migrate            # apply migrations
npm run dev                # web service on :3000
npm run dev:tasks          # workflow runner in a second terminal

Deploy

1. Fork. Hit Deploy to Render. The Blueprint creates ravendr-web + ravendr-db.
2. In the dashboard, create a Workflow service ravendr-workflow, same repo, start command node dist/render/tasks/index.js.
3. Put secrets in an env group ravendr-shared so both services share them.
4. Migrations run on every web deploy via preDeployCommand: npm run migrate.

Repo layout

One folder per vendor. Each owns its protocol or SDK; the Render task files are thin orchestration glue that compose them.

src/
  server.ts  routes.ts  config.ts    web service composition root
  assemblyai/                         AssemblyAI WebSocket protocol client
  mastra/                             Agent factories (classifier, planner, synthesizer, verifier)
  youcom/                             You.com Research API adapter
  render/
    db.ts  event-bus.ts  session-broker.ts  workflow-dispatcher.ts
    tasks/                            workflow tasks (auto-registered by tasks/index.ts)
      research.ts                     orchestrator
      assemblyai/voice-session.ts     root task; holds AssemblyAI + reverse WS
      mastra/                         classify-ask · plan-queries · synthesize · verify
      youcom/search-branch.ts         one You.com call (× N parallel)
  shared/                             ports · events · errors · envelope · logger

static/                               vanilla ES modules (index.html · main.js · mic.js)
migrations/                           sequenced .sql files applied by npm run migrate

Troubleshooting

Symptom	Fix
Failed to create session after deploy	Migrations have not run. Set preDeployCommand: npm run migrate on the web service in the Render dashboard, then redeploy.
Workflow tasks fail with RENDER_API_KEY missing	The web service needs RENDER_API_KEY set so it can dispatch Workflow runs. Add it in the env group ravendr-shared.
503 AT_CAPACITY from /api/start	The demo is at its 100-session cap. Wait a minute, or bump MAX_CONCURRENT_SESSIONS in src/config.ts.
Task disappears from the dashboard mid-session	The cleanup daemon cancelled it because the 15-minute TTL elapsed. Start a new session.
Voice goes silent during research	AssemblyAI's agent does not always narrate the tool result. The briefing still renders on screen with sources, so the experience is preserved.

License

MIT