# codebucks27/deep-research-ai-agent architecture

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

- Interactive diagram: https://gitdiagram.com/codebucks27/deep-research-ai-agent
- Repository: https://github.com/codebucks27/deep-research-ai-agent

## Overview

##### Project Type and Purpose
- This is a full-stack AI-driven research assistant built with Next.js (App Router) and the Vercel AI SDK.
- Purpose: guide users through an iterative “deep research” workflow—generating follow-up questions, crafting search queries, invoking LLMs and a Web Search API, then compiling a final research report.

##### File Structure (High-Level)
- src/app          → Next.js UI routes and layout
- src/app/api      → Serverless API endpoints (deep-research, generate-questions)
- src/components   → Reusable UI components (Shadcn + custom)
- src/store        → Client-side state (Zustand)
- src/lib          → Utility functions
- Configuration    → next.config.ts, tsconfig.json, .env.example

##### Main Workflow (Focus on Core Flow)
User → Next.js Page UI → “Start Research” trigger
↓
Client fetch to /api/deep-research (route.ts)
↓
API Handler calls service layer:
- activity-tracker.ts (logs progress)
- research-functions.ts (defines iterative loops)
- model-caller.ts (wraps Vercel AI SDK / OpenRouter to LLMs)
- constants/prompts/types (configure prompt templates)
- services.ts (orchestrates Exa Search API calls & LLM calls)
↓
External Services:
- LLMs (Gemini, GPT-4o via Vercel AI SDK/OpenRouter)
- Exa Search API
↓
API Response → Client UI
- Updates Zustand store (src/store/deepResearch.ts)
- Renders components (QnA, ResearchActivities, ResearchReport)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        Page["Page UI"]:::ui
        Layout["App Layout"]:::ui
        QnA["QnA Component"]:::ui
        ResearchActivities["ResearchActivities Component"]:::ui
        ResearchReport["ResearchReport Component"]:::ui
    end

    %% State Layer
    subgraph "State Layer"
        Store["Zustand Store"]:::state
    end

    %% API Layer
    subgraph "API Layer"
        Route["/api/deep-research route"]:::api
        MainHandler["DeepResearch Handler"]:::api
    end

    %% Services Layer
    subgraph "Services Layer"
        ResearchLoop["Research Loop Logic"]:::services
        ActivityTracker["Activity Tracker"]:::services
        ModelCaller["Model Caller"]:::services
        ExternalOrch["External Orchestration"]:::services
    end

    %% External Services
    subgraph "External Services"
        LLM["LLM Providers"]:::external
        SearchAPI["Exa Search API"]:::external
    end

    %% Connections
    Page -->|Start Research| Route
    Route -->|invoke Handler| MainHandler
    MainHandler -->|uses| ResearchLoop
    MainHandler -->|logs to| ActivityTracker
    MainHandler -->|calls| ModelCaller
    MainHandler -->|coordinates| ExternalOrch
    ExternalOrch -->|send prompt| LLM
    ExternalOrch -->|search query| SearchAPI
    ExternalOrch -->|returns results| MainHandler
    MainHandler -->|responds with data| Store
    Store --> QnA
    Store --> ResearchActivities
    Store --> ResearchReport

    %% Click Events
    click Page "https://github.com/codebucks27/deep-research-ai-agent/blob/main/src/app/page.tsx"
    click Layout "https://github.com/codebucks27/deep-research-ai-agent/blob/main/src/app/layout.tsx"
    click Route "https://github.com/codebucks27/deep-research-ai-agent/blob/main/src/app/api/deep-research/route.ts"
    click MainHandler "https://github.com/codebucks27/deep-research-ai-agent/blob/main/src/app/api/deep-research/main.ts"
    click ActivityTracker "https://github.com/codebucks27/deep-research-ai-agent/blob/main/src/app/api/deep-research/activity-tracker.ts"
    click ResearchLoop "https://github.com/codebucks27/deep-research-ai-agent/blob/main/src/app/api/deep-research/research-functions.ts"
    click ModelCaller "https://github.com/codebucks27/deep-research-ai-agent/blob/main/src/app/api/deep-research/model-caller.ts"
    click ExternalOrch "https://github.com/codebucks27/deep-research-ai-agent/blob/main/src/app/api/deep-research/services.ts"
    click Store "https://github.com/codebucks27/deep-research-ai-agent/blob/main/src/store/deepResearch.ts"
    click QnA "https://github.com/codebucks27/deep-research-ai-agent/blob/main/src/components/ui/deep-research/QnA.tsx"
    click ResearchActivities "https://github.com/codebucks27/deep-research-ai-agent/blob/main/src/components/ui/deep-research/ResearchActivities.tsx"
    click ResearchReport "https://github.com/codebucks27/deep-research-ai-agent/blob/main/src/components/ui/deep-research/ResearchReport.tsx"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,color:#000;
    classDef state fill:#F3E5F5,stroke:#8E44AD,color:#000;
    classDef api fill:#DFFFE0,stroke:#27AE60,color:#000;
    classDef services fill:#FFE5B4,stroke:#E67E22,color:#000;
    classDef external fill:#FFCCCC,stroke:#C0392B,color:#000;
```
