Guides

Feature packs

Uses the Ahena CLI (beta). Install it with npm install -g @ahena/cli, or prefix commands with npx @ahena/cli. See Installation. The dashboard covers projects, connections, Doctor, the Stack Graph, plans and approvals without it.

Feature packs answer "what backend functionality does my app need?". Each pack writes backend building blocks into your repository. No UI.

ahena add                      # list packs
ahena add teams                # adds auth and profiles first (dependencies)
ahena add subscriptions --dry-run

Pack	Needs	Tables	Also
`auth`	Supabase	none	`requireUser(request)`, user-scoped client, `GET /api/ahena/me`
`profiles`	auth	`profiles` (created on sign-up)	helpers
`teams`	profiles	`teams`, `team_members` (owner/admin/member)	last-owner guard
`subscriptions`	auth, Stripe	`customers`, `subscriptions`	Checkout, portal, webhook sync, `POST /api/ahena/subscriptions/checkout`
`notifications`	auth, Firebase	`devices`, `notifications`	`notifyUser` push + inbox, `POST /api/ahena/devices`
`file-upload`	auth, Cloudflare R2	`files`	presigned uploads, `POST /api/ahena/uploads`
`audit-log`	auth	`audit_log` (append-only)	`recordEvent`
`marketplace`	profiles, Stripe Connect	`sellers`, `listings`, `orders`	onboarding, Checkout with your fee, webhook sync
`reviews`	profiles	`reviews`, view `review_summaries`	one review per author and subject
`messaging`	profiles	`conversations`, `conversation_members`, `messages`	realtime on Supabase
`booking`	profiles	`resources`, `bookings`	overlap-proof (exclusion constraint), `ahena_busy_times`
`moderation`	profiles	`moderators`, `reports`	moderator-only resolution

Note: feature packs are secondary to provider orchestration. reviews, messaging, booking and moderation are experimental: kept and tested, but not promoted in ahena add's list, so Ahena doesn't drift into being a backend framework.

What gets written

supabase/migrations/<timestamp>_ahena_<pack>.sql: tables, constraints, row level security on every table, grants, triggers. Written once and never rewritten, because it may already be applied. Apply with your migration workflow (supabase db push), and ahena doctor reports migrations that aren't applied yet.
src/ahena/features/<pack>/: row types and helpers. Helpers take a Supabase client that acts as the user (requireUser(request).db), so RLS applies. Server-only work (webhook sync, sending pushes) uses adminClient() with SUPABASE_SERVICE_ROLE_KEY, added to .env.example only when a pack needs it.
Next.js route handlers under app/api/ahena/… (or src/app/…) when the app uses Next.js.
docs/ahena/<pack>.md: what the pack does and who can do what.
src/ahena/payments/events.ts: the Stripe webhook route calls it after verifying the signature; packs that handle Stripe events (subscriptions, marketplace) are wired in, and ahena generate keeps them wired.

Packs are recorded in ahena.config.ts as features: [...]. Generated TypeScript follows the usual rule: files you edit are kept (--force replaces them).

How they're verified

Every migration is applied, in dependency order, to real Postgres (PGlite) with Supabase's auth schema and roles, and the access rules are exercised as different users. Examples: outsiders can't read teams, the last owner can't leave, booking overlaps are rejected by the database, audit entries can't be edited even by the table owner, and users can only mark notifications read. All generated TypeScript (helpers and routes) is typechecked against the real @supabase/supabase-js, stripe, firebase-admin and AWS SDK types.