# phuc-nt/deep-research-agent-python architecture

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

- Interactive diagram: https://gitdiagram.com/phuc-nt/deep-research-agent-python
- Repository: https://github.com/phuc-nt/deep-research-agent-python

## Overview

##### Project Type and Purpose
- The project is a full-stack research automation agent that takes research requirements as input and produces detailed research outputs including outlines, analyses, and edited documents.
- Its purpose is to streamline a complete research process by leveraging API endpoints, LLM services (such as OpenAI and Claude), external search services, and storage integrations (both local file system and GitHub).

##### File Structure
- The top-level “app” directory is divided into clear submodules:
- API layer (app/api): Contains the FastAPI application, routes, and entry point.
- Core utilities (app/core): Manages configuration, exceptions, and the service factory pattern.
- Models (app/models): Pydantic models for handling data structures related to research and (originally) cost monitoring.
- Services (app/services): Implements business logic. Under services, you have:
- Core Services: LLM integrations (app/services/core/llm), Search (app/services/core/search), and Storage (app/services/core/storage). (Omit any logging or cost components.)
- Research Services: Implements phases of research such as preparation, detailed processing, and editing.
- Utilities (app/utils): Helpful functions used across the system.
- Additional configuration files, tests, Docker setups, and documentation confirm a robust full-stack architecture built around research processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client["Client/API Consumer"]:::client
    API["API Layer"]:::api

    %% Research Services Subgraph
    subgraph "Research Services"
        Prepare["Prepare Service"]:::research
        Research["Research Service"]:::research
        Edit["Edit Service"]:::research
    end

    %% Core Integrations Subgraph
    subgraph "Core Integrations"
        LLM["LLM Service"]:::core
        Search["Search Service"]:::core
        Storage["Storage Service"]:::core
    end

    %% Connections
    Client -->|"requests"| API
    API -->|"triggers"| Prepare
    API -->|"triggers"| Research
    API -->|"triggers"| Edit

    %% Prepare Service calls
    Prepare -->|"callsLLM"| LLM
    Prepare -->|"callsSearch"| Search
    Prepare -->|"storesOutput"| Storage

    %% Research Service calls
    Research -->|"callsLLM"| LLM
    Research -->|"callsSearch"| Search
    Research -->|"storesOutput"| Storage

    %% Edit Service calls
    Edit -->|"callsLLM"| LLM
    Edit -->|"storesOutput"| Storage

    %% Click Events
    click API "https://github.com/phuc-nt/deep-research-agent-python/blob/main/app/api/main.py"
    click API "https://github.com/phuc-nt/deep-research-agent-python/blob/main/app/api/routes.py"
    click Prepare "https://github.com/phuc-nt/deep-research-agent-python/blob/main/app/services/research/prepare.py"
    click Research "https://github.com/phuc-nt/deep-research-agent-python/blob/main/app/services/research/research.py"
    click Edit "https://github.com/phuc-nt/deep-research-agent-python/blob/main/app/services/research/edit.py"
    click LLM "https://github.com/phuc-nt/deep-research-agent-python/tree/main/app/services/core/llm/"
    click Search "https://github.com/phuc-nt/deep-research-agent-python/tree/main/app/services/core/search/"
    click Storage "https://github.com/phuc-nt/deep-research-agent-python/tree/main/app/services/core/storage/"

    %% Styles
    classDef client fill:#c9f2c9,stroke:#333,stroke-width:2px;
    classDef api fill:#ffebcc,stroke:#333,stroke-width:2px;
    classDef research fill:#ffe6e6,stroke:#333,stroke-width:2px;
    classDef core fill:#e6e6ff,stroke:#333,stroke-width:2px;
```
