Quick-start guide

Sourced from docs/engineering/dev-environment/dev-environment.md and docs/engineering/engineering-standards.md.

Prerequisites

macOS on Apple Silicon is the primary development environment.

# Core tools via Homebrew
brew install go node@20 pnpm git gh jq

# Container runtime
brew install orbstack   # recommended over Docker Desktop

# Supabase CLI
brew install supabase/tap/supabase

Linux (Debian/Ubuntu) works too — see docs/engineering/dev-environment/dev-environment.md for the apt equivalents.

Clone and install

git clone https://github.com/32-north/platform
cd platform
pnpm install

Run the site locally

pnpm --filter @32n/site dev
# Site available at http://localhost:5817

The site uses port 5817 by default. If you open a second worktree, bump PORT= to avoid collisions.

Run Supabase locally

supabase start   # starts Postgres on 54422 (slot A)

Copy .env.example to dev.env and fill in the Supabase keys printed by supabase start.

Branch strategy

All work happens on feature branches — never commit directly to main.

git checkout -b feat/issue-{number}-short-description

Every branch references a GitHub issue number. When you open a PR, include Closes #N or Refs #N in the body.

TDD workflow

This project uses strict TDD. The sequence is:

Write a failing test
Run pnpm --filter @32n/site test and confirm it fails for the right reason
Write the minimum implementation to make it pass
Refactor while keeping tests green
Commit

No implementation before a failing test. This rule has no exceptions for runtime logic. Trivial config edits and /playground/* UI iteration are exempt.

Commit style

Conventional commits with a present-tense, imperative verb:

feat(site): add firmware version database (#123)
fix(bus): handle zero-byte CAN frame gracefully (#456)
docs(contributing): update quick-start for pnpm 9