Skip to content

Commit 9ace56d

Browse files
austin-barringtonaustin-barrington
committed
Add documentation and Query Studio chart support.
Introduce a docs/ tree (user and developer guides), expand the README, and add line/bar charts to Query Studio with JSON API series metadata.
1 parent 0742e1d commit 9ace56d

29 files changed

Lines changed: 1835 additions & 115 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
bin/
2+
dashboard
23
node_modules/
34
web/static/css/app.css
45
*.templ.go

‎README.md‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# HyperbyteDB Dashboard
22

3-
A dark-themed Go web dashboard for [HyperbyteDB](../hyperbytedb). It proxies the InfluxDB v1-compatible HTTP API and provides:
3+
A dark-themed Go web dashboard for [HyperbyteDB](https://github.com/hyperbyte-cloud/hyperbytedb). It proxies the InfluxDB v1-compatible HTTP API and provides:
44

55
- **Overview** — health, readiness, Prometheus metrics
66
- **Databases** — databases, retention policies, measurements
7-
- **Query Studio** — TimeseriesQL editor with result tables
7+
- **Query Studio** — TimeseriesQL editor with result tables and Chart.js graphs (line charts for time series, bar charts for scalar aggregates)
88
- **Query History** — digest explorer with Chart.js summaries, Tabulator grid, latency detail panel (ms), recent runs timeline, Query Studio timing
99
- **Data Explorer** — DBeaver-style three-pane browser: lazy object tree (database → retention policy → measurement → tags/fields), Tabulator data grid with pagination/sort/filter, schema metadata panel, tag filter chips, CSV export, deep-link URL params
1010
- **Storage** — disk metrics and (admin) table sizes via chDB
@@ -13,6 +13,13 @@ A dark-themed Go web dashboard for [HyperbyteDB](../hyperbytedb). It proxies the
1313

1414
Built with Go, [templ](https://templ.guide/), Tailwind CSS, and HTMX.
1515

16+
## Documentation
17+
18+
Full documentation lives in [`docs/`](docs/index.md):
19+
20+
- [User guide](docs/user-guide/index.md) — installation, configuration, features, Query Studio, Data Explorer, deployment
21+
- [Developer guide](docs/developer-guide/index.md) — architecture, development workflow, API reference
22+
1623
## Requirements
1724

1825
- Go 1.22+
@@ -22,10 +29,11 @@ Built with Go, [templ](https://templ.guide/), Tailwind CSS, and HTMX.
2229
## Quick start
2330

2431
```bash
25-
# Terminal 1 — HyperbyteDB
26-
cd ../hyperbytedb && cargo run -- serve
32+
# Terminal 1 — HyperbyteDB (see https://github.com/hyperbyte-cloud/hyperbytedb)
33+
cargo run -- serve
2734

2835
# Terminal 2 — Dashboard
36+
git clone https://github.com/hyperbyte-cloud/hyperbytedb-dashboard.git
2937
cd hyperbytedb-dashboard
3038
make init # npm install + go mod tidy (first time)
3139
make build # generate templ, build CSS, compile binary
@@ -156,6 +164,16 @@ The dashboard is a BFF (backend-for-frontend) that:
156164

157165
No changes to HyperbyteDB are required.
158166

167+
## Query Studio
168+
169+
Run TimeseriesQL at `/query`. Each result series has **Table** and **Graph** tabs:
170+
171+
- **Line charts** when results include a time column and numeric values (e.g. `GROUP BY time(1m)`)
172+
- **Bar charts** for single-value aggregates grouped by tags
173+
- Query timing and row counts on every run
174+
175+
See [docs/user-guide/query-studio.md](docs/user-guide/query-studio.md) for examples and API details.
176+
159177
## Data Explorer
160178

161179
The explorer at `/explorer` provides a DBeaver-style interface:
@@ -169,6 +187,8 @@ The explorer at `/explorer` provides a DBeaver-style interface:
169187

170188
JSON API (authenticated): `/api/explorer/tree`, `/api/explorer/schema`, `/api/explorer/data`, `/api/explorer/export`
171189

190+
See [docs/user-guide/data-explorer.md](docs/user-guide/data-explorer.md) for deep links and API parameters.
191+
172192
## License
173193

174194
Same as the HyperbyteDB project.

‎docs/developer-guide/api-reference.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# API reference
2+
3+
All `/api/*` routes except login require an authenticated session cookie. Admin-only HyperbyteDB operations still require admin credentials in the session.
4+
5+
Base URL: dashboard origin (default `http://localhost:3000`).
6+
7+
## Overview
8+
9+
### `GET /api/overview`
10+
11+
Returns health, readiness, version, build, and summarized Prometheus metrics for the Overview page.
12+
13+
## Databases
14+
15+
### `GET /api/databases`
16+
17+
Query params: `selected` (optional database name).
18+
19+
Returns `{ "options": [ { "value", "label", "selected" } ] }` for database dropdowns.
20+
21+
## Query Studio
22+
23+
### `POST /api/query`
24+
25+
Body (JSON or form):
26+
27+
| Field | Description |
28+
|-------|-------------|
29+
| `q` | TimeseriesQL query |
30+
| `db` | Database name |
31+
32+
Response:
33+
34+
| Field | Description |
35+
|-------|-------------|
36+
| `error` | Error message when the query failed |
37+
| `durationMs` / `durationLabel` | Server-side execution time |
38+
| `rowCount` | Total rows across series |
39+
| `hasStats` | Whether timing stats are present |
40+
| `chartHint` | Hint when results are not time-series chartable |
41+
| `series[]` | Per-series columns, rows, and optional chart metadata |
42+
43+
Series chart fields: `canChart`, `chartType` (`line` \| `bar`), `chartLines[]` with `label`, `points[]` (`x`, `y`), and optional `barLabels[]`.
44+
45+
## Query History
46+
47+
### `GET /api/queries/digests`
48+
49+
List query digests with aggregate stats.
50+
51+
### `GET /api/queries/digests/{digest}`
52+
53+
Detail for one digest.
54+
55+
### `GET /api/queries/stats`
56+
57+
Summary statistics for charts.
58+
59+
### `GET /api/queries/runs`
60+
61+
Recent query runs timeline.
62+
63+
### `DELETE /api/queries/digests`
64+
65+
Reset in-memory digest history.
66+
67+
## Data Explorer
68+
69+
### `GET /api/explorer/tree`
70+
71+
Lazy tree nodes.
72+
73+
| Param | Description |
74+
|-------|-------------|
75+
| `level` | Tree level to expand |
76+
| `db` | Database |
77+
| `rp` | Retention policy |
78+
| `measurement` | Measurement |
79+
| `key` | Tag key (for value expansion) |
80+
| `q` | Search filter |
81+
82+
Returns `{ "nodes": [ ... ] }`.
83+
84+
### `GET /api/explorer/schema`
85+
86+
Params: `db`, `rp`, `measurement`. Returns field and tag metadata.
87+
88+
### `GET /api/explorer/data`
89+
90+
Paginated measurement data. Params include `db`, `measurement`, `rp`, time range, tag filters, `page`, `page_size`, sort fields.
91+
92+
### `GET /api/explorer/export`
93+
94+
Same filters as data; returns CSV (row cap 1000).
95+
96+
## Pages (HTML)
97+
98+
| Route | Handler |
99+
|-------|---------|
100+
| `GET /` | Overview |
101+
| `GET /databases` | Databases |
102+
| `GET /query` | Query Studio |
103+
| `GET /queries` | Query History |
104+
| `GET /explorer` | Data Explorer |
105+
| `GET /storage` | Storage |
106+
| `GET /cluster` | Cluster (admin) |
107+
| `GET /admin/users` | Users (admin) |
108+
| `GET /admin/cqs` | Continuous queries (admin) |
109+
| `GET /login` | Login form |
110+
| `POST /login` | Authenticate |
111+
| `POST /logout` | End session |

‎docs/developer-guide/architecture.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Architecture
2+
3+
The dashboard is a **backend-for-frontend (BFF)**. It does not embed HyperbyteDB or store time-series data. Every data operation is proxied to the HyperbyteDB HTTP API.
4+
5+
## Request flow
6+
7+
```text
8+
Browser → Dashboard (Go) → HyperbyteDB HTTP API (:8086)
9+
↓
10+
Session cookie (credentials)
11+
```
12+
13+
1. **Login** — The dashboard validates credentials with a `SHOW DATABASES` probe against HyperbyteDB.
14+
2. **Session** — Username and password are stored in a signed, HTTP-only session cookie.
15+
3. **Proxy** — Authenticated handlers create a per-request HyperbyteDB client with `Authorization: Basic` (or no auth when HyperbyteDB auth is disabled).
16+
17+
No HyperbyteDB configuration changes are required to use the dashboard.
18+
19+
## Authentication and authorization
20+
21+
| Middleware | Applies to |
22+
|------------|------------|
23+
| Session load/save | All routes |
24+
| `RequireLogin` | All pages except `/login` |
25+
| `RequireAdmin` | `/cluster`, `/admin/*` |
26+
| CSRF token | POST `/login`, `/logout`, `/admin/users` |
27+
28+
Admin detection uses HyperbyteDB's admin flag on the authenticated user.
29+
30+
## UI rendering
31+
32+
- **Server-rendered pages** use templ templates with a shared layout (nav, dark theme).
33+
- **Partial updates** use HTMX against JSON APIs (Overview, Query Studio, Query History).
34+
- **Client-side templates** use Mustache (via htmx-ext-client-side-templates) for Query Studio results and Overview cards.
35+
- **Data Explorer** is a hybrid: templ shell with Tabulator and fetch calls to explorer JSON APIs.
36+
37+
## Query History
38+
39+
Query digests and run stats are kept **in memory** in the dashboard process (`internal/handlers/queries_api.go`). They are not written to disk or HyperbyteDB. Restarting the dashboard clears history.
40+
41+
## Static assets
42+
43+
CSS and JS are embedded with `go:embed` under `web/static/`. Tailwind builds `app.css`; Query Studio adds `query.css` and `query-studio.js`.
44+
45+
## Container image
46+
47+
The multi-stage `Dockerfile`:
48+
49+
1. Builds Tailwind CSS and templ output
50+
2. Compiles a static Go binary
51+
3. Runs as non-root user on port 3000

‎docs/developer-guide/development.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Development
2+
3+
## Setup
4+
5+
```bash
6+
git clone https://github.com/hyperbyte-cloud/hyperbytedb-dashboard.git
7+
cd hyperbytedb-dashboard
8+
9+
make init # npm install + go mod tidy
10+
make install-tools # optional: install templ CLI
11+
```
12+
13+
Start HyperbyteDB separately (see [HyperbyteDB docs](https://github.com/hyperbyte-cloud/hyperbytedb)).
14+
15+
## Common commands
16+
17+
| Command | Description |
18+
|---------|-------------|
19+
| `make generate` | Run `templ generate` and Tailwind CSS build |
20+
| `make build` | Generate + compile `bin/dashboard` |
21+
| `make test` | Generate + `go test ./...` |
22+
| `make run` | Generate + `go run ./cmd/dashboard` |
23+
| `make dev` | Same as run with default env vars |
24+
| `npm run watch:css` | Watch Tailwind during UI work |
25+
26+
Environment for local runs:
27+
28+
```bash
29+
export HYPERBYTEDB_URL=http://localhost:8086
30+
export SESSION_SECRET=dev-secret-change-me-in-prod
31+
```
32+
33+
## Working on templates
34+
35+
1. Edit `web/templates/*.templ`
36+
2. Run `templ generate ./web/templates` or `make generate`
37+
3. Commit both `.templ` sources and generated `*_templ.go` if your change requires it (CI runs generate during build)
38+
39+
Helper functions live in `web/templates/helpers.go`.
40+
41+
## Working on Query Studio charts
42+
43+
- Server-side chart data: `internal/handlers/query_series.go`, `query_charts.go`
44+
- JSON API: `internal/handlers/query_api.go`
45+
- Client rendering: `web/static/js/query-studio.js`
46+
- Mustache template: `web/templates/mustache.templ` (`MustacheQueryTemplates`)
47+
48+
Run targeted tests:
49+
50+
```bash
51+
go test ./internal/handlers/ -run 'Chart|Series' -v
52+
```
53+
54+
## Docker and Kind
55+
56+
```bash
57+
make docker-build
58+
make kind-up # build, load into kind, helm install
59+
make kind-rebuild # rebuild image after code changes
60+
make kind-down
61+
```
62+
63+
## CI parity
64+
65+
Before pushing, run the same checks as CI:
66+
67+
```bash
68+
make test
69+
make docker-build
70+
helm lint deploy/chart
71+
```

‎docs/developer-guide/index.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Developer guide
2+
3+
## Stack
4+
5+
| Layer | Technology |
6+
|-------|------------|
7+
| Server | Go 1.22+, [chi](https://github.com/go-chi/chi) router |
8+
| Templates | [templ](https://templ.guide/) + [HTMX](https://htmx.org/) |
9+
| Styling | Tailwind CSS (npm build) |
10+
| Tables / charts | Tabulator, Chart.js (Query Studio and Query History) |
11+
| Sessions | [alexedwards/scs](https://github.com/alexedwards/scs) |
12+
| HyperbyteDB client | InfluxDB v1 HTTP API (`internal/hyperbytedb`) |
13+
14+
## Repository layout
15+
16+
```text
17+
cmd/dashboard/ Main entrypoint and routes
18+
internal/
19+
auth/ Login, CSRF, admin middleware
20+
config/ Environment configuration
21+
handlers/ HTTP handlers and JSON APIs
22+
hyperbytedb/ API client and response types
23+
explorer/ Data Explorer service layer
24+
session/ Session manager wiring
25+
web/
26+
templates/ templ sources (*.templ)
27+
static/ CSS and JS (embedded via go:embed)
28+
deploy/
29+
chart/ Helm chart
30+
kind/ Kind cluster scripts
31+
```
32+
33+
## Topics
34+
35+
- [Architecture](architecture.md)
36+
- [Development](development.md)
37+
- [API reference](api-reference.md)
38+
39+
## Contributing
40+
41+
1. Fork and clone the repository
42+
2. Run `make init` then `make test`
43+
3. Use `make run` or `make dev` for local iteration
44+
4. Open a pull request against `main`
45+
46+
Generated files (`*_templ.go`, `web/static/css/app.css`) are build artifacts. Run `make generate` before committing template or Tailwind changes.

0 commit comments

Comments
 (0)