160 lines
6.5 KiB
Markdown
160 lines
6.5 KiB
Markdown
# Dimension Lab Website
|
|
|
|
Turbo/Bun workspace for the Dimension Lab system overview dashboard and its
|
|
reusable React component library.
|
|
|
|
This project is not a Homepage customization and does not depend on Homepage
|
|
runtime, frontend code, or configuration. The dashboard will be model-driven:
|
|
the reusable UI package stays content-free, the reusable dashboard model
|
|
package owns schema and validation, and environment-specific data lives in
|
|
validated dashboard model state inside the web app.
|
|
|
|
## Workspace Layout
|
|
|
|
- `apps/web`: Vite React website, Bun API server, model fixtures, Drizzle
|
|
persistence, Playwright e2e checks, and container build.
|
|
- `packages/dashboard-model`: reusable dashboard schema, validation, and
|
|
generic model fixtures shared by apps and tooling.
|
|
- `packages/ui`: reusable dashboard React components, design tokens,
|
|
shadcn/radix primitives, generic fixtures, and Storybook. Component source is
|
|
grouped under `foundation`, `frames`, `operations`, and `telemetry` domains.
|
|
- `docs/superpowers`: migration specs and execution plans used for this repo.
|
|
|
|
## Development
|
|
|
|
```sh
|
|
bun install
|
|
bun run dev
|
|
```
|
|
|
|
This MVP uses Drizzle with Bun SQLite for local file-backed persistence.
|
|
|
|
## Scripts
|
|
|
|
- `bun run dev`: start the web app dev runtime through Turbo.
|
|
- `bun run check`: run TypeScript checks in all workspaces.
|
|
- `bun run test`: run the unit test stage in all workspaces.
|
|
- `bun run test:unit`: run Vitest explicitly as the unit test stage.
|
|
- `bun run test:e2e`: build and run Playwright browser smoke and QA checks.
|
|
- `bun run test:qa`: run the release gate through Turbo across check, unit,
|
|
build, Storybook, and e2e tasks.
|
|
- `bun run build`: build the UI package, production website, and Bun server.
|
|
- `bun run preview`: preview the production web build.
|
|
- `bun run storybook`: start the UI package component explorer on port 6006.
|
|
- `bun run build-storybook`: build the UI package static Storybook artifact.
|
|
- `bun run db:generate`: generate web app Drizzle migrations.
|
|
- `bun run db:check`: validate web app migration consistency.
|
|
|
|
## Persistence
|
|
|
|
Dashboard documents are stored in SQLite through Drizzle. The default database
|
|
URL is:
|
|
|
|
```sh
|
|
DATABASE_URL=file:./data/dimensionlab.sqlite
|
|
```
|
|
|
|
SQLite files under `data/` and `apps/*/data/` are ignored. Drizzle schema lives
|
|
in `apps/web/src/lib/server/db/schema.ts`; tracked migrations live in
|
|
`apps/web/drizzle/`. Runtime startup applies the checked-in dashboard migrations
|
|
before reads or writes. If the app is launched from outside the web app tree,
|
|
set `DASHBOARD_MIGRATIONS_DIR` to the tracked migrations directory. The current
|
|
driver is `bun:sqlite`, which keeps this repo installable in the Bun workflow.
|
|
The store boundary is isolated so a later Postgres driver can replace the
|
|
SQLite connection without changing the dashboard model or renderer.
|
|
Stored dashboard documents pass through a version migration boundary before
|
|
reads or writes; the MVP supports `dashboard.v1` and fails unsupported versions
|
|
with an explicit migration error.
|
|
|
|
## Seed Data
|
|
|
|
The initial Dimension Lab dashboard lives in
|
|
`apps/web/src/lib/dashboard-seed/dimensionlab.ts` as validated model data. It
|
|
includes the first-screen telemetry, service groups, status strip, weather
|
|
module, Iconify icon identifiers, links, and datasource references. Values that
|
|
are not live yet are labeled as fallback values in the data so later datasource
|
|
adapters can replace them without changing presentation components.
|
|
|
|
## Runtime Shape
|
|
|
|
The browser app in `apps/web` is built with Vite and React. Local development
|
|
starts Vite for HMR and a loopback Bun API server for `/api/*` routes.
|
|
Production uses a small Bun HTTP server at `apps/web/build/index.js` to serve
|
|
the Vite `apps/web/dist/` assets and JSON API routes. The current persistence
|
|
runtime is Bun because the MVP SQLite driver is `bun:sqlite`.
|
|
|
|
## Storybook
|
|
|
|
Storybook lives with `packages/ui` and covers the reusable UI components with
|
|
generic fixtures only. Stories must not import environment-specific dashboard
|
|
content; the presentation layer accepts labels, values, icons, status, and links
|
|
through typed props.
|
|
|
|
## MVP QA Gate
|
|
|
|
Install the Chromium browser once before running e2e checks locally:
|
|
|
|
```sh
|
|
bunx playwright install chromium
|
|
```
|
|
|
|
Run the CI-ready release gate with:
|
|
|
|
```sh
|
|
bun run test:qa
|
|
```
|
|
|
|
The gate runs TypeScript checks, Vitest coverage for model,
|
|
persistence, renderer, datasource mocks, and presentation boundaries, the
|
|
production build, the static Storybook build, and Playwright desktop/mobile
|
|
smoke checks against the built adapter output. Turbo owns the release task
|
|
graph; app package scripts stay as leaf commands and do not re-run the QA
|
|
pipeline internally. Playwright also performs
|
|
baseline screenshot checks, keyboard navigation checks, reduced-motion checks,
|
|
landmark checks, and axe accessibility checks against the real model-driven
|
|
route.
|
|
|
|
Playwright uses an isolated SQLite database per run unless
|
|
`PLAYWRIGHT_DATABASE_URL` is set explicitly.
|
|
|
|
Presentation code is checked for Dimension Lab content leakage. Environment
|
|
specific labels, links, icon names, fallback values, and datasource references
|
|
belong in validated model data, not reusable components.
|
|
|
|
## Deployment Notes
|
|
|
|
The production build emits Vite client assets under `apps/web/dist/` and a Bun
|
|
server entry at `apps/web/build/index.js`. A minimal deployment flow is:
|
|
|
|
```sh
|
|
bun install --frozen-lockfile
|
|
bun run build
|
|
cd apps/web
|
|
DATABASE_URL=file:/data/dimensionlab.sqlite HOST=0.0.0.0 PORT=3000 bun build/index.js
|
|
```
|
|
|
|
Mount `/data` or set `DATABASE_URL` to another persistent SQLite path. If the
|
|
process starts outside the repository root, set `DASHBOARD_MIGRATIONS_DIR` to
|
|
the checked-in `apps/web/drizzle/` directory so startup migrations can run.
|
|
|
|
### Internal Container
|
|
|
|
The checked-in `apps/web/Containerfile` runs
|
|
`turbo prune @dimensionlab/web --docker`, installs the pruned manifest set, and
|
|
builds the React client plus Bun server from the pruned workspace source. For the
|
|
Dimension Lab internal host, run it behind Caddy on a loopback port and mount
|
|
persistent state at `/data`:
|
|
|
|
```sh
|
|
podman build -f apps/web/Containerfile -t localhost/dimensionlab-website:latest .
|
|
podman run --rm \
|
|
--publish 127.0.0.1:25341:3000 \
|
|
--volume "$HOME/containers/dimensionlab-website/data:/data:Z" \
|
|
--env-file "$HOME/containers/dimensionlab-website/dimensionlab-website.env" \
|
|
localhost/dimensionlab-website:latest
|
|
```
|
|
|
|
The env file must provide `AGENT_CONFIG_TOKEN`. Runtime defaults inside the
|
|
image set `HOST=0.0.0.0`, `PORT=3000`,
|
|
`DATABASE_URL=file:/data/dimensionlab.sqlite`, and
|
|
`DASHBOARD_MIGRATIONS_DIR=/repo/apps/web/drizzle`.
|