Skip to content

Metrognome Codebase Wiki

A shared knowledge base for understanding the Metrognome codebase. Serves both humans (browsing in Obsidian) and LLMs (reading for codebase comprehension).

How to use: Skim this page to find what you need. Overview pages introduce concepts and link to detail pages for deeper dives. Pages marked (stub) have frontmatter only — content is coming.

Architecture

How the system is built — cross-cutting technical patterns.

  • [[overview]] — What Metrognome is, monorepo layout, data flow, external services
  • [[api/overview|API]] — Request pipeline, route conventions
  • [[api/route-handlers|Route Handlers]] — File structure, withErrorHandling, common patterns
  • [[api/response-envelopes|Response Envelopes]] — Success/error/list JSON shapes, pagination
  • [[api/validation|Validation]] — Body and query param validation with Zod
  • [[api/error-handling|Error Handling]] — AppError, ErrorType, throw vs return
  • [[auth/overview|Auth]] — JWT flow, role system, audit context
  • [[auth/roles|Roles]] — Four roles, scoping, pure check functions, ADMIN superrole
  • [[auth/impersonation|Impersonation]] — Admin acts as another user, session-based, audit trail
  • [[auth/frontend-auth|Frontend Auth]] — Supabase clients, AuthContext, getAuthHeaders, verifySession
  • [[database/overview|Database]] — Prisma, transactions, audit, Postgres objects
  • [[database/transactions|Transactions & Audit]] — Three transaction layers, audit context flow, audit trigger
  • [[database/soft-delete|Soft-Delete]] — Extension, registered models, bypass patterns
  • [[database/postgres-objects|Postgres Objects]] — Functions, triggers, RLS, schemas, extensions, roles
  • [[frontend/overview|Frontend]] — App Router, audiences, key patterns
  • [[frontend/routing|Routing]] — Route groups, layouts, auth guards, navigation, command palette
  • [[frontend/data-fetching|Data Fetching]] — Server/public/client layers, SSR-to-client handoff
  • [[frontend/components|Components]] — Atomic design, HeroUI, dynamic imports, modals
  • [[frontend/staff-pages|Staff Pages]] — TablePage + EntityTable lists, StaffFormLayout forms
    • [[frontend/staff-studio-reference|Studio Reference]] — dense single-page replacement for the team's Google Sheet
  • [[frontend/public-pages|Public Pages]] — Marketing conventions, SEO, JSON-LD, section organisms
  • [[stripe/overview|Stripe]] — Connect, webhooks, checkout flow, subscriptions, transfers
  • [[stripe/webhooks|Webhooks]] — Entry point, idempotency, event dispatch, side effects
  • [[stripe/checkout-flow|Checkout Flow]] — Preview → init → confirm → fulfill pipeline
  • [[stripe/subscriptions|Subscriptions]] — Lifecycle: creation, renewal, cancellation, transfers, dunning
  • [[stripe/transfers|Transfers]] — Platform to location money movement, Connect accounts
  • [[background-jobs]] — DB-backed job queue, cron routes, handlers, retry logic
  • [[shared-packages]] — shared-types, shared-schemas, shared-utils, shared-constants, api-client

Domains

What the system does — one page per business domain.

  • [[reservations/overview|Reservations]] — Booking types, shared model, side effects
  • [[reservations/hourly|Hourly]] — Per-session bookings, overlap rules, batch, cancellation
  • [[reservations/lockouts|Lockouts]] — Monthly subscriptions, billing, changes, cancellation
  • [[reservations/tours|Tours]] — Free visits, Acuity integration, guest + staff booking paths
  • [[resources]] — Bookable units, dimensions, availability, groups, attributes
  • [[locations]] — Physical spaces, Connect accounts, geocoding, slugs, groups
  • [[payments]] — Processing, transfers, invoices, dunning, transaction ledger
  • [[pricing]] — PSF calculation, tiers, fees, denormalization, overrides, rounding
  • [[credits]] — Balances, FIFO consumption, org pools, transfers, subscriptions
  • [[physical-access]] — Codes, gates, Schlage/UniFi providers, job-based provisioning
  • [[users]] — User model, roles, RBAC, organizations, profile, Stripe customers
  • [[waitlist]] — Deposits, conversion to lockout, cancellation vs deletion
  • [[checkout]] — All 5 purchase types, preview → init → confirm → fulfill
  • [[communications]] — Email (Resend), SMS (Twilio), consent event sourcing
  • [[referrals]] — Codes, invoice line items, partner payouts
  • [[insurance]] — Add-on subscription item, pricing tiers, timing modes
  • [[migrations]] — Legacy tenant invitation → claim → submit → approve

AI

How AI agents operate in this codebase.

  • [[ai/overview]] — Configuration layers, infrastructure components, doc system relationships
  • [[hooks]] — Pre-commit/push hooks, pattern matching, all 4 hooks detailed
  • [[agents/skills]] — Skill auto-loading, structure, what-NOT-to-include
  • [[../documenting/overview]] — How to write/update vault pages (per-area conventions)
  • [[memory]] — Memory types, MEMORY.md index, current inventory, when to save

Testing

  • [[testing/overview]] — Vitest, test database, Playwright. Hub for [[testing/api]], [[testing/e2e]], [[testing/conventions]].

Infrastructure

How the system runs — ops, tooling, monitoring.

  • [[deployment]] — Vercel, environments, env var conventions
  • [[monitoring]] — Sentry, captureError, error reporting
  • [[analytics]] — Metabase, FDW, materialized views, dashboards

Allium Specs

Formal behavioural specifications, distilled from code or written ahead of it. See docs/engineering/allium-specs/. (For feature design intent in markdown, see docs/features/<name>/spec.md.)

  • checkout.allium — Allium spec for the checkout pipeline (preview → init → confirm → fulfill)
  • referrals.allium — Allium spec for referral codes, payouts, and discount application
  • waitlist.allium — Allium spec for waitlist deposits, conversion, and cancellation