Frequency
A platform for place-based, in-person community practice. Four nouns:
Member, Space, Circle, Event. Channels are the topical
layer people tune into. Hubs and Nexuses emerge from Circles; they are not
primary nav. An Outpost is a Nexus home base, not the top unit.
Mobile-first (the app is the primary doorway; the web is the secondary
surface and the SEO/discovery front), with a physical-world engagement layer
(QR / NFC / geolocation).
Current build: Next.js 16 (App Router / RSC) + Supabase (Postgres, Auth,
Realtime, Storage) on Vercel, Tailwind v4.
Where documentation lives: three homes, by audience
| Home | Audience | Contains |
|---|
GitHub (/docs, AGENTS.md, this README) | Developers | architecture, schema, conventions. Status: docs/BUILD-BACKLOG.json |
Public help center (content/help/, served at /help) | Members | how to use the product, in member language |
| Notion | Operators, hosts, training | how to operate/moderate the product, host/admin guides, community policy |
Rule of thumb: if it tells a developer how to build it, it goes in Git; if it
tells a member how to use it, it goes in the help center; if it tells an operator how
to run or moderate it, it goes in Notion. One change updates each home in its own voice:
we single-source the routing, not the prose. Full spec:
docs/DOCS-PROTOCOL.md and docs/HELP-CENTER.md.
Architecture at a glance
Five layers separated by stable contracts, so no single framework choice can
trap us (full rationale in SCALE-ARCHITECTURE):
PRESENTATION web: Next.js/RSC · mobile: Expo/RN (later) · design tokens · headless UI ← replaceable
COMPOSITION server-composed capability MODULES, chosen per user by role + involvement
CONTRACT one typed, presentation-neutral contract (RPC view-models) ← shared by web + mobile
DOMAIN/CORE business rules + capability resolver, framework-independent
DATA Supabase/Postgres (+PostGIS) as source of truth · AUTHZ = RLS + SECURITY DEFINER RPCs
Engagement/gamification rides on top as one pipeline
(ENGAGEMENT-ARCHITECTURE):
SOURCE adapters (web · task · QR · NFC · geo · P2P) → server VERIFICATION
→ append-only EVENT LEDGER + rules → REWARD ledger (+ realtime feedback)
The one decision everything hinges on: the contract + capability layer —
presentation-neutral data, computed server-side, consumed identically by web and
mobile.
Documentation map
Which plan is live (read this before anything else)
The repo carries years of planning documents, and several of them describe themselves as the
single source of truth. The live set is short, and AGENTS.md §"Which plan is live"
is its authority; this section mirrors it:
| Question | Where the answer lives |
|---|
| Where does the work stand? | docs/BUILD-BACKLOG.json — the ONE list. Run pnpm backlog for the working view. Status never lives in prose (ADR-1043). |
| What ships next? | UX-MATURITY-PLAN (ADR-925; its §Sequencing table) + BUILD-LIST (ADR-921; the phase runway, including the parked phases). |
| Why was it decided? | DECISIONS — the ADR record. A plan doc that contradicts an ADR is stale, not authoritative. |
| What are the product nouns? | NAMING wins names. CORE-MODEL is commercial law (ADR-1294). FOCUS-MODEL is the accepted interior (ADR-1403). Four nouns: Member, Space, Circle, Event. Channels are the topical layer. |
| The editor, blocks, block registry | EDITOR-ARCHITECTURE (ADR-974…978), phases E0–E10. Read it before touching any of them. |
The locked canons, each machine-enforced or gated: NAMING +
CONTENT-VOICE (every word a human reads),
PAGE-FRAMEWORK (one shell, seven page shells, one chrome map; RailGrid is not a shell; WidgetSlot is a sketch; railFor is the code default and operator overrides can beat it),
STUDIO (creation wizards derive from a manifest),
MENU-CONTRACT (the admin menu derives from four catalogs), and
DEPLOY-SAFETY (merging main deploys to production; the artifact gates).
Everything below this line is context. DEVELOPMENT-MAP, BUILD-PHASES,
ROADMAP, CHECKLIST and BACKLOG are history with superseded banners: worth reading for
rationale, never for status. BUILD-SEQUENCE and MASTER-TODO were absorbed into
docs/BUILD-BACKLOG.json (HYG-104) and removed. When the code and a doc disagree, the code wins, and the doc gets
fixed in the same pass.
Strategy & target architecture (the frame — read in this order)
- PLATFORM-VISION: the whole-system frame (the why). One
community graph spanning a nonprofit (Foundation) + for-profit (Labs), one shared game,
money hard-partitioned by entity, verticals (Programs/Marketplace/Collective/affiliate/
donations/Lab Spaces) as
modules, the geographic flywheel. Governs ADR-029→036. Companions for the live
product: CORE-MODEL and FOCUS-MODEL.
- IA-STRATEGY — information architecture: Circle + Channel
as the belonging words (Interests is retired); Hubs/Nexuses contextual; in-person
designator; role + milestone "wake-up" gating. (Labs/demand-proving are out of
website scope.)
- PAGE-FRAMEWORK — one shell, seven page shells
(Stream / Index / Detail / Dashboard / Focus / WizardShell / Admin, §8),
composable modules + slots, and the on-page operator Settings panel (ADR-180/182).
RailGrid is not a shell. WidgetSlot is a sketch.
- SCALE-ARCHITECTURE — the 5-layer lock-in-resistant
model, RSC/PPR rendering, Postgres scaling seams, future-proofing.
- CAPABILITIES-AND-MOBILE — one capability
resolver powering inline admin + cross-platform parity; why authz converges on
RLS + RPCs.
- ENGAGEMENT-ARCHITECTURE — the event →
verify → ledger → reward backbone hosting all gamification sources.
- TECH-STRATEGY — the capstone: recommended stack,
decisions made, and the phased plan.
Executable plan
docs/BUILD-BACKLOG.json + pnpm backlog — where the work
stands. Every row states how it is proven; pnpm check:backlog runs the probes and fails both
ways (a stale open row and a regressed done row).- UX-MATURITY-PLAN — what ships next. Eight lifts, each with
its gate and its number; the §Sequencing table is the order.
- BUILD-LIST — the phase runway around it, including the phases the
owner has deliberately parked. Its rows defer status to the backlog.
- OVERVIEW — synthesis of IA, page framework,
gamification, and the lock-in-resistant architecture. Not a north star and not
the plan.
- START-HERE — new-developer orientation. Run it locally,
what to read in order, and how to ship a change. Not a rival front door;
AGENTS.md names the live set.
- BUILD-PHASES, CHECKLIST,
DEVELOPMENT-MAP — history.
Each carries a superseded banner; read for items no current plan absorbed, never for status.
BUILD-SEQUENCE and MASTER-TODO were absorbed into the one list (HYG-104) and removed.
As-is engineering reference (current codebase)
- ARCHITECTURE — current stack, directory map, the RLS /
admin-client authz model, server-action conventions, cron. Read first before
touching code.
- GLOSSARY — domain language (names themselves are locked in
NAMING). DATABASE — tables, enums, migrations.
BACKLOG — the 2026-06 hygiene + env-var list, superseded (banner at top).
- DESIGN-LANGUAGE — the design language and page-flow blueprint on
the DAWN tokens; THEME-PROTOCOL — the theming operating manual.
DESIGN is the original warm-editorial brief, kept for history.
- DECISIONS — architecture decision records (ADRs).
DOCS-PROTOCOL — how docs are routed (technical → git,
instructional → Notion). Follow it on every change.
- BASELINE-ASSESSMENT — the 2026-06 senior systems review
(front-end/theming, role-based admin, security, code health, data architecture) and the
cleanup roadmap it proposed (ADR-246). History: read it for the diagnosis, never for status.
- ROADMAP — the original product feature roadmap (P0–P7), superseded.
— discovery layer.
As-is vs to-be: ARCHITECTURE.md/DATABASE.md/GLOSSARY.md describe what
exists today (pnpm check:arch-doc holds ARCHITECTURE.md to the tree). The strategy docs
describe where we're going; BUILD-BACKLOG.json records how far along it is.
Getting started (developers)
Prerequisites: Node 20+ and pnpm 10.33.0 — pinned via the packageManager
field, so let corepack manage it (don't npm i -g pnpm).
corepack enable # use the exact pnpm version this repo pins
pnpm install
pnpm approve-builds # first time only: allow sharp + unrs-resolver to build
cp .env.example .env.local # then fill in the values below
pnpm dev # Next.js dev server (Turbopack) → http://localhost:3000
Environment variables (.env.local). vercel env pull does not help here —
the Vercel vars are marked Sensitive, so they pull back blank. Fill these by hand
(the minimum to boot the app):
| Var | Where to get it |
|---|
NEXT_PUBLIC_SUPABASE_URL | Supabase → Settings → API → Project URL |
NEXT_PUBLIC_SUPABASE_ANON_KEY | Supabase → Settings → API → publishable key |
SUPABASE_SERVICE_ROLE_KEY | Supabase → Settings → API → secret key (server-only) |
NEXT_PUBLIC_SITE_URL, NEXT_PUBLIC_APP_URL | http://localhost:3000 |
Feature keys (Stripe, Resend, AI, KV/Redis, VAPID) only matter when you exercise those
features — leave them blank otherwise.
Quality gates (run before you push):
pnpm exec tsc --noEmit # the project's main correctness gate
pnpm lint
pnpm test # Vitest unit suite (repo-wide co-located *.test.ts)
pnpm check:authz # authz contract gate (admin-client guards)
Tests are a repo-wide unit suite of co-located *.test.ts files (under test/ and
alongside the code they cover in app/, components/, and lib/ — capabilities,
currency, the outbox queue, suppression, webhook verification, and more). They
complement, not replace, tsc --noEmit + ESLint + pnpm check:authz + manual
verification. Schema source
of truth is supabase/migrations/; see ARCHITECTURE for the
authorization model you must follow (the admin client bypasses RLS — authz is
enforced in application code today, converging on RLS + RPCs per the strategy).
Shipping a change
main is protected — every change goes through a pull request (you cannot push to
main directly).
git checkout main && git pull
git checkout -b feature/your-change
# ...edit, run pnpm dev + the gates, commit...
git push -u origin feature/your-change
Open a PR → Vercel builds a preview URL → CI + preview must be green → merge
deploys to production. The full workflow (local + on-the-go, and the path to a
team-grade setup) lives in docs/WORKFLOW.md.
⚠️ One shared database (for now). Local, preview, and production all point at the
same Supabase project. Develop freely, but never run destructive or migration
commands against it — in particular, do not run supabase db push until the
migration baseline is established. See
WORKFLOW.md → Scaling to a team.
How we work the plan
- Start at
pnpm backlog (docs/BUILD-BACKLOG.json) for where we
are and what is built; take the ordered "what to build next" from
UX-MATURITY-PLAN §Sequencing and BUILD-LIST.
(DEVELOPMENT-MAP.md and BUILD-PHASES.md are superseded history.
BUILD-SEQUENCE and MASTER-TODO were absorbed into the one list and removed.)
- Each backlog row states how it will be proven (its probe) and the doc that governs it
(
source.file). A probe measures the consequence, never the row's own title.
- Close the row in the same PR that lands the work by making its probe pass — never by editing
prose and never by deleting the probe (ADR-1043). Re-test a row's
premise before working it; premises expire.
- Don't start work whose dependencies aren't met, and record any decision as an ADR in
DECISIONS.
Proposed Notion structure (user / training side — to build)
Mirror, don't duplicate, the Git docs — translate them into human language:
- Welcome / What is Frequency — Member, Space, Circle, Event, Channels.
- Member guide — joining/finding a Circle, events, the wake-up onboarding,
earning (gems/zaps), QR/NFC/ghost-node basics.
- Host guide — running a Circle, assigning tasks, broadcasts, inline admin.
- Guide / Mentor / Janitor guides — escalating leadership/admin training.
- Partner (business) guide — directory listing, NFC plaque, offers.
- Community policy — moderation, safety (incl. physical-node safety).
(Ask before scaffolding — needs the target Notion workspace.)
