# wolfsbane9513/100x_buildathon architecture

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

- Interactive diagram: https://gitdiagram.com/wolfsbane9513/100x_buildathon
- Repository: https://github.com/wolfsbane9513/100x_buildathon

## Overview

##### Project type and purpose
- From the README and file tree, this is a full‐stack Python “Intelligent Report Generator” that:
- Provides an interactive Gradio UI (“interface/app.py”)
- Orchestrates data ingestion (files, MongoDB, SQL)
- Invokes various LLM providers (Ollama local models, OpenAI, Anthropic) via a core Agent
- Post‐processes text, templates, and visualizations
- Renders reports (PDF/DOCX/HTML)

##### File structure
- Top level:
- report_generator/app – application entrypoint, config, start‐up
- report_generator/interface – Gradio UI definitions
- report_generator/core – business logic: agent, models, data, processors, tools
- report_generator/utils – shared helpers and logging
- root scripts: run.py or test.py, setup.py, requirements.txt
- Patterns:
- Hexagonal/Clean architecture: UI adapters (interface) → application core (core/agent) → domain services (models, processors, data)
- Separation of concerns: data layer vs model abstraction vs processing vs presentation

##### Key insights from README
- Supports multiple LLM backends (Ollama, OpenAI, Anthropic) configured in core/models
- Flexible data sources managed by connection_manager
- Processors for data cleaning, report formatting, visualization
- Gradio front‐end for user input, progress tracking

a. User & UI Layer
- User’s Web Browser ←→ Gradio Server (interface/app.py)
b. Application Layer
- Application Bootstrap (report_generator/app/main.py & config.py)
- Controller / Agent (core/agent.py) – orchestrates the workflow
c. Domain & Services
- Data Layer (core/data/connection_manager.py) – file loaders, MongoDB, MySQL/PostgreSQL adapters
- Model Provider Layer (core/models/) – abstracts calls to OpenAI, Anthropic, Ollama
- Processing Layer (core/processors/)
– DataPreprocessor
– ReportPreprocessor
– VizProcessor
- Tools (core/tools/tools.py) – utility functions, template rendering
d. Persistence & External Services
- File System (CSV/Excel/JSON upload)
- Databases (MongoDB, MySQL, PostgreSQL)
- External LLM APIs / Local runtime (Ollama daemon)
e. Output Layer
- Report Renderers → PDF, DOCX, HTML

##### Relationships and Data Flow
1. User interacts with Gradio UI → submits data/config/query
2. UI forwards request to Application Bootstrap → invokes Agent
3. Agent:
a. Calls Data Layer to load/validate data
b. Passes data + query to Model Provider for LLM completion
c. Receives raw LLM response
d. Runs processors: text‐templating, visualization generation
e. Sends processed output to Renderer for final format
4. Renderer writes report to disk or returns file buffer
5. UI streams progress updates and serves final report for download

##### Architectural patterns and design principles
- Hexagonal / Ports & Adapters:
Core logic (Agent/Processors) depends on abstractions (models, data) via interfaces
- Single Responsibility & Separation of Concerns:
Each folder/module has a distinct role (data access vs LLM clients vs visualization)
- Plugin‐style extensibility:
New data sources or LLM backends can be added under core/data or core/models

##### Relevant technologies & frameworks
- Python 3.8+
- Gradio (interface)
- Pydantic / dataclasses for schemas (core/models/schemas.py)
- MongoDB / MySQL / PostgreSQL drivers
- Requests / HTTP clients for external APIs
- Ollama CLI for local-model inference

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        GradioUI["Gradio UI"]:::internal
        GradioComponents["UI Components"]:::internal
    end

    %% Application Layer
    subgraph "Application Layer"
        Bootstrap["App Bootstrap"]:::internal
        Agent["Agent"]:::internal
    end

    %% Domain Services
    subgraph "Domain Services"
        subgraph "Data Layer"
            DataLayer["Connection Manager"]:::data
        end
        subgraph "Model Providers"
            BaseModel["Base Provider"]:::internal
            Manager["Provider Manager"]:::internal
            OpenAI["OpenAI Client"]:::external
            Anthropic["Anthropic Client"]:::external
            Ollama["Ollama Client"]:::external
            Schemas["Data Schemas"]:::internal
        end
        subgraph "Processors"
            DataProc["DataPreprocessor"]:::internal
            ReportProc["ReportPreprocessor"]:::internal
            VizProc["Visualization Processor"]:::internal
        end
        Tools["Tools & Helpers"]:::internal
    end

    %% External Services
    subgraph "External Services"
        FS["File System"]:::data
        Mongo["MongoDB"]:::data
        SQL["MySQL/PostgreSQL"]:::data
        OpenAIAPI["OpenAI API"]:::external
        AnthropicAPI["Anthropic API"]:::external
        OllamaDaemon["Ollama Runtime"]:::external
    end

    %% Output Layer
    subgraph "Output"
        Renderer["Report Renderer"]:::output
    end

    %% Shared Utilities
    subgraph "Shared Utilities"
        Constants["Constants"]:::internal
        Helpers["Helpers"]:::internal
        Logger["Logging"]:::internal
    end

    %% Root Scripts & Setup
    subgraph "Root Scripts & Setup"
        Test["Test Runner"]:::internal
        Setup["Package Setup"]:::internal
        Req["Requirements"]:::internal
    end

    %% Connections
    GradioUI -->|"user request"| Bootstrap
    GradioComponents --> Bootstrap
    Bootstrap --> Agent
    Agent -->|"load data"| DataLayer
    DataLayer --> FS
    DataLayer --> Mongo
    DataLayer --> SQL
    Agent --> Manager
    Manager --> BaseModel
    Manager --> OpenAI
    Manager --> Anthropic
    Manager --> Ollama
    OpenAI --> OpenAIAPI
    Anthropic --> AnthropicAPI
    Ollama --> OllamaDaemon
    Agent --> DataProc
    DataProc --> ReportProc
    ReportProc --> VizProc
    VizProc --> Renderer
    Renderer --> FS
    Renderer --> GradioUI
    Agent --> Tools
    DataProc --> Tools
    ReportProc --> Tools
    Tools --> Constants
    Tools --> Helpers
    Tools --> Logger
    Test --> Bootstrap

    %% Click Events
    click GradioUI "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/interface/app.py"
    click GradioComponents "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/interface/components.py"
    click Bootstrap "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/app/main.py"
    click Bootstrap "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/app/config.py"
    click Agent "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/core/agent.py"
    click DataLayer "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/core/data/connection_manager.py"
    click BaseModel "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/core/models/base.py"
    click Manager "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/core/models/manager.py"
    click OpenAI "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/core/models/openai_models.py"
    click Anthropic "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/core/models/anthropic_models.py"
    click Ollama "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/core/models/ollama_models.py"
    click Schemas "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/core/models/schemas.py"
    click DataProc "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/core/processors/data_preprocessor.py"
    click ReportProc "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/core/processors/report_preprocessor.py"
    click VizProc "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/core/processors/viz_processor.py"
    click Tools "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/core/tools/tools.py"
    click Constants "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/utils/constants.py"
    click Helpers "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/utils/helpers.py"
    click Logger "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/utils/logger.py"
    click Test "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/test.py"
    click Setup "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/setup.py"
    click Req "https://github.com/wolfsbane9513/100x_buildathon/blob/main/report_generator/requirements.txt"

    %% Styles
    classDef internal fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef data fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef output fill:#e1bee7,stroke:#333,stroke-width:1px
```
