Developer Onboarding

Day-one setup to get the app and these docs running locally.

Prerequisites

• Node 20.19.1 (see .nvmrc). Use nvm use.
• npm (bundled with Node).
• Deno — for edge-function tests (npm run test:ef).
• Supabase CLI — for local DB and migrations (npx supabase).
• Access to the project's .env.local (Supabase URL/anon key and integration keys).

First run

nvm use
npm install
npm run dev          # app on http://localhost:3000

Everyday commands

Command	Purpose
npm run dev	Dev server (port 3000).
npm run build	Production build → dist/ (runs tools/generate-llms.js first).
npm run lint	ESLint (--quiet).
npm test	Full Vitest suite.
npm run test:watch	Vitest watch mode.
npm run test:ef	Deno edge-function tests.
npm run test:db	pgTAP SQL/RPC tests against local Supabase.

Per-feature suites exist too (e.g. npm run test:trade-planner, npm run test:market-mood). Run a single file: npx vitest run path/to/file.test.jsx.

Running this documentation portal

The docs are a separate, internal-only VitePress app under documentations/portal/. They are never part of the production build.

# one-time, from repo root:
npm --prefix documentations/portal install

# then, from repo root:
npm run docs:gen     # regenerate auto-generated reference pages
npm run docs:dev     # serve the portal locally
npm run docs:build   # build static HTML (offline-viewable)

Where to read next

1. Tier System — how the codebase is organised.
2. Data Access Strategy — the most important rule in the codebase.
3. Backend — the edge-function model.
4. Coding Standards — what reviewers enforce.
5. Deployment — dev/production builds and where dist/ lands.

Mental model in 30 seconds

• Features live by access tier (src/tiers/{users,public,admin,landing}/), not by component type.
• Reads = a hook calling a Postgres RPC, with caching. Writes = a service calling an Edge Function.
• Components are pure UI; they never touch Supabase directly.
• Every feature ships a co-located tests/ folder (4-layer model).