139 lines
5.2 KiB
Markdown
139 lines
5.2 KiB
Markdown
# Dimension Lab Website
|
|
|
|
Standalone React runtime for the Dimension Lab system overview dashboard.
|
|
|
|
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 renderer stays content-free, while environment-specific data lives
|
|
in validated dashboard model state.
|
|
|
|
## 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 local development server.
|
|
- `bun run check`: run TypeScript checks.
|
|
- `bun run test`: run Vitest.
|
|
- `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 MVP release gate.
|
|
- `bun run build`: build the production app.
|
|
- `bun run preview`: preview the production build.
|
|
- `bun run storybook`: start the component explorer on port 6006.
|
|
- `bun run build-storybook`: build the static Storybook review artifact.
|
|
- `bun run db:generate`: generate Drizzle migrations from the server schema.
|
|
- `bun run db:check`: validate 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/` are ignored. Drizzle schema lives in
|
|
`src/lib/server/db/schema.ts`; tracked migrations live in `drizzle/`. Runtime
|
|
startup applies the checked-in dashboard migrations before reads or writes. If
|
|
the app is launched from outside the repo 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
|
|
`src/lib/model/fixtures/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 is built with Vite and React. Production uses a small Bun HTTP
|
|
server at `build/index.js` to serve the Vite `dist/` assets and JSON API routes.
|
|
The current persistence runtime is Bun because the MVP SQLite driver is
|
|
`bun:sqlite`.
|
|
|
|
## Storybook
|
|
|
|
Storybook 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. 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 `dist/` and a Bun server
|
|
entry at `build/index.js`. A minimal deployment flow is:
|
|
|
|
```sh
|
|
bun install --frozen-lockfile
|
|
bun run build
|
|
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 `drizzle/` directory so startup migrations can run.
|
|
|
|
### Internal Container
|
|
|
|
The checked-in `Containerfile` builds the React client and Bun server into a
|
|
runtime image. For the Dimension Lab internal host, run it behind Caddy on a
|
|
loopback port and mount persistent state at `/data`:
|
|
|
|
```sh
|
|
podman build -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=/app/drizzle`.
|