# paradiddle131/dynamic-research-agent architecture

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

- Interactive diagram: https://gitdiagram.com/paradiddle131/dynamic-research-agent
- Repository: https://github.com/paradiddle131/dynamic-research-agent

## Overview

##### Project type and purpose
- This is a backend-only Python microservice exposing a versioned REST API (likely FastAPI, given the “app/main.py”, “uv.lock” and typical structure).
- Its purpose appears to be to scrape data, process it with Large Language Models (LLM), dynamically build schemas/models, and serve results via an HTTP endpoint (e.g., “research” endpoint).

##### File structure
- Top-level: configuration files (.env, pyproject.toml, requirements.txt), main entrypoint (app/main.py), environment lock (uv.lock).
- app/api/v1/endpoints: defines HTTP routes (research.py).
- app/api/v1/schemas: defines request payload schemas.
- app/core: houses the business logic layers:
- config.py – loads environment/configuration values
- scraper.py – fetches or scrapes external data
- llm.py – wraps calls to external LLM services
- dynamic_models.py – builds or modifies data models at runtime
- app/utils: cross-cutting concerns (logging_config.py).

##### Clues for architectural insights
- Versioned API (v1) suggests future extensibility.
- Separation into API, Core, and Utils layers shows clear layering.
- No database folder/file – likely stateless or uses external services (LLM API, web scraping).

##### Elements
- HTTP request/response
- Data flow between core services
- Outgoing calls to external systems
- Core services in another
- External services in a third
- Utilities (logging) as a sidebar or overlay

Guidelines summary:
- A “Logging” overlay or sidebar capturing cross-layer events.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["Client"]:::external

    %% API Layer
    subgraph "API Layer"
        APIMain["FastAPI"]:::api
        Endpoints["Research Endpoint"]:::api
        Schemas["Schemas"]:::api
    end

    %% Core Layer
    subgraph "Core Layer"
        Config["Config Service"]:::core
        Scraper["Scraper Service"]:::core
        LLM["LLM Service"]:::core
        DynModels["Dynamic Models Service"]:::core
    end

    %% Utility Layer
    subgraph "Utility Layer"
        Logging["Logging"]:::util
    end

    %% External Services
    TargetWeb["Target Websites"]:::external
    LLMProvider["LLM Provider API"]:::external

    %% Connections
    Client -->|"HTTP Request"| APIMain
    APIMain -->|"Route to v1/research"| Endpoints
    Endpoints -->|"Payload Validation"| Schemas
    Schemas -->|"Validated Payload"| Endpoints

    Endpoints -->|"Uses Config"| Config
    Config --> Scraper
    Config --> LLM
    Config --> DynModels

    Endpoints -->|"Calls Scraper"| Scraper
    Scraper -->|"Scrapes"| TargetWeb
    Scraper -->|"Raw Data"| LLM

    Endpoints -->|"Calls LLM"| LLM
    LLM -->|"LLM Request/Response"| LLMProvider
    LLMProvider --> LLM
    LLM -->|"LLM Response"| DynModels

    Endpoints -->|"Calls Model Builder"| DynModels
    DynModels -->|"Built Model Object"| Endpoints

    Endpoints -->|"HTTP Response"| Client

    %% Logging overlay
    Logging -.-> APIMain
    Logging -.-> Endpoints
    Logging -.-> Config
    Logging -.-> Scraper
    Logging -.-> LLM
    Logging -.-> DynModels

    %% Click Events
    click APIMain "https://github.com/paradiddle131/dynamic-research-agent/blob/main/app/main.py"
    click Endpoints "https://github.com/paradiddle131/dynamic-research-agent/blob/main/app/api/v1/endpoints/research.py"
    click Schemas "https://github.com/paradiddle131/dynamic-research-agent/blob/main/app/api/v1/schemas/request.py"
    click Config "https://github.com/paradiddle131/dynamic-research-agent/blob/main/app/core/config.py"
    click Scraper "https://github.com/paradiddle131/dynamic-research-agent/blob/main/app/core/scraper.py"
    click LLM "https://github.com/paradiddle131/dynamic-research-agent/blob/main/app/core/llm.py"
    click DynModels "https://github.com/paradiddle131/dynamic-research-agent/blob/main/app/core/dynamic_models.py"
    click Logging "https://github.com/paradiddle131/dynamic-research-agent/blob/main/app/utils/logging_config.py"

    %% Styles
    classDef api fill:#B3E5FC,stroke:#0277BD,color:#000
    classDef core fill:#C8E6C9,stroke:#2E7D32,color:#000
    classDef external fill:#FFCDD2,stroke:#C62828,color:#000
    classDef util fill:#FFE0B2,stroke:#EF6C00,color:#000
```
