Backend
The backend (apps/backend, package @hobenakicoffee/backend) is one Supabase project: a Postgres database, the edge functions that run beside it, and file storage. The apps never hold business rules of their own for money, access or moderation: they call the database, and the database decides.
This page is the map. The pages beside it cover each part, and every feature has its own backend page for its tables and functions.
A few terms used throughout:
- RPC (remote procedure call): a Postgres function the apps call through Supabase.
- RLS (row-level security): Postgres rules that decide which rows a user may read or write.
- Edge function: a small TypeScript server function, run by Deno on Supabase, for work SQL cannot do, such as calling the payment gateway.
How it fits together
Rahim, a Supporter, sends Nusrat three coffees (৳60) with a message from her Public page. The marketing site's gift action (apps/marketing/src/pages/@[handle]/_components/_gift/actions/gift.ts) opens a payment through the sslcommerz-init edge function. Once SSLCommerz has taken the money, it calls sslcommerz-ipn, which calls the perform_coffee_gift RPC (apps/backend/supabase/schemas/services/coffee_gifts.sql) as the service role (the Supabase key that bypasses RLS, held only by server code).
That RPC counts the coffees itself, works out the Platform fee, and calls process_service_payment (apps/backend/supabase/schemas/money/payments.sql). That function writes Nusrat's credit row in transactions, adds the gift minus the Platform fee to her Wallet, and writes the Activities both of them see. A signed-in Rahim also gets a debit row; a signed-out one does not. Last, the RPC stores the Coffee gift (in coffee_gifts). Every step runs in one transaction, so the payment and the gift are saved together or not at all.
Key parts
| Part | Where it lives | What it does |
|---|---|---|
| Schema files | apps/backend/supabase/schemas/ | Every table, RPC, policy, trigger and scheduled job, by domain; see Schema files |
| Migrations | apps/backend/supabase/migrations/ | The SQL that hosted databases run, written from the schema change |
| Edge functions | apps/backend/supabase/functions/ | One folder per function, all entering through one serve wrapper; see Edge functions |
| Object storage | apps/backend/supabase/functions/_shared/storage/s3.ts | Uploads to Cloudflare R2 through signed URLs, with an Image check for public images; see Storage and uploads |
| pgTAP tests | apps/backend/supabase/tests/ | Database tests, in the same domain folders as the schemas; see Tests |
| Headless database | apps/backend/scripts/local-db/ | The disposable Postgres each worktree runs its tests against; see Headless database |
| Stack lease | apps/backend/scripts/local-db/lease-cli.ts | Which worktree may use the one Full stack; see Stack lease |
| Seeds | apps/backend/supabase/seeds/ | Local test data only, written through the real RPCs |
| Common types | apps/backend/supabase/schemas/platform/common.sql | The shared enums and the updated_at trigger; see Common types and helpers |
Every RPC, with its arguments and who may call it, is on the generated Database functions page. Every edge function is on Edge functions. Which roles may execute each function is in the RPC grant advisory. To browse the tables, open the schema viewer.
Common tasks
- Run the backend tests:
bunx nx run @hobenakicoffee/backend:test. It needs Docker running. It worked when the pgTAP files, the Deno unit tests and the seed and script tests all pass. - Start the Full stack for a dev server:
bunx nx run @hobenakicoffee/backend:dev. It needs Docker and the Stack lease. It worked whenbun run db:lease show, fromapps/backend, names this worktree. - Change the schema: edit the file under
apps/backend/supabase/schemas/. Fromapps/backend, runsupabase migration new <name> </dev/nulland write the migration. Add a pgTAP test. It worked whenbunx nx run @hobenakicoffee/backend:testpasses; the full steps are inapps/backend/AGENTS.md. - Fill the Full stack with test data:
bun run db:seedfromapps/backend. It needs the Stack lease and resets the Full stack first. It worked whenbun run db:seed:verifypasses.
Gotchas
- The schema files are the source of truth, but hosted databases run migrations. A schema edit without a matching migration never reaches staging or production. The parity tests (pgTAP tests that compare the schema files with what the migrations build) catch reference rows and scheduled jobs that differ; see Tests.
- Reference data lives in the schemas, not the seeds. Rows every environment needs, such as Notification types and platform settings, are inserted in
schemas/and in a migration. Seeds never run on a hosted database (ADR 0014). - A catch that swallows a real failure must report it. SQL calls
private.report_failure, which thereport-failuresedge function sends to Sentry (ADR 0049). - A deploy reaches production. Read Deploy to production before any hosted step.
Related
- Schema files: how the schemas load, and which feature page covers each domain.
- Edge functions: the
servewrapper and the function groups. - Storage and uploads: how a file gets from the browser to R2.
- Headless database: the Postgres each worktree runs its tests against.
- Stack lease: sharing the one Full stack between worktrees.
- Tests: pgTAP layout and the parity tests.
- Common types and helpers: the shared enums.
- Database and Storage: auth settings, the cron schedule, seed data and storage buckets.
- Infrastructure: CI, secrets and deploys.
- Coffee gifts: backend: the example above in full.