# ashgen12/deep-research-ai-agent architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack AI research agent for the Indian stock market.
- It combines an interactive web UI (Gradio) with a backend “agent” built on LangChain that orchestrates tools to fetch, scrape, and summarize stock data and news.

##### File structure
- Top-level files:
- `main.py` – entry point: sets up the Gradio interface and the LangChain agent with tools.
- `requirements.txt` – lists dependencies (LangChain, Gradio, Deepseek, NSE API library, BeautifulSoup, requests).
- `README.md` – project overview and setup.
- Directory `Interactions`: contains modules implementing the individual tools:
- `get_52_week_high_stocks`
- `gather_information`
- `summarize_insights`

##### README for architectural insights
- Tech stack: Deepseek API (LLM), LangChain (agent framework), Gradio (UI), NSE API (market data), Beautiful Soup (web scraping).
- Workflow: User → Gradio UI → LangChain agent chooses tools → Tools call external services → Agent composes response → UI displays results

##### Main components
a. Frontend layer
- Gradio interface (hosted by `main.py`)
b. Backend / Orchestration layer
- LangChain Agent (configured in `main.py`)
- Tool modules in `Interactions/` directory
c. External services
- NSE API (stock data)
- Google News (scraped via Beautiful Soup)
- Deepseek API (LLM for summarization and reasoning)
d. Configuration / Environment
- Deepseek API key (environment variable)
- Other API credentials if needed

##### Relationships and data flow
- User inputs query in Gradio UI → HTTP call to main.py
- Gradio passes user prompt to the LangChain agent
- LangChain agent analyzes the prompt and invokes one or more tools:
- get_52_week_high_stocks → requests to NSE API
- gather_information → web scraping logic (Beautiful Soup + requests)
- summarize_insights → HTTP call to Deepseek API
- Each tool returns structured data to the agent
- Agent combines tool outputs into final answer
- Gradio returns response to user in browser

##### Architectural patterns and design principles
- Separation of concerns: UI / Orchestrator / Tools / External services are distinct components
- Plug-in tool architecture via LangChain – easily add, remove, or replace tools in `Interactions/`
- Single entry point (`main.py`) that wires UI and agent together
- Environment-driven configuration for secret management

##### Final advice
- Be exhaustive: capture each distinct component, even if “small.”
- Review the README and code to ensure every piece (e.g., Gradio endpoints, API key management) appears in the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        GradioUI["Gradio UI"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        LangChainAgent["LangChain Agent"]:::application
    end

    %% Tools Layer
    subgraph "Tools"
        direction TB
        Get52["get_52_week_high_stocks"]:::tools
        GatherInfo["gather_information"]:::tools
        Summarize["summarize_insights"]:::tools
    end

    %% External Services
    subgraph "External Services"
        direction TB
        NSEAPI["NSE API"]:::external
        GoogleNews["Google News"]:::external
        DeepseekAPI["Deepseek API"]:::external
    end

    %% Configuration / Documentation
    subgraph "Support Files"
        direction TB
        EnvConfig["Env Variables & Dependencies"]:::config
        Documentation["README.md"]:::documentation
    end

    %% Data Flows
    GradioUI -->|"HTTP/Gradio"| LangChainAgent
    LangChainAgent -->|"requests to fetch stock data"| Get52
    LangChainAgent -->|"requests & BeautifulSoup"| GatherInfo
    LangChainAgent -->|"HTTP call to LLM"| Summarize

    Get52 -->|"REST API"| NSEAPI
    GatherInfo -->|"HTTP/HTML Scraping"| GoogleNews
    Summarize -->|"HTTP/Deepseek API"| DeepseekAPI

    NSEAPI -->|returns data| LangChainAgent
    GoogleNews -->|returns data| LangChainAgent
    DeepseekAPI -->|returns summary| LangChainAgent
    LangChainAgent -->|composed response| GradioUI

    EnvConfig -->|provides keys & libs| LangChainAgent
    EnvConfig -->|provides keys & libs| Get52
    EnvConfig -->|provides keys & libs| GatherInfo
    EnvConfig -->|provides keys & libs| Summarize

    %% Click Events
    click GradioUI "https://github.com/ashgen12/deep-research-ai-agent/blob/main/main.py"
    click LangChainAgent "https://github.com/ashgen12/deep-research-ai-agent/blob/main/main.py"
    click Get52 "https://github.com/ashgen12/deep-research-ai-agent/blob/main/Interactions/get_52_week_high_stocks.py"
    click GatherInfo "https://github.com/ashgen12/deep-research-ai-agent/blob/main/Interactions/gather_information.py"
    click Summarize "https://github.com/ashgen12/deep-research-ai-agent/blob/main/Interactions/summarize_insights.py"
    click Documentation "https://github.com/ashgen12/deep-research-ai-agent/blob/main/README.md"
    click EnvConfig "https://github.com/ashgen12/deep-research-ai-agent/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef application fill:#A9DFBF,stroke:#196F3D,color:#145A32;
    classDef tools fill:#F9E79F,stroke:#B9770E,color:#7E5109;
    classDef external fill:#D5D8DC,stroke:#566573,color:#1B2631;
    classDef config fill:#EBDEF0,stroke:#7D3C98,color:#4A235A;
    classDef documentation fill:#FADBD8,stroke:#922B21,color:#641E16;
```
