vince/dimensionlab-website
1
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions
dimensionlab-website/README.md

6.5 KiB
Raw Blame History

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

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:

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:

bunx playwright install chromium

Run the CI-ready release gate with:

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:

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:

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.