# bdarwin/quackjvm architecture

> Architecture diagram of the GitHub repository bdarwin/quackjvm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bdarwin/quackjvm
- Repository: https://github.com/bdarwin/quackjvm

## Overview

quackjvm is an embedded DuckDB analytical layer for Java: map objects into typed columns, write them in batches, query with SQL, and read answers as Java values. Its distinct product branches add CQEngine-backed persistence and query pushdown, plus an optional live metrics dashboard. The README documents materializations and Arrow as core capabilities; the tree supports their source paths, though their internal wiring was not sampled. Edges below reflect only documented workflow or explicit source evidence; unsampled subsystems are shown without speculative connections.

Main entry points: [`quackjvm-core/src/main/java/io/quackjvm/core/sql/Rows.java`](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/sql/Rows.java) (Typed SQL rows), [`quackjvm-dashboard/src/main/java/io/quackjvm/dashboard/QuackDashboard.java`](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-dashboard/src/main/java/io/quackjvm/dashboard/QuackDashboard.java) (Dashboard server), [`quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBDatabase.java`](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBDatabase.java) (CQEngine database), [`quackjvm-core/src/main/java/io/quackjvm/core/duckdb/TableWriter.java`](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/duckdb/TableWriter.java) (Table writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core analytics"]
  node_layout["Columnar layout"]
  node_writer["Table writer<br/>[TableWriter.java]"]
  node_rows["Typed SQL rows<br/>[Rows.java]"]
  node_query["SQL query stream<br/>[SqlQuery.java]"]
  node_arrow["Arrow batches<br/>[ArrowBatch.java]"]
  node_connections["Connection pool"]
  node_materialization["Materialization"]
  node_measure["Measure queries<br/>[MeasureQuery.java]"]
end

subgraph group_cq["CQEngine persistence"]
  node_database["CQEngine database"]
  node_persistence["Object persistence"]
  node_collection["Indexed collection"]
  node_index["DuckDB indexes<br/>[DuckDBIndex.java]"]
  node_pushdown["Query pushdown"]
  node_translator["Join translation"]
end

subgraph group_observe["Metrics dashboard"]
  node_metrics["Metrics registry<br/>[QuackMetrics.java]"]
  node_profile["Query profiles<br/>[QueryProfile.java]"]
  node_dashboard["Dashboard server"]
  node_sampler["Metrics sampler<br/>[Sampler.java]"]
  node_ui["Live dashboard<br/>[app.js]"]
end

node_app(("Java application"))
node_duckdb[("DuckDB")]
node_cqapp(("CQEngine client"))
node_browser(("Browser user"))

node_app -->|"maps objects"| node_layout
node_app -->|"writes batches"| node_writer
node_app -->|"submits SQL"| node_rows
node_layout -->|"provides columns"| node_writer
node_writer -->|"loads tables"| node_duckdb
node_rows -->|"executes SQL"| node_duckdb
node_rows -.->|"reads batches"| node_arrow
node_query -->|"executes query"| node_duckdb
node_connections -->|"opens connections"| node_duckdb
node_app -->|"precomputes queries"| node_materialization
node_app -->|"builds measure SQL"| node_measure
node_measure -->|"runs SQL"| node_rows
node_cqapp -->|"creates collections"| node_database
node_database -->|"configures storage"| node_persistence
node_persistence -->|"backs collection"| node_collection
node_collection -->|"maintains indexes"| node_index
node_index -->|"stores and retrieves"| node_duckdb
node_pushdown -->|"executes translated query"| node_duckdb
node_pushdown -->|"translates joins"| node_translator
node_database -->|"exposes metrics"| node_metrics
node_metrics -->|"supplies observations"| node_dashboard
node_dashboard -->|"samples metrics"| node_sampler
node_dashboard -->|"records profiles"| node_profile
node_browser -->|"views dashboard"| node_ui
node_ui -->|"polls state"| node_dashboard

click node_layout "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/layout/ColumnarLayout.java"
click node_writer "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/duckdb/TableWriter.java"
click node_rows "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/sql/Rows.java"
click node_query "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/sql/SqlQuery.java"
click node_arrow "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/arrow/ArrowBatch.java"
click node_connections "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/duckdb/ConnectionPool.java"
click node_materialization "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/sql/Materialization.java"
click node_measure "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/measure/MeasureQuery.java"
click node_database "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBDatabase.java"
click node_persistence "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBPersistence.java"
click node_collection "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBIndexedCollection.java"
click node_index "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/index/DuckDBIndex.java"
click node_pushdown "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/internal/PushedDownQuery.java"
click node_translator "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/internal/ForeignQueryTranslator.java"
click node_metrics "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/metrics/QuackMetrics.java"
click node_profile "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/metrics/QueryProfile.java"
click node_dashboard "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-dashboard/src/main/java/io/quackjvm/dashboard/QuackDashboard.java"
click node_sampler "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-dashboard/src/main/java/io/quackjvm/dashboard/Sampler.java"
click node_ui "https://github.com/bdarwin/quackjvm/blob/main/quackjvm-dashboard/src/main/resources/io/quackjvm/dashboard/app.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_layout,node_writer,node_rows,node_query,node_arrow,node_connections,node_materialization,node_measure,node_cqapp,node_browser toneBlue
class node_database,node_persistence,node_collection,node_index,node_pushdown,node_translator,node_duckdb toneAmber
class node_metrics,node_profile,node_dashboard,node_sampler,node_ui toneMint
class node_app toneIndigo
```

## Components

### Core analytics

- [Columnar layout](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/layout/ColumnarLayout.java): `quackjvm-core/src/main/java/io/quackjvm/core/layout/ColumnarLayout.java`
- [Table writer](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/duckdb/TableWriter.java): `quackjvm-core/src/main/java/io/quackjvm/core/duckdb/TableWriter.java`
- [Typed SQL rows](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/sql/Rows.java): `quackjvm-core/src/main/java/io/quackjvm/core/sql/Rows.java`
- [SQL query stream](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/sql/SqlQuery.java): `quackjvm-core/src/main/java/io/quackjvm/core/sql/SqlQuery.java`
- [Arrow batches](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/arrow/ArrowBatch.java): `quackjvm-core/src/main/java/io/quackjvm/core/arrow/ArrowBatch.java`
- [Connection pool](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/duckdb/ConnectionPool.java): `quackjvm-core/src/main/java/io/quackjvm/core/duckdb/ConnectionPool.java`
- [Materialization](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/sql/Materialization.java): `quackjvm-core/src/main/java/io/quackjvm/core/sql/Materialization.java`
- [Measure queries](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/measure/MeasureQuery.java): `quackjvm-core/src/main/java/io/quackjvm/core/measure/MeasureQuery.java`

### CQEngine persistence

- [CQEngine database](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBDatabase.java): `quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBDatabase.java`
- [Object persistence](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBPersistence.java): `quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBPersistence.java`
- [Indexed collection](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBIndexedCollection.java): `quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBIndexedCollection.java`
- [DuckDB indexes](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/index/DuckDBIndex.java): `quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/index/DuckDBIndex.java`
- [Query pushdown](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/internal/PushedDownQuery.java): `quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/internal/PushedDownQuery.java`
- [Join translation](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/internal/ForeignQueryTranslator.java): `quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/internal/ForeignQueryTranslator.java`

### Metrics dashboard

- [Metrics registry](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/metrics/QuackMetrics.java): `quackjvm-core/src/main/java/io/quackjvm/core/metrics/QuackMetrics.java`
- [Query profiles](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-core/src/main/java/io/quackjvm/core/metrics/QueryProfile.java): `quackjvm-core/src/main/java/io/quackjvm/core/metrics/QueryProfile.java`
- [Dashboard server](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-dashboard/src/main/java/io/quackjvm/dashboard/QuackDashboard.java): `quackjvm-dashboard/src/main/java/io/quackjvm/dashboard/QuackDashboard.java`
- [Metrics sampler](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-dashboard/src/main/java/io/quackjvm/dashboard/Sampler.java): `quackjvm-dashboard/src/main/java/io/quackjvm/dashboard/Sampler.java`
- [Live dashboard](https://github.com/bdarwin/quackjvm/blob/main/quackjvm-dashboard/src/main/resources/io/quackjvm/dashboard/app.js): `quackjvm-dashboard/src/main/resources/io/quackjvm/dashboard/app.js`

### Other components

- **Java application**
- **DuckDB**
- **CQEngine client**
- **Browser user**

## Connections

- Java application → Columnar layout: maps objects
- Java application → Table writer: writes batches
- Java application → Typed SQL rows: submits SQL
- Columnar layout → Table writer: provides columns
- Table writer → DuckDB: loads tables
- Typed SQL rows → DuckDB: executes SQL
- Typed SQL rows → Arrow batches: reads batches
- SQL query stream → DuckDB: executes query
- Connection pool → DuckDB: opens connections
- Java application → Materialization: precomputes queries
- Java application → Measure queries: builds measure SQL
- Measure queries → Typed SQL rows: runs SQL
- CQEngine client → CQEngine database: creates collections
- CQEngine database → Object persistence: configures storage
- Object persistence → Indexed collection: backs collection
- Indexed collection → DuckDB indexes: maintains indexes
- DuckDB indexes → DuckDB: stores and retrieves
- Query pushdown → DuckDB: executes translated query
- Query pushdown → Join translation: translates joins
- CQEngine database → Metrics registry: exposes metrics
- Metrics registry → Dashboard server: supplies observations
- Dashboard server → Metrics sampler: samples metrics
- Dashboard server → Query profiles: records profiles
- Browser user → Live dashboard: views dashboard
- Live dashboard → Dashboard server: polls state