hackerspace.sh/ARCHITECTURE.md

# Architecture

hackerspace-management is a **Next.js 16 App Router** app (TypeScript, Turbopack) on **Supabase**
(Postgres + Auth). Every space is a tenant; the product is single-space-per-user today (see Known
limitations). This document describes the layers and the exact recipe for adding a feature.

## Request & auth flow

1. **`proxy.ts`** (repo root) is the middleware (Next 16 renamed `middleware` → `proxy`). It refreshes
   the Supabase session and gates every route: anything not in its `PUBLIC_ROUTES` allowlist requires an
   authenticated user, else redirect to `/login`. Public routes (webhooks, cron, `/f/*` public forms,
   `/track`, the resources subsite) each **self-authenticate** (signature/secret/token) — they do not
   rely on a session.
2. **`app/(app)/layout.tsx`** is the second gate (defense in depth): it re-checks the user, loads the
   active `space_members` row, and redirects to signup/onboarding when appropriate. Everything under
   `app/(app)/` renders inside it.

## Layers

Data flows **UI → server action → (validation, guard, domain logic) → data access → Postgres**. Each
layer has one job:

| Layer | Where | Responsibility |
|---|---|---|
| **Generated types** | `types/database.ts` | Supabase-generated row/enum types. **Never hand-edited** — regenerate with `supabase gen types typescript --schema public > types/database.ts`. |
| **Domain types** | `types/domain/*` | Hand-written friendly aliases (`Space = Tables<'spaces'>`), composites, and result shapes. Import via `@/types/domain`. |
| **Validation** | `lib/validations/*` | Zod schemas, one file per feature + `primitives.ts`, re-exported from `lib/validations/index.ts`. Import via `@/lib/validations`. |
| **Domain logic** | `lib/<feature>-logic.ts`, `lib/<feature>/logic.ts` | Pure, side-effect-free decision functions. Unit-tested with no DB (e.g. `dues-payments-logic`, `door-logic`, `invite-claim`). |
| **Guards** | `lib/auth-helpers.ts`, `lib/<feature>-guard.ts`, `lib/actions/<feature>/_guard.ts` | `requireMember` / `requireMemberWithRole` / `parseInput` / `logActivity`; per-feature permission gates returning a `Gate` discriminated union. |
| **Data access** | `lib/supabase/{server,client,admin,proxy}.ts` | Supabase clients. `server`/`client` are **RLS-bound**. `admin` uses the service role and **bypasses RLS**. |
| **Server actions** | `lib/actions/<feature>[.ts \| /]` | `'use server'` mutations/queries. Re-exported through `lib/actions/index.ts`. Client code imports from `@/lib/actions`. |
| **UI** | `app/(app)/<route>/` | `page.tsx` (server: fetch + guard) → `<route>-client.tsx` (thin orchestrator) → `panels/` + `components/` + `types.ts`. |

### The server-action contract (memorize this)

Every action follows the same shape — see `lib/actions/members.ts` for the canonical example:

```ts
'use server'
export async function doThing(input: {...}) {
  const v = parseInput(thingSchema, input)          // 1. validate (Zod)
  if (!v.ok) return { error: v.error }
  const supabase = await createClient()
  const auth = await requireMemberWithRole(supabase, ADMIN_ROLES, 'Admin access required')  // 2. authorize
  if (!auth.ok) return { error: auth.error }
  const { member } = auth
  const { error } = await supabase
    .from('things').update(v.data)
    .eq('id', id)
    .eq('space_id', member.space_id)                // 3. SCOPE to the caller's space (mandatory)
  if (error) return { error: error.message }
  await logActivity(supabase, member, 'updated', 'thing', id)  // 4. audit
  revalidatePath('/things')                          // 5. revalidate
  return { success: true as const }
}
```

**The critical invariant:** whenever you use `createAdminClient()` (service role, RLS off), *every* read,
update, and delete **must** be scoped with `.eq('space_id', member.space_id)` (or an id already proven to
belong to that space). RLS will not save you there — the scope is the only thing preventing a cross-tenant
(IDOR) leak. `__tests__/actions.test.ts` locks this in; `__tests__/auth-helpers.test.ts` covers the gates.

## Feature-folder conventions

A large feature is a folder, not a file. The pattern already exists in the tree:

- **Actions**: `lib/actions/<feature>/` with `'use server'` sub-files split by capability, plain
  `_guard.ts`/`_helpers.ts` (NOT `'use server'` — they export non-async values), and a plain `index.ts`
  barrel. Examples: `lib/actions/{classes,door,forms}/`.
- **UI**: `app/(app)/<route>/` = `page.tsx` + a thin `<route>-client.tsx` orchestrator + `panels/`
  (one per tab/section) + `components/` (modals, rows) + `types.ts`. Exemplars:
  `app/(app)/{customize,ops,settings,members}/`.

Everything is wired through four barrels so features stay decoupled: `@/lib/validations`,
`@/types/domain`, `@/lib/actions`, and `lib/permissions-catalog.ts`.

## Adding a feature (extension) — step by step

A correct feature touches **one file per layer** and imports cross-feature code only through the barrels.

1. **Migration** — add `scripts/0NN_<feature>.sql` (table + RLS policies + any RPC). Enable RLS and write
   per-operation policies scoped by space membership. Then regenerate `types/database.ts`.
2. **Validation** — `lib/validations/<feature>.ts` with `create<Feature>Schema` etc., reusing
   `lib/validations/primitives.ts`. Add `export * from './<feature>'` to `lib/validations/index.ts`.
3. **Domain types** — `types/domain/<feature>.ts`: `export type Feature = Tables<'features'>` + composites.
   Barrel from `types/domain/index.ts`.
4. **Domain logic** — `lib/<feature>/logic.ts`: pure decision functions, unit-tested (no DB).
5. **Guard** — `lib/actions/<feature>/_guard.ts`: `require<Feature>Manager()` returning the `Gate` union
   (copy `lib/actions/classes/_guard.ts` and swap the permission string). Register the permission in
   `lib/permissions-catalog.ts`.
6. **Actions** — `lib/actions/<feature>/<capability>.ts` (`'use server'`). Follow the contract above:
   validate → authorize → **space-scope every query** → `logActivity` → `revalidatePath`. Barrel via
   `lib/actions/<feature>/index.ts`, then `export * from './<feature>'` in `lib/actions/index.ts`.
7. **UI** — `app/(app)/<feature>/page.tsx` (server: fetch + guard, pass data as props) +
   `<feature>-client.tsx` (thin orchestrator) + `panels/` + `components/` + `types.ts`. Client components
   call server actions from `@/lib/actions` — **never write to the DB from the browser client** (that
   skips validation, the authz gate, the activity log, and — for encrypted data — encryption).
8. **Tests** — pure-logic unit tests in `__tests__/`; an action-layer test asserting the space-scope and
   the guard rejection (mirror `__tests__/actions.test.ts`).

## Security model (summary)

- **Two enforcement layers**: Postgres RLS (all 50 tables) *and* explicit code-side authz +
  `space_id` scoping in every action. The admin (service-role) client bypasses RLS, so code-side scoping
  is mandatory there.
- **Roles/statuses** live in `lib/permissions.ts`. `PRIVILEGE_STATUSES` excludes `unverified` — a member
  pending approval in a `require_approval` space holds no privileged capability.
- **Secrets** are AES-256-GCM encrypted at rest (`lib/secrets/*`); always write them via the
  `createSecret`/`updateSecret` server actions (the key is server-only).
- **Public endpoints** self-authenticate: Stripe (per-space signing secret + replay guard), door inbound
  (per-connection vault bearer, `timingSafeEqual`), crons (`CRON_SECRET`), `/track` (192-bit token).

## Build & CI

- `pnpm run typecheck` (`tsc --noEmit`), `pnpm run lint` (ESLint 9 flat config, `eslint.config.mjs`),
  `pnpm run test:run` (Vitest). `.github/workflows/ci.yml` runs all three on PRs and `main`.
- `next build` type-checks (no `ignoreBuildErrors`). **`main` deploys to production on every push**
  (`.github/workflows/deploy.yml` → SSH → the droplet's `deploy.sh`).

## Known limitations / follow-ups

- **Single active space per user** (`getAuthMember` uses `.single()`, fail-closed). Multi-space needs an
  explicit active-space selector before that changes.
- **Regenerate `types/database.ts`** to drop the hand-added RPC entries and the `// TODO(types)` join
  casts, and to de-duplicate the governance row types in `types/domain/governance.ts` into `Tables<>`.
- **`markOnboardingStepDone`** read-modify-writes a JSON column; a concurrent double-submit can drop a
  step. A DB-side atomic append (RPC / jsonb operator) is the fix.
- Integration + e2e suites need a DB service wired into CI (only unit tests + typecheck + lint run today).
- **Full authenticated UI testing** hasn't run in this environment (no local Docker/Supabase). The public
  surface + routing were browser-smoke-tested; the authed screens are verified by `next build` + tsc + tests.

All client-component DB writes now go through server actions (the ops area-lead and comms message writes
were the last direct-browser-write holdouts). The only browser-client usage that remains is auth
(login/signup) and the comms realtime read, which the postgres_changes subscription requires.