Onboarding

Onboarding

Everything you need to go from zero to a merged first PR. This page is a hub — it links to the canonical docs rather than restating them, so follow the links.

1. The system: three repos, one product

Repo	Surface	URL	Stack
surfc/	The app (PWA)	app.surfc.app	React + Vite + Dexie + Supabase
surfc/ (docs/)	Public help	help.surfc.app	VitePress
surfc-web/	Marketing site	surfc.app	Astro (static)
surfc-intranet/	This wiki + admin	intranet.surfc.app	Astro + Starlight

The three repos are siblings (clone them next to each other). The wiki you’re reading documents code in surfc/ and surfc-web/ — those files are not in surfc-intranet/.

2. Local dev quickstart

Clone the repos you’ll work in side by side, then for each:

surfc/ — the app

git clone <surfc-remote> && cd surfc
npm install
cp .env.example .env        # fill in Supabase + PostHog values (see §3)
npm run dev                 # → http://localhost:5173

Node 20+ is fine for surfc/ (no .nvmrc; CI uses Node 20). Docker is required only for the Postgres test harness (npm run db:start).

surfc-web/ — marketing

git clone <surfc-web-remote> && cd surfc-web
nvm use                     # Node 22 (.nvmrc)
npm install
cp .env.example .env.local  # PUBLIC_* values (see §3)
npm run dev                 # → http://localhost:4321

surfc-intranet/ — this wiki + admin

git clone <surfc-intranet-remote> && cd surfc-intranet
nvm use                     # Node 22 (.nvmrc)
npm install
npm run dev                 # → http://localhost:4321

No .env and no test/lint scripts here — npm run build is the only verification gate (it validates Starlight frontmatter and Astro templates).

3. Cloud access checklist

You’ll need access to these services. Ask the Product Owner (Deji) to grant each, then collect the listed values into your local env files.

Service	Why	What you need	Where it’s documented
Supabase	DB, auth, storage, Edge Functions	Project URL + anon key (client); service-role key + DATABASE_URL (local tooling)	Supabase setup runbook
Cloudflare	Pages hosting + Zero Trust Access (live) to this intranet	Your email added to the intranet.surfc.app Access allowlist	CI/CD & Deployment (Access control)
PostHog	Product analytics (EU host)	Project token + host (https://eu.i.posthog.com); a Personal API key is only needed for the admin stats work	Supabase setup runbook (env table)
Resend	Transactional email via Supabase SMTP	No local value — RESEND_API_KEY is a Supabase Edge Function secret only	CI/CD & Deployment (Edge Functions)
Linear	Issue tracking (SUR- prefix)	Workspace invite + GitHub integration linked	Linear setup

Edge Function secrets (Anthropic, Stripe, Azure, Resend, PostHog server keys) are set in the Supabase dashboard, never in a local .env — see CI/CD & Deployment.

4. Your first PR

Read How We Work first — it defines the 7-step workflow loop (Issue → Branch → Implementation → PR → Review → Deploy → Close) and the branching/release rules. The short version:

1. Pick up a Linear issue and move it to In Progress (see Linear setup for the issue workflow).
2. Branch off main — never commit to main directly. Naming: feat/..., fix/..., chore/..., docs/... (issue-scoped branches like dejidipeolu/sur-287-... are also common).
3. Commit in logical units using Conventional Commits (feat(scope): …, fix(scope): …, etc.); reference the ticket in the footer, e.g. [SUR-287].
4. Before you call it done: run npm run build and confirm zero errors (in surfc/, also run npm run test:db if you touched supabase/**). Make sure .env is not staged.
5. Push and open a PR using the template — what changed, why, how to test, open questions — and link the Linear issue. Merging to main auto-deploys (see CI/CD & Deployment).

Make your first PR a small, low-risk change to learn the loop before taking on feature work.

5. Where to find things

You want…	Go to
The app	https://app.surfc.app
Marketing site	https://surfc.app
Public help articles	https://help.surfc.app
This wiki	https://intranet.surfc.app/wiki/
The admin dashboard	https://intranet.surfc.app/admin/
How deploys work	CI/CD & Deployment
The workflow loop & roles	How We Work
Architecture	System Architecture
Per-repo conventions	each repo’s CLAUDE.md and CONTRIBUTING.md

Welcome aboard.