# drewsephski/vercel-ai-sdk-deep-research-agent architecture

> Architecture diagram of the GitHub repository drewsephski/vercel-ai-sdk-deep-research-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/drewsephski/vercel-ai-sdk-deep-research-agent
- Repository: https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent

## Overview

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: [`src/trigger/deepResearch.ts`](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/trigger/deepResearch.ts) (Deep research), [`src/components/DeepResearchAgent.tsx`](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/components/DeepResearchAgent.tsx) (Deep Research), [`src/app/api/research-sessions/[id]/route.ts`](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/api/research-sessions/[id]/route.ts) (Session API), [`src/app/api/checkout/route.ts`](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/api/checkout/route.ts) (Billing API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_landing["Landing<br/>page<br/>[page.tsx]"]
  node_pricing["Pricing<br/>page<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>page<br/>[page.tsx]"]
  node_research["Research<br/>page<br/>[page.tsx]"]
  node_signauth["Sign in/up<br/>auth pages<br/>[page.tsx]"]
  node_landingcmp["Landing page<br/>ui shell<br/>[LandingPage.tsx]"]
  node_deepui["Deep Research<br/>client orchestrator"]
  node_workflowui["Workflow UI<br/>steps & states<br/>[ResearchSteps.tsx]"]
end

subgraph group_server["Next.js app"]
  node_clarifyapi["Clarify API<br/>route handler<br/>[route.ts]"]
  node_researchapi["Session API<br/>route handlers<br/>[route.ts]"]
  node_billingapi["Billing API<br/>route handlers<br/>[route.ts]"]
  node_middleware["Middleware<br/>auth guard<br/>[middleware.ts]"]
end

subgraph group_workers["Background jobs"]
  node_researchjob{{"Deep research<br/>trigger task<br/>[deepResearch.ts]"}}
  node_reportjob{{"Report task<br/>trigger task<br/>[generateReport.ts]"}}
  node_pdfjob{{"PDF task<br/>trigger task"}}
end

subgraph group_data["Data & billing"]
  node_sessionlib["Session lib<br/>server logic"]
  node_subscriptionlib["Subscription lib<br/>server logic<br/>[subscriptions.ts]"]
  node_dbschema["DB schema<br/>drizzle schema<br/>[schema.ts]"]
end

subgraph group_external["External systems"]
  node_ai(("AI models"))
  node_exa(("Exa<br/>search API"))
  node_stripe(("Stripe<br/>billing provider"))
  node_neon[("Neon Postgres<br/>database")]
  node_r2[("Cloudflare R2<br/>object storage")]
  node_auth(("Auth provider<br/>identity service"))
  node_triggerdev(("Trigger.dev<br/>job runtime"))
end

node_landing -->|"renders"| node_landingcmp
node_landing -->|"navigates"| node_research
node_pricing -->|"starts checkout"| node_billingapi
node_signauth -->|"authenticates"| node_auth
node_middleware -->|"protects"| node_dashboard
node_middleware -->|"protects"| node_research
node_dashboard -->|"loads sessions"| node_researchapi
node_research -->|"hosts"| node_deepui
node_deepui -->|"composes"| node_workflowui
node_deepui -->|"asks follow-up"| node_clarifyapi
node_deepui -->|"starts task"| node_researchjob
node_researchjob -->|"runs on"| node_triggerdev
node_researchjob -->|"reasons with"| node_ai
node_researchjob -->|"searches"| node_exa
node_researchjob -->|"reads/writes"| node_sessionlib
node_researchjob -->|"hands off"| node_reportjob
node_reportjob -->|"writes report"| node_ai
node_reportjob -->|"passes artifact"| node_pdfjob
node_pdfjob -->|"uploads"| node_r2
node_researchapi -->|"uses"| node_sessionlib
node_researchapi -->|"persists"| node_dbschema
node_billingapi -->|"integrates"| node_stripe
node_billingapi -->|"updates access"| node_subscriptionlib
node_subscriptionlib -->|"reads state"| node_dbschema
node_sessionlib -->|"stores"| node_neon
node_dbschema -->|"backed by"| node_neon
node_deepui -.->|"realtime hook"| node_triggerdev
node_clarifyapi -.->|"classifies"| node_ai

click node_landing "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/page.tsx"
click node_pricing "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/pricing/page.tsx"
click node_dashboard "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/dashboard/page.tsx"
click node_research "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/research/page.tsx"
click node_signauth "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/sign-in/[[...sign-in]]/page.tsx"
click node_landingcmp "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/components/LandingPage.tsx"
click node_deepui "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/components/DeepResearchAgent.tsx"
click node_workflowui "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/components/ResearchSteps.tsx"
click node_clarifyapi "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/api/clarify/route.ts"
click node_researchapi "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/api/research-sessions/[id]/route.ts"
click node_billingapi "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/api/checkout/route.ts"
click node_middleware "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/middleware.ts"
click node_sessionlib "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/lib/research-sessions.ts"
click node_subscriptionlib "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/lib/subscriptions.ts"
click node_dbschema "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/db/schema.ts"
click node_researchjob "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/trigger/deepResearch.ts"
click node_reportjob "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/trigger/generateReport.ts"
click node_pdfjob "https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/trigger/generatePdfAndUpload.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_landing,node_pricing,node_dashboard,node_research,node_signauth,node_landingcmp,node_deepui,node_workflowui toneBlue
class node_clarifyapi,node_researchapi,node_billingapi,node_middleware toneAmber
class node_researchjob,node_reportjob,node_pdfjob toneMint
class node_sessionlib,node_subscriptionlib,node_dbschema toneRose
class node_ai,node_exa,node_stripe,node_neon,node_r2,node_auth,node_triggerdev toneIndigo
```

## Components

### Frontend

Public, auth, and research UI surfaces.

- [Landing](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/page.tsx): page · Public marketing entry and home page. · `src/app/page.tsx`
- [Pricing](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/pricing/page.tsx): page · Public pricing surface. · `src/app/pricing/page.tsx`
- [Dashboard](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/dashboard/page.tsx): page · Authenticated overview surface. · `src/app/dashboard/page.tsx`
- [Research](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/research/page.tsx): page · Primary research workspace. · `src/app/research/page.tsx`
- [Sign in/up](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/sign-in/[[...sign-in]]/page.tsx): auth pages · Dedicated authentication routes. · `src/app/sign-in/[[...sign-in]]/page.tsx`
- [Landing page](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/components/LandingPage.tsx): ui shell · Shared marketing page composition. · `src/components/LandingPage.tsx`
- [Deep Research](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/components/DeepResearchAgent.tsx): client orchestrator · Client-side research flow controller with realtime task updates. · `src/components/DeepResearchAgent.tsx`
- [Workflow UI](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/components/ResearchSteps.tsx): steps & states · Research steps, progress, clarification, and completion components. · `src/components/ResearchSteps.tsx`

### Next.js app

Route handlers, middleware, and server-side application logic.

- [Clarify API](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/api/clarify/route.ts): route handler · Collects or resolves follow-up questions for ambiguous topics. · `src/app/api/clarify/route.ts`
- [Session API](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/api/research-sessions/[id]/route.ts): route handlers · Research session CRUD and state boundaries. · `src/app/api/research-sessions/[id]/route.ts`
- [Billing API](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/app/api/checkout/route.ts): route handlers · Checkout, portal, subscription, credits, and Stripe webhook entry points. · `src/app/api/checkout/route.ts`
- [Middleware](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/middleware.ts): auth guard · Protects authenticated areas and routes. · `src/middleware.ts`

### Background jobs

Trigger.dev task pipeline for research and artifact generation.

- [Deep research](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/trigger/deepResearch.ts): trigger task · Recursive research pipeline that searches, evaluates, and accumulates findings. · `src/trigger/deepResearch.ts`
- [Report task](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/trigger/generateReport.ts): trigger task · Transforms research output into a structured report. · `src/trigger/generateReport.ts`
- [PDF task](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/trigger/generatePdfAndUpload.ts): trigger task · Converts report output to PDF and uploads the artifact. · `src/trigger/generatePdfAndUpload.ts`

### Data & billing

Database, sessions, subscriptions, and payments.

- [Session lib](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/lib/research-sessions.ts): server logic · Centralized research session persistence and lookup logic. · `src/lib/research-sessions.ts`
- [Subscription lib](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/lib/subscriptions.ts): server logic · Plan, credits, and access checks. · `src/lib/subscriptions.ts`
- [DB schema](https://github.com/drewsephski/vercel-ai-sdk-deep-research-agent/blob/main/src/db/schema.ts): drizzle schema · Drizzle tables and relational model. · `src/db/schema.ts`

### External systems

Search, model, storage, and auth providers.

- **AI models**: Vercel AI SDK + OpenAI · Model layer for query generation, evaluation, and report synthesis.
- **Exa**: search API · Semantic search and web evidence retrieval.
- **Stripe**: billing provider · Checkout, portal, and webhook source of truth for billing state.
- **Neon Postgres**: database · Persistent store for users, sessions, and billing state.
- **Cloudflare R2**: object storage · Stores generated PDF artifacts.
- **Auth provider**: identity service · User authentication/session boundary used by the app.
- **Trigger.dev**: job runtime · Background execution and realtime task updates.

## Connections

- 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.
