How drewsephski/vercel-ai-sdk-deep-research-agent works
1. Overall shape
- This is a Next.js App Router application with a split between:
- public marketing/auth pages,
- authenticated research workflow pages,
- API routes for app state and billing,
- background jobs handled by Trigger.dev.
- The system is centered on one main product flow: user submits a research topic → agent researches recursively → report is generated → PDF is created and stored.
2. Frontend surfaces
- src/app/page.tsx, pricing/page.tsx, and src/components/LandingPage.tsx form the public marketing entry.
- dashboard/page.tsx and research/page.tsx are the main application surfaces.
- sign-in and sign-up routes indicate a dedicated authentication entry point, while middleware.ts likely protects authenticated areas.
- UI is composed from small reusable components plus a shared design system in src/components/ui.
3. Core research experience
- src/components/DeepResearchAgent.tsx is the main client-side orchestrator for the research UI.
- It uses Trigger.dev’s realtime hook to start the research task and receive live progress updates.
- Supporting components like ResearchSteps, progress-section, ResearchComplete, and ClarifyingChat represent the workflow stages: input, progress, clarification, and finished output.
4. Background orchestration boundary
- The heavy work does not happen in the request/response cycle.
- src/trigger/deepResearch.ts coordinates the research pipeline as a Trigger.dev task.
- It delegates to other tasks:
- generateReport.ts for report synthesis,
- generatePdfAndUpload.ts for PDF conversion and storage upload.
- This separation keeps the web app responsive while long-running work executes in background workers.
5. Research data flow
- The deep research task performs a recursive search strategy:
- generate queries,
- search the web via Exa,
- evaluate result relevance with an AI model,
- extract learnings and follow-up questions,
- recurse until depth limits are hit.
- The accumulated output becomes structured research data, then a report, then a PDF.
- Live status is pushed through task metadata so the UI can show “searching”, “analyzing”, “generating report”, etc.
6. AI and external research services
- The project uses the Vercel AI SDK as the model integration layer.
- The README describes OpenAI GPT-4o as the default model for:
- query generation,
- result evaluation,
- report creation.
- Exa API is the semantic search/crawling backend for source discovery.
- These are the two main intelligence boundaries: model reasoning + web evidence retrieval.
7. Report and file production
- After research completes, generateReport.ts turns the research graph into a structured HTML report.
- generatePdfAndUpload.ts then converts that HTML into a PDF using LibreOffice and uploads it to Cloudflare R2.
- This means the final deliverable is not just on-screen content; it is a generated artifact stored in cloud object storage.
8. Persistence layer
- src/db/schema.ts and src/db/index.ts define a Drizzle ORM layer on top of Neon Postgres.
- The drizzle/ migrations and snapshots show schema evolution is managed explicitly.
- The database appears to track at least:
- users,
- research sessions,
- credits or subscription-related state.
- API routes under research-sessions, user/credits, and subscription are the app’s DB-facing boundaries.
9. Billing and access control
- The presence of checkout, portal, subscription, and webhooks/stripe routes indicates a Stripe-based billing subsystem.
- PaywallModal suggests research usage is gated by subscription/credits.
- Stripe webhooks are the asynchronous source of truth for billing state changes, which then feed back into the database and app access logic.
10. Clarification and conversation flow
- src/app/api/clarify/route.ts plus ClarifyingChat.tsx suggest the agent can ask follow-up questions before or during research.
- This is likely a smaller interaction loop inside the broader research workflow: if the topic is ambiguous, the app collects more detail before launching or deepening the task.
11. Session and state management
- src/lib/research-sessions.ts centralizes session-related DB logic.
- src/lib/subscriptions.ts likely centralizes plan/credit checks and billing state evaluation.
- src/lib/auth.ts isolates auth/session handling.
- These libraries form the server-side application boundary between UI/API and persistence.
12. Operational and deployment concerns
- trigger.config.ts and src/trigger/* are required for Trigger.dev runtime configuration and worker registration.
- next.config.mjs, Tailwind/PostCSS config, and components.json support the UI build layer.
- The app therefore has two operational runtimes:
- the Next.js web server for UI + API routes,
- the Trigger.dev worker/runtime for research jobs and document generation.
13. What to draw in an architecture diagram
- A useful diagram would place the browser/UI on the left, the Next.js app in the center, and the external systems on the right:
- Trigger.dev for orchestration/realtime,
- OpenAI/Vercel AI SDK and Exa for intelligence/search,
- Neon Postgres for state,
- Stripe for billing,
- Cloudflare R2 for PDF storage.
- The main arrows should show:
- user submits research topic from the UI,
- UI triggers a realtime background job,
- job reads/writes session and billing data as needed,
- job returns progress and final artifact links,
- billing webhooks update subscription state independently of the user flow.
Main entry points: deepResearch.ts Deep research · DeepResearchAgent.tsx Deep Research · [id]/route.ts Session API · checkout/route.ts Billing API
Components 25
Frontend
Public, auth, and research UI surfaces.
- Landing · Public marketing entry and home page.
src/app/page.tsx - Pricing · Public pricing surface.
src/app/pricing/page.tsx - Dashboard · Authenticated overview surface.
src/app/dashboard/page.tsx - Research · Primary research workspace.
src/app/research/page.tsx - Sign in/up · Dedicated authentication routes.
src/app/sign-in/[[...sign-in]]/page.tsx - Landing page · Shared marketing page composition.
src/components/LandingPage.tsx - Deep Research · Client-side research flow controller with realtime task updates.
src/components/DeepResearchAgent.tsx - Workflow UI · Research steps, progress, clarification, and completion components.
src/components/ResearchSteps.tsx
Next.js app
Route handlers, middleware, and server-side application logic.
- Clarify API · Collects or resolves follow-up questions for ambiguous topics.
src/app/api/clarify/route.ts - Session API · Research session CRUD and state boundaries.
src/app/api/research-sessions/[id]/route.ts - Billing API · Checkout, portal, subscription, credits, and Stripe webhook entry points.
src/app/api/checkout/route.ts - Middleware · Protects authenticated areas and routes.
src/middleware.ts
Background jobs
Trigger.dev task pipeline for research and artifact generation.
- Deep research · Recursive research pipeline that searches, evaluates, and accumulates findings.
src/trigger/deepResearch.ts - Report task · Transforms research output into a structured report.
src/trigger/generateReport.ts - PDF task · Converts report output to PDF and uploads the artifact.
src/trigger/generatePdfAndUpload.ts
Data & billing
Database, sessions, subscriptions, and payments.
- Session lib · Centralized research session persistence and lookup logic.
src/lib/research-sessions.ts - Subscription lib · Plan, credits, and access checks.
src/lib/subscriptions.ts - DB schema · Drizzle tables and relational model.
src/db/schema.ts
External systems
Search, model, storage, and auth providers.
- AI models · Model layer for query generation, evaluation, and report synthesis.
- Exa · Semantic search and web evidence retrieval.
- Stripe · Checkout, portal, and webhook source of truth for billing state.
- Neon Postgres · Persistent store for users, sessions, and billing state.
- Cloudflare R2 · Stores generated PDF artifacts.
- Auth provider · User authentication/session boundary used by the app.
- Trigger.dev · Background execution and realtime task updates.
Connections 28
- Landing → Landing page: renders · Home page is composed from shared marketing UI.
- Landing → Research: navigates · Entry flow leads to the research experience.
- Pricing → Billing API: starts checkout · Pricing surface connects to billing actions.
- Sign in/up → Auth provider: authenticates · Sign-in and sign-up routes delegate to the identity provider.
- Middleware → Dashboard: protects · Authenticated pages are guarded at the edge.
- Middleware → Research: protects · Research workspace is access-controlled.
- Dashboard → Session API: loads sessions · Dashboard reads and manages research sessions.
- Research → Deep Research: hosts · Research page mounts the main client orchestrator.
- Deep Research → Workflow UI: composes · Client orchestrator renders workflow-stage components.
- Deep Research → Clarify API: asks follow-up · Clarification loop is handled through an API route.
- Deep Research → Deep research: starts task · Client kicks off the background research pipeline.
- Deep research → Trigger.dev: runs on · Research executes as a Trigger.dev job.
- Deep research → AI models: reasons with · Generates queries, evaluates results, and refines findings.
- Deep research → Exa: searches · Retrieves web evidence and source material.
- Deep research → Session lib: reads/writes · Updates research session state and status.
- Deep research → Report task: hands off · Research output feeds report synthesis.
- Report task → AI models: writes report · Uses model output to synthesize the report.
- Report task → PDF task: passes artifact · Structured report becomes input for PDF generation.
- PDF task → Cloudflare R2: uploads · Final PDF is stored in object storage.
- Session API → Session lib: uses · Session routes centralize through shared session logic.
- Session API → DB schema: persists · Session state is backed by the database model.
- Billing API → Stripe: integrates · Checkout, portal, and webhook routes connect to Stripe.
- Billing API → Subscription lib: updates access · Billing changes flow into subscription evaluation logic.
- Subscription lib → DB schema: reads state · Credits and plan state are stored in Postgres.
- Session lib → Neon Postgres: stores · Research sessions are persisted in Neon Postgres.
- DB schema → Neon Postgres: backed by · Drizzle schema maps to the Postgres database.
- Deep Research → Trigger.dev: realtime hook · UI receives live task progress from the job runtime.
- Clarify API → AI models: classifies · Clarification can use model reasoning for question generation.