# teoria/iceduck architecture

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

- Interactive diagram: https://gitdiagram.com/teoria/iceduck
- Repository: https://github.com/teoria/iceduck

## Overview

##### Project type and purpose
- This is a Python library (“iceduck”) that wraps DuckDB and provides an Iceberg‐compliant writer/reader layer on top of it.
- It is intended to be used by other Python applications or scripts to (a) run SQL against DuckDB, and (b) write/read tables in Apache Iceberg format using a local SQLite meta‐store and file‐based warehouse.

##### File structure
- Top‐level:
- README.md – describes usage patterns
- main.py – likely a demo or CLI entry point for testing
- pyproject.toml – build & publish config
- .github/workflows/python-publish.yml – CI/CD for PyPI publishing
- src/iceduck:
- __init__.py – package initializer, exposes connect() wrapper
- iceberg.py – core implementation of Iceberg integration
- warehouse/ – placeholder for file‐based Iceberg warehouse (populated at runtime)

##### README for additional insights
- Two usage modes:
1. Plain DuckDB SQL via iceduck.connect()
2. DuckDB + Iceberg: load a “local” catalog (SQLite), create namespace, upsert to Iceberg table, then read Iceberg table.
- Underlying technologies: DuckDB’s Python API, PyIceberg (via con.load_catalog), SQLite as metadata catalog, local FS warehouse.

##### Detail
- How CI/CD and packaging fits (optional inset): GitHub Actions → PyPI Publishing (pyproject.toml).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main entities
    Client["Client Application / User Script"]:::client
    README["README.md"]:::doc
    PyProj["pyproject.toml"]:::config
    CI["GitHub Actions Workflow"]:::ci
    PyPI["PyPI Publishing"]:::ci

    %% iceduck package
    subgraph "iceduck Package"
        direction TB
        API["iceduck.connect() API"]:::module
        Adapter["Iceberg Adapter Module"]:::module
    end

    %% External engines and extensions
    subgraph "External Engines & Extensions"
        direction TB
        DuckDB["DuckDB Engine"]:::external
        ICExt["Iceberg Extension (PyIceberg)"]:::external
    end

    %% Storage components
    subgraph "Storage"
        direction TB
        SQLite["SQLite Catalog"]:::db
        Warehouse["File System Warehouse"]:::storage
    end

    %% Interactions
    Client --> API
    API --> DuckDB
    Client -->|"SQL query"| DuckDB
    DuckDB -->|"returns DataFrame"| Client

    Client -->|"upsert_iceberg()"| Adapter
    Adapter -->|"delegates to"| ICExt
    ICExt --> SQLite
    ICExt --> Warehouse

    Client -->|"load_catalog()"| Adapter
    Adapter --> SQLite
    Client -->|"scan"| DuckDB
    DuckDB --> Warehouse

    %% CI/CD flow
    CI --> PyPI
    PyPI --> PyProj

    %% Click events
    click Client "https://github.com/teoria/iceduck/blob/main/main.py"
    click API "https://github.com/teoria/iceduck/blob/main/src/iceduck/__init__.py"
    click Adapter "https://github.com/teoria/iceduck/blob/main/src/iceduck/iceberg.py"
    click README "https://github.com/teoria/iceduck/blob/main/README.md"
    click PyProj "https://github.com/teoria/iceduck/blob/main/pyproject.toml"
    click CI "https://github.com/teoria/iceduck/blob/main/.github/workflows/python-publish.yml"
    click Warehouse "https://github.com/teoria/iceduck/tree/main/warehouse/"
    click Warehouse "https://github.com/teoria/iceduck/blob/main/warehouse/.gitkeep"

    %% Styles
    classDef module fill:#ADD8E6,stroke:#000;
    classDef db fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef storage fill:#FFD580,stroke:#000;
    classDef external stroke-dasharray:5 5,stroke:#000,fill:#fff;
    classDef ci fill:#D3D3D3,stroke:#000;
    classDef client fill:#B0C4DE,stroke:#000;
    classDef doc fill:#FFFACD,stroke:#000;
```
