# pro402/ai-report-generator architecture

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

- Interactive diagram: https://gitdiagram.com/pro402/ai-report-generator
- Repository: https://github.com/pro402/ai-report-generator

## Overview

##### Main Components
- User Interface: Represented by streamlit_app.py, which is the entry point for the interactive web interface where users input parameters and trigger the report generation workflow.
- Report Generation Engine: Represented by report_generator.py; this component handles the creation of outlines and compiling the final report content using AI models.
- Workflow Orchestrator: Represented by workflow.py; it implements the state graph workflow (powered by LangGraph) to manage multi-stage transitions from research to report compilation.
- Tools Module: Represented by tools.py; contains functions to perform deep research and specialized searches (e.g., general, finance, and news) by interfacing with the Tavily API.
- Data Models: Represented by models.py; it defines TypedDict-based data models for tracking Report and Research state throughout the generation process.
- External Services: Indicate integration with multiple external services such as:
- Tavily API for search functionality.
- ChatNVIDIA and LangChain for AI-powered content generation.
- Pandoc for markdown to PDF conversion (as mentioned in the README).
- Supporting Files: Configuration files (.env_example, .gitignore) and demo assets found in the demos directory that help illustrate workflow and functionality.

##### Relationships and Interactions
- User Interaction: The user engages with the system via the Streamlit UI, which collects parameters and initiates the workflow.
- Workflow Process: The input from the UI is passed on to the workflow module. The state graph in workflow.py defines various states (research, outline generation, content creation, and final assembly) and transitions for handling the report creation lifecycle.
- Handling Research: Within the workflow, the tools module (tools.py) is invoked to perform deep research by calling the Tavily API and possibly other specialized search endpoints.
- Report Composition: Once research data is fetched, report_generator.py processes and converts the data, leveraging AI models, to generate structured markdown reports.
- Data Flow: Models defined in models.py help maintain and pass structured data between these components thus enabling consistency.

##### Architectural Patterns and Design Principles
- Modular Separation: Emphasize a clear separation of concerns with dedicated modules for UI (streamlit_app.py), workflow coordination (workflow.py), business logic (report_generator.py), and external API integration (tools.py).
- State Graph Workflow: Illustrate the state transition mechanism managed by LangGraph—for instance, how states move from research initiation to content generation and final report output.
- Extensibility: Note that the system is designed for customization. The modular design makes it easier to extend or refine the workflow (e.g., adding new research steps or more data sources).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Streamlit UI (streamlit_app.py)"]:::frontend
    end

    %% Business Logic
    subgraph "Business Logic"
        WF["Workflow Orchestrator (workflow.py)"]:::backend
        RG["Report Generation Engine (report_generator.py)"]:::backend
        TL["Tools Module (tools.py)"]:::backend
        DM["Data Models (models.py)"]:::backend
    end

    %% External Services
    subgraph "External Services"
        TAP["Tavily API"]:::external
        CN["ChatNVIDIA"]:::external
        LC["LangChain"]:::external
        LG["LangGraph"]:::external
        PD["Pandoc Converter"]:::external
    end

    %% Supporting Configurations
    subgraph "Supporting Configurations"
        ENV[".env_example"]:::support
        GI[".gitignore"]:::support
        DEM["demos"]:::support
    end

    %% Connections between components
    UI -->|"triggers"| WF
    WF -->|"orchestrates"| RG
    WF -->|"manages-state"| TL
    TL -->|"calls"| TAP
    WF -->|"stateGraph"| LG
    RG -->|"integrates"| CN
    RG -->|"leverages"| LC
    RG -->|"converts"| PD
    RG -->|"returns"| UI

    %% Data Models shared across modules
    WF ---|"usesData"| DM
    TL ---|"usesData"| DM
    RG ---|"usesData"| DM

    %% Supporting Configuration integration
    WF -.->|"config"| ENV
    WF -.->|"config"| GI
    WF -.->|"config"| DEM

    %% Styles
    classDef frontend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef backend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef external fill:#A9DFBF,stroke:#117A65,stroke-width:2px;
    classDef support fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/pro402/ai-report-generator/blob/main/streamlit_app.py"
    click WF "https://github.com/pro402/ai-report-generator/blob/main/workflow.py"
    click RG "https://github.com/pro402/ai-report-generator/blob/main/report_generator.py"
    click TL "https://github.com/pro402/ai-report-generator/blob/main/tools.py"
    click DM "https://github.com/pro402/ai-report-generator/blob/main/models.py"
    click ENV "https://github.com/pro402/ai-report-generator/blob/main/.env_example"
    click GI "https://github.com/pro402/ai-report-generator/blob/main/.gitignore"
    click DEM "https://github.com/pro402/ai-report-generator/tree/main/demos"
```
