Skip to content

Getting started ​

Prerequisites ​

  • Bun 1.4+ (the repo pins packageManager in package.json)
  • A Cloudflare account, only for running the API with D1/R2/Queues (alchemy dev). The web UI and docs run without it.

First run ​

bash
bun install            # also generates src/env.ts for each app via Varlock
cp apps/web/.env.example apps/web/.env
cp apps/server/.env.example apps/server/.env
bun run dev:web        # web app, http://localhost:8001
bun run dev:docs       # this site, http://localhost:3010

The web login page has a Development preview panel (dev builds only) that lets you open any role's space without a database or sign-in. It is removed from production bundles.

Running the API ​

The API is a Cloudflare Worker provisioned by Alchemy:

bash
cd packages/infra && bunx alchemy profile edit   # once: choose your Cloudflare profile
bun run dev                                      # alchemy dev: server on :8000, web on :8001

BETTER_AUTH_SECRET must be at least 32 characters. Generate one with openssl rand -base64 48. Secrets never go in the repo; see Environment.

Everyday commands ​

CommandWhat it does
bun run dev:web / dev:server / dev:docsOne app in development mode
bun run check-typesType-check every project (Nx)
bun run testRun tests (domain package uses bun test)
bun run checkOxlint + Oxfmt (writes formatting)
bun run lint / format:checkCI-style checks, no writes
bun run db:generateGenerate a Drizzle migration from schema changes
bun run db:checkFail if an applied migration was edited or deleted
bun run ui:add <slug>Vendor a beUI component
bun run ui:statusShow local edits and upstream beUI updates
bun run buildBuild everything

Where to start reading ​

  1. Architecture: the repo map and request flow.
  2. Conventions: the rules code review checks.
  3. Versioning: how change is managed. Read this before touching a rule, a price, a template or a table.
  4. Roadmap: what step 1 still needs.

Internal documentation. Not for clients.