# wikar/dux architecture

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

- Interactive diagram: https://gitdiagram.com/wikar/dux
- Repository: https://github.com/wikar/dux

## Overview

DUX is an analytics stack: clients submit DAX-inspired DUX queries, which are parsed, resolved against a live semantic model, emitted as DuckDB SQL, and executed to return tabular results. The server also exposes schema and model operations, DuckLake imports and maintenance, and JSON-backed dashboards; the CLI runs queries locally. The UI adds a field-based query builder, Explorer, and dashboard designer. The README documents the major capabilities, while sampled source confirms selected query, client, dashboard-store, and import behavior; unsampled endpoint wiring is represented only where documented.

Main entry points: [`cmd/duxd/main.go`](https://github.com/wikar/dux/blob/main/cmd/duxd/main.go) (HTTP server), [`executor/executor.go`](https://github.com/wikar/dux/blob/main/executor/executor.go) (Query executor), [`web/app/src/App.tsx`](https://github.com/wikar/dux/blob/main/web/app/src/App.tsx) (Web UI), [`cmd/dux/main.go`](https://github.com/wikar/dux/blob/main/cmd/dux/main.go) (DUX CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_webapp["Web UI<br/>[App.tsx]"]
  node_coreclient["API client<br/>[client.ts]"]
  node_querybuilder["Query builder<br/>[generateQuery.ts]"]
  node_dashquery["Visual query<br/>[elementQuery.ts]"]
  node_cli["DUX CLI<br/>[main.go]"]
  node_dashboardui["Dashboard designer<br/>[DashApp.tsx]"]
  node_dashboardquery["Dashboard queries<br/>[elementQuery.ts]"]
end

subgraph group_service["Service"]
  node_server["HTTP server<br/>[main.go]"]
  node_bootstrap["Runtime startup<br/>[bootstrap.go]"]
end

subgraph group_language["Query pipeline"]
  node_parser["Parser and AST<br/>[parser.go]"]
  node_resolver["Semantic resolution<br/>[resolver.go]"]
  node_emitter["SQL emitter<br/>[emitter.go]"]
  node_executor["Query executor<br/>[executor.go]"]
end

subgraph group_storage["Data and model"]
  node_schema["Schema and model<br/>[schema.go]"]
  node_metadata[("Model metadata<br/>[metadata.go]")]
  node_duckservice["DuckLake service<br/>[service.go]"]
  node_duckowner["DuckLake runtime<br/>[ducklake.go]"]
  node_lakefiles[("Lake catalog and data")]
end

subgraph group_dashboards["Dashboards"]
  node_dashapi["Dashboard API<br/>[server.go]"]
  node_dashstore[("Dashboard store<br/>[store.go]")]
end

node_analyst(("Analyst"))
node_httpclient(("HTTP client"))
node_duckdb[("DuckDB")]

node_analyst -->|"uses"| node_webapp
node_analyst -->|"runs queries"| node_cli
node_httpclient -->|"calls API"| node_server
node_webapp -->|"generates DUX"| node_querybuilder
node_webapp -->|"requests data"| node_coreclient
node_dashboardui -->|"runs visuals"| node_dashboardquery
node_dashboardquery -->|"generates DUX"| node_querybuilder
node_dashboardquery -->|"executes queries"| node_coreclient
node_coreclient -->|"calls REST"| node_server
node_cli -->|"starts runtime"| node_bootstrap
node_cli -->|"executes query"| node_executor
node_server -->|"starts runtime"| node_bootstrap
node_server -->|"executes query"| node_executor
node_server -->|"serves schema"| node_schema
node_server -->|"dispatches lake operations"| node_duckservice
node_server -->|"serves dashboard API"| node_dashapi
node_executor -->|"parses DUX"| node_parser
node_executor -->|"resolves query"| node_resolver
node_executor -->|"emits SQL"| node_emitter
node_executor -->|"executes SQL"| node_duckdb
node_resolver -->|"reads model"| node_schema
node_schema -->|"persists model"| node_metadata
node_duckservice -->|"uses owner"| node_duckowner
node_duckservice -->|"imports and maintains"| node_lakefiles
node_duckowner -->|"uses engine"| node_duckdb
node_duckdb -->|"reads and writes"| node_lakefiles
node_dashapi -->|"reads and writes"| node_dashstore
node_dashboardui -->|"loads and saves"| node_dashapi

click node_webapp "https://github.com/wikar/dux/blob/main/web/app/src/App.tsx"
click node_coreclient "https://github.com/wikar/dux/blob/main/web/core/src/client.ts"
click node_querybuilder "https://github.com/wikar/dux/blob/main/web/core/src/generateQuery.ts"
click node_dashquery "https://github.com/wikar/dux/blob/main/web/app/src/dash/elementQuery.ts"
click node_cli "https://github.com/wikar/dux/blob/main/cmd/dux/main.go"
click node_server "https://github.com/wikar/dux/blob/main/cmd/duxd/main.go"
click node_bootstrap "https://github.com/wikar/dux/blob/main/internal/bootstrap/bootstrap.go"
click node_parser "https://github.com/wikar/dux/blob/main/parser/parser.go"
click node_resolver "https://github.com/wikar/dux/blob/main/semantic/resolver.go"
click node_emitter "https://github.com/wikar/dux/blob/main/emitter/emitter.go"
click node_executor "https://github.com/wikar/dux/blob/main/executor/executor.go"
click node_schema "https://github.com/wikar/dux/blob/main/semantic/schema.go"
click node_metadata "https://github.com/wikar/dux/blob/main/semantic/metadata.go"
click node_duckservice "https://github.com/wikar/dux/blob/main/internal/ducklake/service.go"
click node_duckowner "https://github.com/wikar/dux/blob/main/internal/ducklake/ducklake.go"
click node_dashapi "https://github.com/wikar/dux/blob/main/dash/server.go"
click node_dashstore "https://github.com/wikar/dux/blob/main/dash/store.go"
click node_dashboardui "https://github.com/wikar/dux/blob/main/web/app/src/dash/DashApp.tsx"
click node_dashboardquery "https://github.com/wikar/dux/blob/main/web/app/src/dash/elementQuery.ts"

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_webapp,node_coreclient,node_querybuilder,node_dashquery,node_cli,node_dashboardui,node_dashboardquery,node_httpclient toneBlue
class node_server,node_bootstrap,node_duckdb toneAmber
class node_parser,node_resolver,node_emitter,node_executor toneMint
class node_schema,node_metadata,node_duckservice,node_duckowner,node_lakefiles toneRose
class node_dashapi,node_dashstore,node_analyst toneIndigo
```

## Components

### Clients

- [Web UI](https://github.com/wikar/dux/blob/main/web/app/src/App.tsx): `web/app/src/App.tsx`
- [API client](https://github.com/wikar/dux/blob/main/web/core/src/client.ts): `web/core/src/client.ts`
- [Query builder](https://github.com/wikar/dux/blob/main/web/core/src/generateQuery.ts): `web/core/src/generateQuery.ts`
- [Visual query](https://github.com/wikar/dux/blob/main/web/app/src/dash/elementQuery.ts): `web/app/src/dash/elementQuery.ts`
- [DUX CLI](https://github.com/wikar/dux/blob/main/cmd/dux/main.go): `cmd/dux/main.go`
- [Dashboard designer](https://github.com/wikar/dux/blob/main/web/app/src/dash/DashApp.tsx): `web/app/src/dash/DashApp.tsx`
- [Dashboard queries](https://github.com/wikar/dux/blob/main/web/app/src/dash/elementQuery.ts): `web/app/src/dash/elementQuery.ts`

### Service

- [HTTP server](https://github.com/wikar/dux/blob/main/cmd/duxd/main.go): `cmd/duxd/main.go`
- [Runtime startup](https://github.com/wikar/dux/blob/main/internal/bootstrap/bootstrap.go): `internal/bootstrap/bootstrap.go`

### Query pipeline

- [Parser and AST](https://github.com/wikar/dux/blob/main/parser/parser.go): `parser/parser.go`
- [Semantic resolution](https://github.com/wikar/dux/blob/main/semantic/resolver.go): `semantic/resolver.go`
- [SQL emitter](https://github.com/wikar/dux/blob/main/emitter/emitter.go): `emitter/emitter.go`
- [Query executor](https://github.com/wikar/dux/blob/main/executor/executor.go): `executor/executor.go`

### Data and model

- [Schema and model](https://github.com/wikar/dux/blob/main/semantic/schema.go): `semantic/schema.go`
- [Model metadata](https://github.com/wikar/dux/blob/main/semantic/metadata.go): `semantic/metadata.go`
- [DuckLake service](https://github.com/wikar/dux/blob/main/internal/ducklake/service.go): `internal/ducklake/service.go`
- [DuckLake runtime](https://github.com/wikar/dux/blob/main/internal/ducklake/ducklake.go): `internal/ducklake/ducklake.go`
- **Lake catalog and data**

### Dashboards

- [Dashboard API](https://github.com/wikar/dux/blob/main/dash/server.go): `dash/server.go`
- [Dashboard store](https://github.com/wikar/dux/blob/main/dash/store.go): `dash/store.go`

### Other components

- **Analyst**
- **HTTP client**
- **DuckDB**

## Connections

- Analyst → Web UI: uses
- Analyst → DUX CLI: runs queries
- HTTP client → HTTP server: calls API
- Web UI → Query builder: generates DUX
- Web UI → API client: requests data
- Dashboard designer → Dashboard queries: runs visuals
- Dashboard queries → Query builder: generates DUX
- Dashboard queries → API client: executes queries
- API client → HTTP server: calls REST
- DUX CLI → Runtime startup: starts runtime
- DUX CLI → Query executor: executes query
- HTTP server → Runtime startup: starts runtime
- HTTP server → Query executor: executes query
- HTTP server → Schema and model: serves schema
- HTTP server → DuckLake service: dispatches lake operations
- HTTP server → Dashboard API: serves dashboard API
- Query executor → Parser and AST: parses DUX
- Query executor → Semantic resolution: resolves query
- Query executor → SQL emitter: emits SQL
- Query executor → DuckDB: executes SQL
- Semantic resolution → Schema and model: reads model
- Schema and model → Model metadata: persists model
- DuckLake service → DuckLake runtime: uses owner
- DuckLake service → Lake catalog and data: imports and maintains
- DuckLake runtime → DuckDB: uses engine
- DuckDB → Lake catalog and data: reads and writes
- Dashboard API → Dashboard store: reads and writes
- Dashboard designer → Dashboard API: loads and saves