Operational reference for local setup, verification and maintenance. Start with the README for use cases and the architecture overview; use AGENTS.md for Engineering's branch and review procedure. Run commands from the repository root.
Use Node 24.18.1 (.nvmrc) and npm 11.11.1 (packageManager in package.json). Install NVM if needed and load it in your shell. In the standard Linux Devin environment, use source /home/ubuntu/.nvm/nvm.sh.
nvm install
nvm use
npm install --global npm@11.11.1
npm ci
npm rebuild better-sqlite3 --build-from-source --foreground-scripts
npm run setup:local
npm run db:migrate
npm run db:seed
npm run devOpen http://localhost:3000 and use a synthetic sign-in account. No external database account, authentication provider or hosted application URL is needed. Installation downloads public dependencies; application fonts are bundled locally.
npm ci uses the committed lockfile; do not mix package managers. npm 11 is pinned because npm 10's dependency resolver crashes on this test dependency tree.
Node 24.18.1 is temporarily pinned to avoid the native-addon cleanup regression, pending the complete upstream fix. Run the source rebuild after every clean install or Node switch: it replaces cached or downloaded better-sqlite3 prebuilds with a binary compiled against the selected Node headers. Changing the runtime alone is insufficient. The rebuild requires Python 3, make and a C++ compiler (on Ubuntu: python3 make g++); CI performs the same rebuild.
setup:local generates a random session secret into ignored .env only when that file does not exist. It preserves existing settings. .env.example documents the variables below. Run migrations before seeding or starting the application.
| Variable | Local configuration |
|---|---|
BETTER_AUTH_SECRET |
Generated by setup:local; use a random value of at least 32 characters when configuring manually. Never commit or print it. |
BETTER_AUTH_URL |
Exact application origin, normally http://localhost:3000; localhost and 127.0.0.1 are different origins. Update it when changing the host or port. |
SQLITE_PATH |
SQLite file, normally .data/workspace.sqlite; relative paths are resolved from the repository root when running these commands. |
Exported variables override .env. Next loads .env for the application; the migration/seed commands explicitly load it with Node. For ad-hoc Node commands needing these settings, use node --env-file=.env.
Secrets (.env*, private keys), local SQLite files, dependencies, test output and generated Next files are excluded by .gitignore. Never commit operational credentials.
Drizzle migrations are committed under drizzle/; npm run db:generate generates a migration after schema changes. db:migrate applies only unapplied migrations. db:seed inserts missing synthetic accounts and cases: a fresh database contains three accounts, twelve cases and three initial decision events. Reruns preserve existing password hashes, assignments, decisions and events; they do not reset previous work or repair manually edited records/history.
For an explicitly fresh demonstration database, stop the application and choose a new path in the same shell:
export SQLITE_PATH=".data/fresh-$(date +%s).sqlite"
npm run db:migrate
npm run db:seed
npm run devThis leaves the previous database intact. Keep using that exported path, or set it in .env, to reopen the new database later. SQLite requires a persistent writable disk; serverless durability, backups and deployment are outside this prototype.
This deletes all accounts, sessions, cases and history in the selected database. Prefer the new-path procedure above. Before deleting anything, stop every process using that database and preserve any data you need. Verify the selected path belongs to your disposable demonstration, not another checkout or an existing user database. Do not remove .env.
In the same shell where you selected that disposable SQLITE_PATH:
: "${SQLITE_PATH:?Select the disposable database path before resetting}"
printf 'Permanently reset %s? Type RESET: ' "$SQLITE_PATH"
read -r confirmation
if [ "$confirmation" = "RESET" ]; then
rm -f -- "$SQLITE_PATH" "${SQLITE_PATH}-wal" "${SQLITE_PATH}-shm"
npm run db:migrate && npm run db:seed
fiThe exact SQLite file and its WAL/shared-memory companions are removed; no directory or wildcard deletion is needed. Migrate and seed recreate the initial synthetic state, and old sessions no longer authenticate. Restart with the same selected path and sign in again.
npm run build
npm run startBoth development and production servers default to port 3000. Do not run next dev and next build simultaneously in the same checkout. Confirm listener ownership before stopping a server.
| Command | Purpose |
|---|---|
npm run dev |
Next development server on port 3000 |
npm run lint |
ESLint with no warnings allowed |
npm run typecheck |
Generate Next route types, then TypeScript checks |
npm test |
Vitest UI/registry tests, then server integration tests |
npm run test:server |
Migrations, seeded auth, permissions, transitions, filters, atomicity and conflicts |
npm run test:watch |
Vitest watch mode |
npm run check |
Lint, typecheck and Vitest unit/component/policy/server tests |
npm run build |
Production compilation and static route generation |
npm run start |
Serve the production build |
npm run test:e2e |
Playwright tests against a production server on port 3100 |
npm run setup:local |
Create local environment with a random session secret if absent |
npm run db:generate |
Generate Drizzle migrations from the schema |
npm run db:migrate |
Apply committed migrations to the selected SQLite database |
npm run db:seed |
Insert missing synthetic data without resetting existing work |
For browser checks after installation:
npx playwright install chromium
npm run check
npm run build
npm run test:e2eOn a Linux machine missing browser system libraries, use npx playwright install --with-deps chromium with appropriate OS package permissions. Playwright starts and stops its own production server; port 3100 must be free.
The browser suite creates a separate, freshly migrated and seeded SQLite database under .data on each run and signs in seeded roles. It covers the workspace regressions, login/logout, search/filters (including country selection and composition when configured), assignment/reassignment, all decisions, persistence after refresh, read-only controls, request recovery and direct HTTP permission/validation/conflict checks. Server integration tests use an in-memory database and additionally inject event-insert failures to prove transaction rollback. HTML reports are generated under playwright-report; failure artifacts are in test-results. Session state, databases and test/build output are ignored by Git. Test database files are retained locally; do not run concurrent Playwright suites in the same checkout.
Unexpected KYC API failures return HTTP 500 with a safe message, an errorId and the same reference in X-Request-ID. The queue/detail feedback displays the reference; match it to the unexpected_server_error JSON entry on the server's stderr. Each entry contains the operation, an allowlisted error type and a recognized SQLite code when available. Raw exception messages/stacks, request headers, session tokens and case data are deliberately excluded; these logs are limited diagnostics, not full tracing or an audit trail.
Missing page sessions still redirect to sign-in. Unexpected session lookup failures are logged with operation workspace.session.read and rethrown with only a safe reference. The page error boundary offers Try again, which requests fresh server data and resets the failed view without submitting a case mutation. If the failure continues, contact Engineering. The boundary covers pages and the workspace layout beneath the root layout, not failures in the root layout itself.
Select this repository and follow Run locally and Commands and checks. The repository blueprint managed in Devin's environment settings selects the pinned runtime, installs dependencies, rebuilds SQLite and installs Chromium. A snapshot is a starting environment, not evidence that the current revision has passed checks. Its maintenance dependency install is incremental; use the documented npm ci sequence for clean-checkout verification.
The blueprint does not initialize a demonstration database or keep an application server running. Generate the local environment, migrate and seed only when initialization is needed; preserve existing settings/data. For write/reset verification, use a separate checkout and a new synthetic database path. Verify available ports before startup, keep the authentication origin consistent and avoid simultaneous dev/build processes in one checkout.
Invoke the appropriate repository skill with the business request and acceptance examples. Follow its maintained discovery, confirmation and PR procedure rather than duplicating that workflow in the request. Local startup or restart does not publish the application; no hosting account or production deployment is part of this setup.
Each skill lives under .agents/skills/<skill-name>/SKILL.md with YAML name and description; choose one rather than assuming simultaneous active skills. Cloud Skills documentation describes discovery, invocation and supported format. Next's automatic agent-instruction generation is disabled (agentRules: false); the project maintains its own AGENTS.md.
app/ Routes, root layout and global design tokens
app/(workspace)/ Authenticated shell, Overview and KYC page
app/api/ Better Auth and protected KYC route handlers
components/workspace/ Shell and catalog
components/kyc/ Functional KYC queue, details, actions and history
components/shared/ Queue, detail, status, feedback and heading patterns
components/motion/ Installed Be UI source
lib/tool-registry.ts Typed catalog/navigation metadata
lib/kyc/ Typed domain model, strict validation and initial presentation
lib/server/ Server-only auth, database, schema and KYC service
drizzle/ Generated, committed SQLite migrations
scripts/ Local environment, migration and synthetic seed commands
licenses/ Third-party license notices
tests/ Focused unit/component and browser tests
DESIGN.md Implemented visual specification
Available/foundation entries require a /tools/... route; preview entries require route: null. The discriminated registry type makes accidental preview routes invalid. Each tool owns its route content within the authenticated workspace layout. See architecture for extension steps and server boundaries.
There is no beui runtime package. The following actual source was installed from the Be UI shadcn registry, configured as @beui in components.json:
npx --yes shadcn@4.21.0 add \
@beui/animated-sidebar @beui/table @beui/drawer \
@beui/input @beui/animated-badge @beui/button-statefulThe registry also installs table internals, checkbox, button base, shared-layout and presence/hover/touch/easing helpers. Required runtime dependencies are motion, lucide-react, clsx, tailwind-merge and @tanstack/react-virtual. Their versions and all other dependencies are pinned in package.json. focus-trap-react supplies keyboard containment and focus return around the drawer.
Source is retained unmodified, including provenance comments; workspace styling and Next links live in the compositions. The MIT notice is in licenses/beui-MIT.txt. The locally bundled Geist font (@fontsource-variable/geist) retains its SIL OFL notice. Shared visual and interaction standards are documented in DESIGN.md.
ESLint checks the entire tree. Narrow overrides for installed Be UI source allow its synchronous DOM measurements, shared mutable refs, TanStack Virtual compatibility and empty interfaces; the stateful button additionally measures its label every render. Next's React Compiler is not enabled. These exceptions do not apply to workspace code; rules-of-hooks and other checks still apply to the installed source. Review upstream source changes before updating registry components.
The shell from #1 and Engineering standards from #2 now host the functional KYC workflow (#3). Historical project context remains in epic #7.
The fresh-session workflow report and integrated verification report record the initial work. The PR #15 acceptance report records the native reviewed path. These are revision-specific evidence, not prerequisites that every new tool must follow. See merge controls for enforcement evidence and remaining gaps.