Developer Onboarding¶

Everything a new engineer needs to go from zero to a running local stack for App-name. Work through the onboarding checklist first to request access, then follow the setup steps in order.

Are you bootstrapping a brand-new project?

This page is for joining an existing App-name repo. If you are standing up a new application from scratch, follow New Project Setup instead.

Onboarding checklist¶

Request these before you start — most require someone else to grant access, so kick them off early.

[ ] GitHub repo access — ask your team lead to add you to the <org> GitHub organisation and the app-name repository.
[ ] Cloudflare WARP enrollment — required for SSH into the test and production hosts. Enrollment is email-based; your team lead approves your device in Cloudflare Zero Trust. See Cloudflare Tunnel.
[ ] Supabase project access — request membership in the test and production Supabase projects from your team lead. See Supabase (Online).
[ ] Secrets & test credentials — obtain the local .env values and a valid test user (email/password) from your team lead. Never commit these. See Secrets & Environment.
[ ] Tooling installed — Node 24, Python 3.12, Git, and Docker on your machine (see Prerequisites below).
[ ] Local stack runs — frontend and backend both start and the smoke tests pass.

Prerequisites¶

Tool	Version	Notes
Node.js	24.x	Frontend (React + Vite). Use a version manager (`nvm`, `fnm`, `volta`) to match the project's `.nvmrc`.
Python	3.12	Backend (FastAPI + SQLModel). Use a virtualenv created from the backend's `pyproject.toml`.
Git	latest	Configure `user.name` and `user.email` globally before your first commit.
Docker + Compose	latest	Docker Desktop on macOS — see Docker (macOS). Runs local Supabase and the app containers.

Two runtimes

The frontend (React + Vite + TypeScript) is pinned to Node 24; the backend (FastAPI + SQLModel) runs on Python 3.12. Match both — a mismatched runtime is the most common cause of install and build failures.

Clone and install¶

The repo is a monorepo with the frontend in ./frontend and the backend in ./backend. Install dependencies in both, then wire up the Husky pre-commit hooks.

# Clone the repository
git clone git@github.com:<org>/app-name.git
cd app-name

# Install frontend dependencies
cd frontend
npm install

# Install backend dependencies (FastAPI + SQLModel)
cd ../backend
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Install Husky pre-commit hooks (run from the repo root)
cd ..
npm run prepare

Don't skip the hooks

The Husky hooks enforce the architecture boundary and run the test gate locally. If npm run prepare is skipped, your commits will pass locally but fail in CI.

Configure `.env`¶

Copy the example file and fill in the values your team lead provided. The canonical list of every variable, where it lives, and which are required per environment is documented in Secrets & Environment.

cp .env.example .env

A minimal local .env looks like this:

# Database (Supabase PostgreSQL)
DATABASE_URL=postgresql://postgres:postgres@localhost:54322/postgres

# Supabase (Auth + client)
VITE_SUPABASE_URL=http://localhost:54321
VITE_SUPABASE_ANON_KEY=<local-anon-key>

# Backend API
VITE_API_URL=http://localhost:5001

# Test credentials (for smoke tests — ask your team lead)
TEST_USER_EMAIL=<test-user@example.com>
TEST_USER_PASSWORD=<test-password>

# Application
NODE_ENV=development
PORT=5001

Test credentials

Smoke tests authenticate directly against Supabase Auth, so VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY must point at the project where the test user actually exists. If they are missing, auth-dependent tests are skipped (not failed).

Run locally¶

Start local Supabase first, then the backend and frontend. Full local-Supabase setup (CLI install, supabase start, seeding, and resetting) is covered in Supabase (Local).

# Terminal 1 — local Supabase (Postgres, Auth, Studio)
supabase start

# Terminal 2 — backend API (FastAPI)
cd backend
uvicorn app.main:app --reload --port 5001

# Terminal 3 — frontend dev server
cd frontend
npm run dev

The frontend will be served by Vite (default http://localhost:5173) and proxies API calls to the backend on port 5001.

Pre-commit hooks¶

This project uses Husky to run quality gates before every commit.

Behaviour	What happens
On `git commit`	The architecture check (`scripts/check-architecture.js`) and the test gate run automatically.
On failure	The commit is blocked. Fix the issue, `git add` your changes, and commit again.
Architecture violation	A direct Supabase call from the frontend (or other boundary break) aborts the commit. See Agent Workflows for the enforced rules.

Emergency bypass¶

git commit --no-verify -m "your message"

Use --no-verify sparingly

A blocked commit almost always means a real problem. Bypassing the hooks only defers the failure to CI, where the same checks run and will block the merge.

Running tests¶

cd backend

# Run the smoke tests (fast API/health checks)
pytest tests/smoke

# Run the full suite
pytest

# Watch mode — re-runs on file changes (pytest-watch)
ptw

# A single file
pytest tests/smoke/test_health.py

Common issues¶

Symptom	Cause	Fix
"Tests failed" on commit	Backend not running, or a change broke an endpoint	Start the backend (`cd backend && uvicorn app.main:app --reload --port 5001`) and re-run the failing test
"No auth token available" warnings	`TEST_USER_EMAIL` / `TEST_USER_PASSWORD` missing	Add the test credentials to `.env` (tests still pass; auth tests are skipped)
"Connection refused"	Backend server not running	Start the backend in its own terminal
Husky hooks not firing	Hooks not installed during `npm install`	Run `npm run prepare` from the repo root
Architecture check fails	Frontend calls Supabase/DB directly	Route the call through the backend API — see Auth Flow

Development is local-first: you run a full Supabase stack (Postgres, Auth, Storage, and the Studio dashboard) on your machine and push/pull code through GitHub. See Local Development for the complete loop — standing up the local database, populating it from the hosted test data, seeding login users, and bringing changes back.

Database schema changes are managed with SQLModel + Alembic; see Migrations for the workflow, and use the /db-migration skill for any schema change.

Quick reference¶

Command	Purpose
`supabase start`	Start local Supabase (Postgres, Auth, Studio)
`cd frontend && npm run dev`	Start the frontend dev server
`cd backend && uvicorn app.main:app --reload --port 5001`	Start the backend API server
`cd backend && pytest tests/smoke`	Run API smoke tests
`npm run prepare`	(Re)install Husky pre-commit hooks
`npm run build`	Build for production
`git commit --no-verify`	Bypass pre-commit gate (emergency only)

Welcome to the team. Once your local stack is green, read Agent Workflows to learn how the assisted workflows and architecture enforcement work, and Version Control for the release process.