# adirthaborgohain/reportai architecture

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

- Interactive diagram: https://gitdiagram.com/adirthaborgohain/reportai
- Repository: https://github.com/adirthaborgohain/reportai

## Overview

##### Project type and purpose
- This is a Python-based CLI/open-source tool (not a web or full-stack app).
- Purpose: ingest structured AI chat messages → generate a formatted PDF research report (9–15 pages) using OpenAI/Anthropic LLMs.

##### File structure
- Top-level:
- report_ai/ (main package)
- requirements.txt, README.md, LICENSE
- report_ai/ subdirectories & files:
- assets/ – HTML templates, logos, screenshots (static resources for report cover, sections, disclaimers)
- common/utils/ – configuration loader (configs.yaml), environment variables (.env), logger, helper functions
- components/ – core “pipeline” steps: llms.py (API wrappers), deduplicate.py, convert.py (HTML→PDF), functions.py (report-building helpers)
- skeleton.py, section.py, summary.py, report.py – modules that assemble the high-level report structure, section content, executive summary, and orchestrate PDF rendering
- main.py – CLI entry point demonstrating usage
- reports/ – output directory containing sample.pdf

##### Key insights from the README
- Uses LLMs via OpenAI/Anthropic; configurable via environment variables/.env
- Pipeline: parse conversation → dedupe → format sections/tables/figures → produce PDF
- Depends on LangChain and other Python libraries

##### Main components and their relationships
a. CLI Entry Point (main.py)
- Reads user’s structured conversation input
- Loads config & API keys via common/utils
- Kicks off the ReportBuilder (report.py)
b. Report Pipeline
- skeleton.py: defines overall report structure (title page, table of contents, sections)
- section.py: generates each section by invoking llms.py (API calls) and functions.py (text/table formatting)
- summary.py: creates executive summary via a separate LLM call
- deduplicate.py: removes repeated sentences/phrases across sections
- convert.py: merges filled‐in HTML templates (assets/) into final PDF
c. Static Assets
- HTML templates, logos, disclaimers (report_ai/assets) used by convert.py to render pages
d. Utilities
- config loader reads .env & configs.yaml
- logger for structured logging
e. External Dependencies
- OpenAI/Anthropic LLM APIs
- PDF rendering library (e.g., WeasyPrint, PyPDF2—check requirements.txt)
- LangChain for prompt management

##### Architectural patterns & design principles
- Modular pipeline: each stage in its own component/module
- Single-responsibility: separation of concerns (LLM API calls vs. formatting vs. dedupe vs. conversion)
- Pluggable: LLM choice abstracted in llms.py, environment-driven config
- Template-driven output: HTML assets + conversion → PDF

##### Detailed but uncluttered
- If space allows, annotate each module with its primary responsibility (e.g., “deduplicate.py: remove repeated content”)
- Related modules (e.g., section.py and summary.py) under a “Content Generation” container

##### Essential elements
- The separation of stages (generation, dedupe, conversion)
- The abstraction of LLM providers behind llms.py
- The use of static HTML assets to drive PDF layout

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Utilities
    A["CLI / User Input"]:::util
    click A "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/main.py"
    B["Config Loader"]:::util
    click B "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/common/utils/configs.yaml"
    Env["Environment Variables"]:::util
    click Env "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/.env"
    C["Logger Utility"]:::util
    click C "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/common/utils/logger.py"
    Helpers["Helper Functions"]:::util
    click Helpers "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/common/utils/helpers.py"

    %% Orchestrator
    RB["Report Orchestrator"]:::pipeline
    click RB "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/report.py"

    %% Pipeline Modules
    subgraph "Report Pipeline"
        direction TB
        Skl["Report Skeleton"]:::pipeline
        click Skl "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/skeleton.py"
        subgraph "Content Generation"
            direction TB
            Sec["Section Generation"]:::pipeline
            click Sec "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/section.py"
            Sum["Executive Summary"]:::pipeline
            click Sum "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/summary.py"
        end
        Dedupe["Deduplication Module"]:::pipeline
        click Dedupe "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/components/deduplicate.py"
        Conv["HTML→PDF Converter"]:::pipeline
        click Conv "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/components/convert.py"
    end

    %% Helpers and LLM
    Funcs["Report-Building Helpers"]:::pipeline
    click Funcs "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/components/functions.py"
    LLM["LLM API Wrappers"]:::external
    click LLM "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/components/llms.py"

    %% Static Assets and Output
    Assets[(Static Assets)]:::assets
    click Assets "https://github.com/adirthaborgohain/reportai/tree/main/report_ai/assets/"
    Title["title.html"]:::assets
    click Title "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/assets/title.html"
    Disc["disclaimer.html"]:::assets
    click Disc "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/assets/disclaimer.html"
    EndT["end.html"]:::assets
    click EndT "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/assets/end.html"
    Logos[(Logo Assets)]:::assets
    click Logos "https://github.com/adirthaborgohain/reportai/tree/main/report_ai/assets/logos/"
    Screens[(Screenshot Assets)]:::assets
    click Screens "https://github.com/adirthaborgohain/reportai/tree/main/report_ai/assets/screenshots/"
    Reports[(Sample PDF Output)]:::assets
    click Reports "https://github.com/adirthaborgohain/reportai/blob/main/report_ai/reports/sample.pdf"

    %% External Services
    OpenAI[(OpenAI API)]:::external
    Anthro[(Anthropic API)]:::external

    %% Connections
    A --> B --> Env --> C --> RB
    RB --> Skl
    Skl --> Sec
    Skl --> Sum
    Sec --> Funcs
    Sum --> Funcs
    Sec --> Dedupe
    Sum --> Dedupe
    Dedupe --> Conv
    Conv --> Reports
    Conv --> Assets
    Assets --> Title
    Assets --> Disc
    Assets --> EndT
    Assets --> Logos
    Assets --> Screens
    Sec -->|requests| LLM
    Sum -->|requests| LLM
    LLM --> OpenAI
    LLM --> Anthro

    %% Styles
    classDef pipeline fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef util fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef external fill:#fff3e0,stroke:#ef6c00,stroke-width:2px,stroke-dasharray: 5 5;
    classDef assets fill:#eceff1,stroke:#546e7a,stroke-width:2px,stroke-dasharray: 2 2;
```
