# newcubator/jdbc-excel architecture

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

- Interactive diagram: https://gitdiagram.com/newcubator/jdbc-excel
- Repository: https://github.com/newcubator/jdbc-excel

## Overview

##### Project type and purpose
- This is a pure-Java, Gradle-based library (jdbc-excel) whose sole purpose is to generate Excel spreadsheets from JDBC queries and expose an API for programmatic use.
- It is not a full-stack application or microservice; rather it is a reusable component (jar) with a core ExcelWriter, a family of CellWriter strategies, configuration objects, and tab abstractions.

##### File structure
- Top-level Gradle files and GitHub workflows automate build, test, and Maven Central releases.
- src/main/java/com/newcubator/jdbcexcel: the root package.
- ExcelWriter.java – the façade entry point.
- configuration/ExportConfiguration.java – holds user settings (sheet names, SQL, cell styles, etc.).
- tabs/ExcelTab.java & DefaultExcelTab.java – abstractions over a single worksheet.
- cellwriters/ – a strategy pattern: AbstractCellWriter + concrete writers for String, Number, Date, BigDecimal, Boolean, hintText, replaceableString, Object.
- src/test/groovy – integration and unit tests verifying interaction with a live H2 (data.sql) and cell-writer behavior.

##### Readme insights
- Confirms it’s a library hosted on Maven Central.

##### Diagramming the architecture
a. Main components:
- Client Code (your application)
- JDBC DataSource / Connection (e.g., H2, MySQL)
- ExportConfiguration (holds SQL, sheet metadata, style hints)
- ExcelWriter – orchestrator
- ExcelTab & DefaultExcelTab – per-sheet logic
- CellWriter hierarchy – strategy implementations
- Apache POI (or similar Excel engine)
- Output (FileSystem or OutputStream)
b. Relationships / interactions:
1. Client instantiates ExportConfiguration with a JDBC DataSource, SQL, sheet definitions.
2. Client calls ExcelWriter.export(ExportConfiguration).
3. ExcelWriter opens Connection, executes query, obtains ResultSet.
4. For each row and column:
– ExcelWriter delegates to DefaultExcelTab which picks the correct CellWriter (via cell type or user override).
– CellWriter writes value + style into a POI Workbook cell.
5. After iterating, ExcelWriter hands the populated Workbook to an output sink.
c. Architectural patterns / principles:
– Strategy pattern: CellWriter interface + concrete implementations.
– Single Responsibility: ExcelWriter orchestrates, ExportConfiguration holds settings, ExcelTab handles per-sheet logic.
– Dependency Injection: configuration passed into ExcelWriter.
d. Key technologies & libraries:
– Java 8+ (or compatible)
– Gradle build system
– JDBC API
– Apache POI (or similar) for Excel generation
– Groovy + Spock for testing (in tests)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client Application"]:::external

    subgraph "Core Library"
        EC["ExportConfiguration"]:::core
        EW["ExcelWriter"]:::core

        subgraph "Tabs"
            ET["ExcelTab (interface)"]:::core
            DET["DefaultExcelTab"]:::core
        end

        subgraph "CellWriter Family"
            CW["CellWriter (interface)"]:::extension
            ACW["AbstractCellWriter"]:::extension
            SCW["StringCellWriter"]:::extension
            NCW["NumberCellWriter"]:::extension
            DCW["DateCellWriter"]:::extension
            BCW["BigDecimalCellWriter"]:::extension
            BoolCW["BooleanCellWriter"]:::extension
            ObjCW["ObjectCellWriter"]:::extension
            HintCW["HintTextCellWriter"]:::extension
            RepCW["ReplaceableStringCellWriter"]:::extension
        end
    end

    subgraph "Build & CI"
        GB["Gradle Build Configuration"]:::external
        GH["GitHub Actions Workflows"]:::external
    end

    JDBC["JDBC DataSource/Connection"]:::external
    POI["Apache POI Workbook"]:::external
    Output["Output Sink (FileSystem/OutputStream)"]:::external

    Client -->|"instantiates and provides"| EC
    Client -->|"calls export(config)"| EW
    EW -->|"reads settings from"| EC
    EW -->|"executeQuery() → ResultSet"| JDBC
    EW -->|"creates per-sheet instance"| DET
    DET -->|"delegates write to"| CW
    CW -->|"base class"| ACW
    CW -->|"implements 8 concrete writers"| SCW
    CW --> SCW
    CW --> NCW
    CW --> DCW
    CW --> BCW
    CW --> BoolCW
    CW --> ObjCW
    CW --> HintCW
    CW --> RepCW
    CW -->|"writes cells via"| POI
    EW -->|"outputs populated workbook to"| Output

    click EC "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/configuration/ExportConfiguration.java"
    click EW "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/ExcelWriter.java"
    click ET "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/tabs/ExcelTab.java"
    click DET "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/tabs/DefaultExcelTab.java"
    click CW "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/cellwriters/CellWriter.java"
    click ACW "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/cellwriters/AbstractCellWriter.java"
    click SCW "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/cellwriters/StringCellWriter.java"
    click NCW "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/cellwriters/NumberCellWriter.java"
    click DCW "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/cellwriters/DateCellWriter.java"
    click BCW "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/cellwriters/BigDecimalCellWriter.java"
    click BoolCW "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/cellwriters/BooleanCellWriter.java"
    click ObjCW "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/cellwriters/ObjectCellWriter.java"
    click HintCW "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/cellwriters/HintTextCellWriter.java"
    click RepCW "https://github.com/newcubator/jdbc-excel/blob/master/src/main/java/com/newcubator/jdbcexcel/cellwriters/ReplaceableStringCellWriter.java"
    click GB "https://github.com/newcubator/jdbc-excel/blob/master/build.gradle"
    click GH "https://github.com/newcubator/jdbc-excel/blob/master/.github/workflows/gradle.yml"
    click GH "https://github.com/newcubator/jdbc-excel/blob/master/.github/workflows/release.yml"

    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef extension fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
