# stanmathers/simple-datatable architecture

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

- Interactive diagram: https://gitdiagram.com/stanmathers/simple-datatable
- Repository: https://github.com/stanmathers/simple-datatable

## Overview

##### Project type and purpose
- **Type**: Open-source Python package / library.
- **Purpose**: Provide adapters that convert various data sources (Pandas DataFrame, CSV, Excel, JSON, SQL) into Flet’s DataTable structure (DataTable + DataRows + DataColumns).

##### Main components
a. **Input Adapters**
– DataFrameAdapter (core)
– CSVDataTable
– ExcelDataTable
– JsonDataTable
– SQLDataTable
b. **Core Conversion Engine**
– simpledatatable.py → `DataFrame` class
- Reads/validates source
- Uses pandas (and SQLAlchemy for SQL)
- Produces three attributes:
– datatable (Flet DataTable instance)
– datarows (list of Flet DataRow)
– datacolumns (list of Flet DataColumn)
c. **External Dependencies**
– pandas (data parsing)
– SQLAlchemy (SQL adapter)
– Flet (UI controls: DataTable, DataRow, DataColumn, DataCell)
d. **Client Application**
– Any Flet app that imports and instantiates these adapters, then calls `page.add(...)`.

##### Relationships and data flow
1. Input source (CSV/Excel/JSON file path, SQL connection + table/statement, or existing pandas DataFrame)
→
Shortcut class (e.g., `CSVDataTable`) or direct `DataFrame(source)`
2. Adapter/Factory
→ internal use of pandas/SQLAlchemy
3. pandas DataFrame
→ conversion routines in `DataFrame` class
4. Output
– `datacolumns` → list of Flet DataColumn
– `datarows` → list of Flet DataRow (with DataCell children)
– `datatable` → Flet DataTable wrapping those columns & rows
5. Client Flet App
← uses `datatable` to render UI

##### Architectural patterns & design principles
- **Adapter Pattern**: Each shortcut class adapts a particular source into a common interface.
- **Factory Method**: `DataFrame` constructor decides how to parse the source.
- **Separation of Concerns**:
- Input parsing & normalization (pandas/SQLAlchemy)
- Conversion to UI model (Flet controls)
- No hardcoded values—fully configurable via attributes

##### Final checklist of elements
- Clear component names (e.g., `CSVDataTable`, `DataFrame`)
- External dependencies called out with version hints (pandas ≥1.x, SQLAlchemy ≥1.x, flet ≥VERSION)
- Notes on the three key attributes that every adapter produces

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input Sources"
        CSVFile["CSV file path"]:::external
        ExcelFile["Excel file path"]:::external
        JSONFile["JSON file path"]:::external
        SQLSource["SQL connection + query"]:::external
        PandasDF["pandas DataFrame"]:::external
    end

    subgraph "Adapters"
        CSVAdapter["CSVDataTable"]:::adapter
        ExcelAdapter["ExcelDataTable"]:::adapter
        JsonAdapter["JsonDataTable"]:::adapter
        SQLAdapter["SQLDataTable"]:::adapter
    end

    subgraph "Core Engine"
        DataFrameCore["DataFrame"]:::core
    end

    subgraph "External Dependencies"
        PandasLib["pandas"]:::extdep
        SQLAlchemyLib["SQLAlchemy"]:::extdep
        FletLib["Flet"]:::extdep
    end

    subgraph "Flet UI Model"
        DataColumns["datacolumns\n(list of DataColumn)"]:::fletmodel
        DataRows["datarows\n(list of DataRow)"]:::fletmodel
        DataTableUI["datatable\n(DataTable instance)"]:::fletmodel
    end

    ClientApp["Client Flet App"]:::client

    subgraph "Project Files"
        InitFile["__init__.py"]:::file
        Setup["setup.py"]:::file
        Req["requirements.txt"]:::file
        Readme["README.md"]:::file
        License["LICENSE"]:::file
    end

    %% Data flows
    CSVFile --> CSVAdapter --> DataFrameCore
    ExcelFile --> ExcelAdapter --> DataFrameCore
    JSONFile --> JsonAdapter --> DataFrameCore
    SQLSource --> SQLAdapter --> DataFrameCore
    PandasDF --> DataFrameCore

    DataFrameCore -->|uses| PandasLib
    DataFrameCore -->|uses| SQLAlchemyLib
    DataFrameCore -->|uses| FletLib

    DataFrameCore --> DataColumns
    DataFrameCore --> DataRows
    DataFrameCore --> DataTableUI

    DataTableUI -->|"renders in"| ClientApp

    %% Click Events
    click InitFile "https://github.com/stanmathers/simple-datatable/blob/master/simpledt/__init__.py"
    click DataFrameCore "https://github.com/stanmathers/simple-datatable/blob/master/simpledt/simpledatatable.py"
    click CSVAdapter "https://github.com/stanmathers/simple-datatable/blob/master/simpledt/simpledatatable.py"
    click ExcelAdapter "https://github.com/stanmathers/simple-datatable/blob/master/simpledt/simpledatatable.py"
    click JsonAdapter "https://github.com/stanmathers/simple-datatable/blob/master/simpledt/simpledatatable.py"
    click SQLAdapter "https://github.com/stanmathers/simple-datatable/blob/master/simpledt/simpledatatable.py"
    click Setup "https://github.com/stanmathers/simple-datatable/blob/master/setup.py"
    click Req "https://github.com/stanmathers/simple-datatable/blob/master/requirements.txt"
    click Readme "https://github.com/stanmathers/simple-datatable/blob/master/README.md"
    click License "https://github.com/stanmathers/simple-datatable/tree/master/LICENSE"

    %% Styles
    classDef adapter fill:#CFE2F3,stroke:#007ACC,color:#000
    classDef core fill:#D9EAD3,stroke:#6AA84F,color:#000
    classDef extdep fill:#FCE5CD,stroke:#E69138,color:#000
    classDef fletmodel fill:#EAD1DC,stroke:#C27BA0,color:#000
    classDef client fill:#EDEDED,stroke:#999999,color:#000
    classDef file fill:#F3F3F3,stroke:#CCCCCC,color:#000
    classDef external fill:#F9F2F4,stroke:#D3D0CB,color:#000
```
