# salesforceairesearch/enterprise-deep-research architecture

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

- Interactive diagram: https://gitdiagram.com/salesforceairesearch/enterprise-deep-research
- Repository: https://github.com/salesforceairesearch/enterprise-deep-research

## Overview

##### Project Type and Purpose
- Full-stack, multi-agent research system for automated enterprise analytics.
- Frontend: React/Tailwind web app (“ai-research-assistant”).
- Backend: FastAPI/Uvicorn Python service exposing REST/OpenAPI endpoints.
- Core research engine: orchestrates Master Planning Agent, specialized search agents, visualization, reflection loops, and tool invocations.
- Extensible tool ecosystem (NL2SQL, file analysis, enterprise workflows) via MCP (multi-chain planning) integration.
- Benchmarking and CLI utilities for offline evaluation.

##### File Structure
Top-level:
- ai-research-assistant/ – React frontend
- app.py – FastAPI entry point
- routers/ – HTTP endpoints mapping to services
- services/ – business-logic modules (research, parsing, storage, analysis)
- models/ – Pydantic schemas and data classes
- src/ – core multi-agent engine (agent_architecture, graph, state, steering, prompts, visualization, tools)
- llm_clients.py – wrapping OpenAI/Anthropic/Groq/SambaNova clients
- session_store.py & services/file_storage.py – persistence layers
- benchmarks/ – scripts for DeepResearchBench, ResearchQA, DeepConsult
- Docker/E2B deploy files: e2b.Dockerfile, e2b.toml
- config: .env.sample, pyproject.toml, requirements.txt
- tests/ & various test_*.py – unit/integration tests

##### README Insights
- Tech stack: Python 3.11+, Node.js 20.9.0+, FastAPI, React, Tailwind CSS, LangGraph.
- External dependencies: Tavily search API, multiple LLM providers.
- Key components: Master Planning Agent, four specialized search agents, Visualization Agent, reflection mechanism, real-time steering.

##### Main Components & Interactions
a. Frontend (React / Tailwind)
– Static build served by FastAPI (public/index.html & assets).
– UI components (Navbar, ResearchPanel, CodeSnippetViewer, FinalReport, LoadingIndicator, etc.)
– Makes HTTP/WebSocket calls to backend for queries, streaming updates, file uploads.
b. API Layer (FastAPI routers)
– routers/*.py define endpoints: /research, /file_analysis, /database upload, /steering, etc.
– Delegates to service layer modules.
c. Service Layer (services/*.py)
– research.py: entry to core engine
– content_analysis, activity_generator, file_parsers, file_storage: specialized processing
– session_store manages stateful sessions across requests.
d. Core Research Engine (src/)
– agent_architecture: orchestrates agents via LangGraph workflows.
– graph.py/state.py: define research DAG and state transitions.
– steering_integration/simple_steering.py: real-time human-in-the-loop guidance.
– prompts/*.py: templates for LLM calls.
– visualization_agent: produces charts or HTML (IframeView).
– tools: MCP-based tool registry & executor (text2sql, math_server, puppeteer, GitHub search, LinkedIn search).
e. Infrastructure & Integrations
– llm_clients.py: abstraction over OpenAI, Anthropic, Google, Groq, SambaNova.
– External Search API (Tavily) via researchService.js in frontend and via Python clients.
– File storage: local FS or S3 (pluggable) in services/file_storage.
– Session store: in-memory or Redis (configurable).
f. Benchmarking & CLI
– benchmarks/ scripts invoke core engine directly for automated evaluation.
– coding-agent.py, graph_test.py, model_test.py exercises workflows.
g. Deployment & DevOps
– Dockerfile (e2b.Dockerfile) for containerized deployment.
– E2B.toml for edge-to-edge builds.
– CI/CD hints in .github/ (not shown) & code quality commands.

##### Architectural Patterns & Design Principles
- Layered architecture: Presentation (frontend), API, Application (services), Domain (models, core engine), Infrastructure (LLM clients, storage).
- Plugin-based tool framework: add new MCP tools without touching core orchestrator.
- Workflow engine (LangGraph) for agent orchestration—resembles pipeline/graph execution.
- Reflection loop pattern: detect gaps, replan, iterate.
- Real-time streaming & steering: evented data flows (WebSockets or server-sent events) from engine → frontend.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        FE["React/Tailwind UI"]:::frontend
    end

    subgraph "API Layer"
        APIEntry["app.py"]:::api
        Routers["HTTP Routers"]:::api
    end

    subgraph "Core Engine & Services"
        subgraph "Service Layer"
            Services["services/*"]:::service
            SessionStore["session_store.py"]:::service
            FileStorage["file_storage.py"]:::service
        end
        subgraph "Core Research Engine"
            AgentArch["agent_architecture.py"]:::core
            AgentModule["agent.py"]:::core
            Graph["graph.py"]:::core
            State["state.py"]:::core
            Steering1["simple_steering.py"]:::core
            Steering2["steering_integration.py"]:::core
            Prompts["prompts.py / prompts_benchmark.py / prompts_qa.py"]:::core
            Viz["visualization_agent.py"]:::core
            Tools["tools/*"]:::core
        end
    end

    subgraph "Infrastructure & External"
        LLM["llm_clients.py"]:::infra
        ExtSearch["Tavily & External APIs"]:::infra
        StorageInfra["S3/FS"]:::infra
        SessionInfra["Redis/in-memory"]:::infra
    end

    subgraph "Benchmarks & CLI"
        Bench["benchmarks/*"]:::benchmark
        Coding["coding-agent.py"]:::benchmark
        GraphTest["graph_test.py"]:::benchmark
        ModelTest["model_test.py"]:::benchmark
    end

    FE -->|HTTP/WS| APIEntry
    FE -->|HTTP/WS| Routers
    APIEntry --> Routers
    Routers -->|calls| Services
    Services -->|invokes| AgentArch
    Services --> SessionStore
    Services --> FileStorage
    AgentArch --> AgentModule
    AgentArch --> Graph
    AgentArch --> State
    AgentArch --> Steering1
    AgentArch --> Steering2
    AgentArch --> Prompts
    AgentArch --> Viz
    AgentArch --> Tools
    AgentArch -->|LLM API call| LLM
    Tools -->|external tool exec| ExtSearch
    FileStorage --> StorageInfra
    SessionStore --> SessionInfra
    Bench --> AgentArch
    Coding --> AgentArch
    GraphTest --> AgentArch
    ModelTest --> AgentArch

    click FE "https://github.com/salesforceairesearch/enterprise-deep-research/tree/main/ai-research-assistant/"
    click APIEntry "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/app.py"
    click Routers "https://github.com/salesforceairesearch/enterprise-deep-research/tree/main/routers/"
    click Services "https://github.com/salesforceairesearch/enterprise-deep-research/tree/main/services/"
    click SessionStore "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/session_store.py"
    click FileStorage "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/services/file_storage.py"
    click AgentArch "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/src/agent_architecture.py"
    click AgentModule "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/src/agent.py"
    click Graph "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/src/graph.py"
    click State "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/src/state.py"
    click Steering1 "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/src/simple_steering.py"
    click Steering2 "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/src/steering_integration.py"
    click Prompts "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/src/prompts.py"
    click Viz "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/src/visualization_agent.py"
    click Tools "https://github.com/salesforceairesearch/enterprise-deep-research/tree/main/src/tools/"
    click LLM "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/llm_clients.py"
    click Bench "https://github.com/salesforceairesearch/enterprise-deep-research/tree/main/benchmarks/"
    click Coding "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/coding-agent.py"
    click GraphTest "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/graph_test.py"
    click ModelTest "https://github.com/salesforceairesearch/enterprise-deep-research/blob/main/model_test.py"

    classDef frontend fill:#D0EFFF,stroke:#009AD6
    classDef api fill:#E0F8E0,stroke:#2E8B57
    classDef service fill:#E6FFE6,stroke:#2E8B57
    classDef core fill:#FFF4C2,stroke:#E1C700
    classDef infra fill:#F0F0F0,stroke:#AAAAAA
    classDef benchmark fill:#F5E1FF,stroke:#9B59B6
```
