# pablocfonseca/streamlit-aggrid architecture

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

- Interactive diagram: https://gitdiagram.com/pablocfonseca/streamlit-aggrid
- Repository: https://github.com/pablocfonseca/streamlit-aggrid

## Overview

##### Project Type and Purpose
- This is an open-source Python package that integrates the AgGrid “awesome grid”—a feature-rich JavaScript-based grid library—with Streamlit applications. In essence, it acts as a wrapper around AgGrid, providing an interactive grid component for Streamlit apps.
- The project includes both a Python backend (for handling Streamlit integration, data management, configuration, and grid response processing) and a JavaScript/React based frontend (to render the grid using AgGrid). There are also examples, tests, and configuration files to support development and usage.

##### File Structure
- The top-level files (e.g., README.md, setup.py, package.json, pyproject.toml) indicate that the project is packaged for distribution as a Python package and also includes frontend build tooling.
- The st_aggrid directory is the heart of the project and is separated into:
- Core Python modules (AgGrid.py, AgGridReturn.py, grid_options_builder.py, shared.py) which encapsulate the grid’s server-side logic and communication.
- A dedicated frontend directory (st_aggrid/frontend) that contains React/TypeScript code, Webpack configuration, build scripts, and public assets. This part handles the rendering of the grid in the browser.
- Additional directories such as examples, tests, and .github indicate that the project is well-supported with demos, testing, and GitHub issue templates.

##### Using Details from the README
- The README further clarifies that once the package is installed, a developer creates a simple Streamlit script (e.g., example.py) that instantiates the AgGrid component, passes a pandas DataFrame, and receives editable grid data back.
- It emphasizes integration between the Python backend and the React frontend, with details on grid state handling, events, and theming (including references to AgGrid’s official documentation).

##### Main Components and Their Interactions
- Python Backend:
- Streamlit AgGrid API: A Python module that provides the AgGrid component for use in Streamlit applications.
- Grid Options Builder and Shared Modules: Handle request/response processing, configuration of grid options, and possibly manage state or callback functions.
- Data Handling: Reads and processes grid data (e.g., dataframes) from the user’s input or external sources.
- Frontend:
- React Components (e.g., AgGrid.tsx, ThemeParser.tsx): Render the grid using AgGrid’s JS library and manage dynamic grid events.
- Frontend Configuration & Build Tools: Webpack, package.json, and TS config files indicate the usage of modern frontend build tooling to bundle the React components.
- Communication Layer: Likely uses Streamlit’s components API to exchange data (via JSON) between the backend and the frontend.
- External Dependencies:
- AgGrid Library: An external feature-rich grid library (with both free and enterprise features) that provides the core grid functionalities.
- Streamlit: Acts as the application framework, hosting the Python backend and serving the rendered frontend components.
- Other potential libraries include pandas for DataFrame management and possibly other third-party JS/TS libraries integrated via npm.

##### Final Recommendations
- Clear labels for each module and component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level User
    U["User (Streamlit App)"]:::external

    %% External Dependencies
    subgraph "External Services"
        AGLib["AgGrid Library"]:::external
        StreamlitExt["Streamlit"]:::external
    end

    %% Python Backend
    subgraph "Python Backend"
        init["Package Init (st_aggrid/__init__.py)"]:::python
        AGB["AgGrid (st_aggrid/AgGrid.py)"]:::python
        AGRet["AgGridReturn (st_aggrid/AgGridReturn.py)"]:::python
        GOB["GridOptionsBuilder (st_aggrid/grid_options_builder.py)"]:::python
        Shared["Shared (st_aggrid/shared.py)"]:::python
    end

    %% React Frontend
    subgraph "React Frontend"
        AgGridTSX["AgGrid.tsx (st_aggrid/frontend/src/AgGrid.tsx)"]:::react
        ThemeParser["ThemeParser.tsx (st_aggrid/frontend/src/ThemeParser.tsx)"]:::react
        IndexTSX["Index.tsx (st_aggrid/frontend/src/index.tsx)"]:::react
    end

    %% Frontend Build & Configuration
    subgraph "Frontend Build & Config"
        Webpack["webpack.config.js (st_aggrid/frontend/config/webpack.config.js)"]:::config
        PkgFront["package.json (st_aggrid/frontend/package.json)"]:::config
        TSConfig["tsconfig.json (st_aggrid/frontend/tsconfig.json)"]:::config
        BuildJS["build.js (st_aggrid/frontend/scripts/build.js)"]:::config
    end

    %% Project Distribution & Dependency Files
    subgraph "Project Distribution"
        PkgDist["package.json (Project Root)"]:::distribution
        SetupPy["setup.py"]:::distribution
        PyprojectTOML["pyproject.toml"]:::distribution
    end

    %% Examples / Demos
    subgraph "Examples / Demos"
        ExamplePy["example.py (examples/example.py)"]:::demo
        LocalisationPy["Localisation.py (examples/Localisation.py)"]:::demo
        QuickExample["quick_example.py (examples/quick_example.py)"]:::demo
    end

    %% Relationships
    U -- "initiates" --> init
    U -- "triggers demos" --> ExamplePy

    %% Python Backend interactions
    init --- AGB
    AGB --- AGRet
    AGRet --- GOB
    GOB --- Shared

    %% Data flow between Backend and Frontend
    init -- "renders grid" --> AgGridTSX
    AgGridTSX -- "returns grid data" --> AGB

    %% External dependencies
    StreamlitExt -- "hosts" --> init
    AGLib -- "integrates with" --> AgGridTSX

    %% Frontend Build connections
    Webpack -- "bundles" --> AgGridTSX
    PkgFront -- "manages dependencies" --> AgGridTSX
    TSConfig -- "configures TS" --> AgGridTSX
    BuildJS -- "builds assets" --> AgGridTSX

    %% Project Distribution linkage
    PkgDist -- "packages" --> init
    SetupPy -- "packages" --> init
    PyprojectTOML -- "packages" --> init

    %% Styling Classes
    classDef python fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef react fill:#ffcdd2,stroke:#b71c1c,stroke-width:2px;
    classDef config fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef external fill:#f8bbd0,stroke:#880e4f,stroke-width:2px;
    classDef distribution fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
    classDef demo fill:#ffe0b2,stroke:#e65100,stroke-width:2px;

    %% Click Events for Python Backend
    click init "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/st_aggrid/__init__.py"
    click AGB "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/st_aggrid/AgGrid.py"
    click AGRet "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/st_aggrid/AgGridReturn.py"
    click GOB "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/st_aggrid/grid_options_builder.py"
    click Shared "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/st_aggrid/shared.py"

    %% Click Events for React Frontend
    click AgGridTSX "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/st_aggrid/frontend/src/AgGrid.tsx"
    click ThemeParser "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/st_aggrid/frontend/src/ThemeParser.tsx"
    click IndexTSX "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/st_aggrid/frontend/src/index.tsx"

    %% Click Events for Frontend Build & Configuration
    click Webpack "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/st_aggrid/frontend/config/webpack.config.js"
    click PkgFront "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/st_aggrid/frontend/package.json"
    click TSConfig "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/st_aggrid/frontend/tsconfig.json"
    click BuildJS "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/st_aggrid/frontend/scripts/build.js"

    %% Click Events for Project Distribution
    click PkgDist "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/package.json"
    click SetupPy "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/setup.py"
    click PyprojectTOML "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/pyproject.toml"

    %% Click Events for Examples / Demos
    click ExamplePy "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/examples/example.py"
    click LocalisationPy "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/examples/Localisation.py"
    click QuickExample "https://github.com/pablocfonseca/streamlit-aggrid/blob/main/examples/quick_example.py"
```
