# nickscamara/open-deep-research architecture

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

- Interactive diagram: https://gitdiagram.com/nickscamara/open-deep-research
- Repository: https://github.com/nickscamara/open-deep-research

## Overview

##### Project’s Type and Purpose
- This is a full-stack web application built with Next.js, which serves both as a frontend UI (for chat and authentication) and a backend API (for chat actions, document extraction, search, etc.). Its purpose is to perform deep research by combining real-time web search/extraction (via Firecrawl) with AI reasoning and chat capabilities.
- It integrates multiple external services such as AI model providers (OpenAI, Anthropic, TogetherAI), Vercel Postgres for chat history and user data persistence, Vercel Blob for file storage, and NextAuth for authentication.

##### File Structure for Architectural Clues
- The top-level “app” directory uses Next.js’s new App Router. Inside it, there are subdirectories like (auth) and (chat) splitting authentication functionality from chatting and document handling.
- The /app/(auth)/api and /app/(chat)/api directories host server-side endpoints (such as authentication routes, chat routes, document extraction, history, suggestions, etc.), indicating clear separation between public facing pages and internal API handling.
- The “components” folder contains reusable UI pieces (from chat headers, code editors to sidebar and theming components) that help build user interfaces.
- The “lib” directory contains business logic for AI integration (lib/ai), database interactions (lib/db – including migration and schema files), and even editor functionalities (lib/editor), which further underlines the application's modular architecture.
- Other directories like “hooks” show custom React hooks used for state management and UI behavior. Configuration files such as next.config.ts, Dockerfile, and environment example files reinforce that this project is set up to work in a cloud and containerized environment.

##### Examining the README for More Insights
- The README confirms that this is a Next.js application using the App Router, leveraging modern React features such as React Server Components and Server Actions.
- It emphasizes integrations with external services including Firecrawl (for search & data extraction) and multiple AI model providers, with additional configurations (e.g., for reasoning models) exposed via environment variables.
- Deployment instructions and local development guidelines suggest that the system is designed to be modular, configurable, and ready to scale, intended to support both real-time user interactions and long-running analysis (with function timeouts).

##### What
- Use clear labels for every major component (e.g., “Client/Browser,” “Next.js Frontend (UI & Pages),” “Auth API,” “Chat API,” “AI Service Layer,” “Database,” “External Services”).
- Rectangles for application components.
- That areas like routing (using Next.js App Router), real-time data feeds from Firecrawl, and AI reasoning are clearly captured.

##### Final Advice
- Avoid oversimplification: ensure every service’s role (authentication, chat processing, document extraction, and model reasoning) is represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        client["Client/Browser"]:::clientStyle
        frontend["Next.js Frontend (Pages)"]:::frontendStyle
        uiComponents["UI Components Library"]:::frontendStyle
    end

    %% API Layer
    subgraph "API Layer"
        authAPI["Authentication Endpoints & Pages"]:::apiStyle
        chatAPI["Chat Endpoints & Pages"]:::apiStyle
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        aiIntegration["AI Integration Layer"]:::businessStyle
        editor["Editor & Utility Services"]:::businessStyle
    end

    %% Data & External Layer
    subgraph "Data & External Layer"
        database["Database (Vercel Postgres)"]:::dataStyle
        storage["File Storage (Vercel Blob)"]:::dataStyle
        external["External Services (Firecrawl, NextAuth)"]:::externalStyle
    end

    %% Connections between layers
    client -->|"HTTP_Request"| frontend
    frontend -->|"Renders_UI"| uiComponents
    frontend -->|"API_Call"| authAPI
    frontend -->|"API_Call"| chatAPI
    authAPI -->|"Process_Auth"| aiIntegration
    chatAPI -->|"Process_Chat"| aiIntegration
    frontend -->|"Utilize"| editor
    aiIntegration -->|"DB_Query"| database
    aiIntegration -->|"Store_Files"| storage
    aiIntegration -->|"External_Request"| external

    %% Click Events for component mapping
    click frontend "https://github.com/nickscamara/open-deep-research/tree/main/app/"
    click uiComponents "https://github.com/nickscamara/open-deep-research/tree/main/components/"
    click authAPI "https://github.com/nickscamara/open-deep-research/tree/main/app/(auth)/api"
    click chatAPI "https://github.com/nickscamara/open-deep-research/tree/main/app/(chat)/api"
    click aiIntegration "https://github.com/nickscamara/open-deep-research/tree/main/lib/ai"
    click database "https://github.com/nickscamara/open-deep-research/tree/main/lib/db"
    click editor "https://github.com/nickscamara/open-deep-research/tree/main/lib/editor"

    %% Styles
    classDef clientStyle fill:#f9e79f,stroke:#333,stroke-width:2px
    classDef frontendStyle fill:#aed6f1,stroke:#333,stroke-width:2px
    classDef apiStyle fill:#a9dfbf,stroke:#333,stroke-width:2px
    classDef businessStyle fill:#f5cba7,stroke:#333,stroke-width:2px
    classDef dataStyle fill:#f1948a,stroke:#333,stroke-width:2px
    classDef externalStyle fill:#82e0aa,stroke:#333,stroke-width:2px

    class client clientStyle
    class frontend,uiComponents frontendStyle
    class authAPI,chatAPI apiStyle
    class aiIntegration,editor businessStyle
    class database,storage dataStyle
    class external externalStyle
```
