Contributing

This page is the full contributor guide. CONTRIBUTING.md at the repository root is the short version GitHub surfaces on pull requests — when one changes, change the other.

Setup

git clone git@github.com:sachio222/atlas.git && cd atlas
pnpm install
pnpm web

Anonymous watch works with zero environment variables, by design. See Quickstart for the full variable table.

Before you push

pnpm exec tsc --noEmit   # 0 errors — keep it that way
pnpm test                # 0 failures — keep it that way

CI runs the identical two gates in .github/workflows/checks.yml.

House rules

Commit messages

Short prose sentences — what changed and why. No feat:/fix: prefixes. Match git log --oneline -20.

Comments

State constraints code can’t show — why a storage key can’t be renamed, why an effect reads a ref. Don’t add comments that just restate the next line.

Tests accompany behavior

Most modules are TDD’d. A behavior change updates the test that encoded the old behavior, with a comment saying who decided (see Watch.test.tsx).

Anonymous keyless mode

Non-negotiable. Every feature renders without any env keys. Clerk hooks only behind useClerkReady().

Design non-negotiables

Amber = now, crimson = LIVE, no third accent, no purple, no glassmorphism, real flag images never emoji, honor blocklist.json before any stream plays, drop closed channels only, NSFW stays behind its off-by-default toggle.

Storage keys

Keep the atlas. prefix forever — renaming discards user data (src/state/storage.ts).

Where things live

Area	Path
Screens (Expo Router)	`app/` → `src/screens/`
Catalog pipeline (8 sources → one catalog)	`src/catalog/`
Player + stream handling	`src/player/`, `worker/` (CORS relay)
State (zustand, persisted)	`src/state/`
Auth (Clerk + Supabase RLS)	`src/auth/`
Recommendation engine	`src/recs/`, `scripts/build-*.ts`
Jev (TypeSafe) classification	`src/catalog/classify/`
Database migrations	`supabase/migrations/`
Nightly jobs	`.github/workflows/epg.yml`, `recs.yml`

Secrets

gitleaks git . runs clean against full history (config in .gitleaks.toml). Keep it that way — secrets live in .env*.local (gitignored), GitHub secrets, or wrangler secret put. Never in code, fixtures, or workflow files.

The one existing allowlist entry in .gitleaks.toml covers upstream IPTV catalog fixtures whose auth_key URL parameters and playback JWTs look like secrets but are public tokens served to every viewer, not credentials.

Previewing this documentation

cd docs
pnpm dlx mint dev

Get started

How it works

Contribute

Setup

Before you push

House rules

Where things live

Secrets

Previewing this documentation

​Setup

​Before you push

​House rules

​Where things live

​Secrets

​Previewing this documentation

Setup

Before you push

House rules

Where things live

Secrets

Previewing this documentation