Skip to content

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 ​

How a Coffee gift reaches the databaseThe marketing site's gift action starts a payment through the sslcommerz-init edge function. After the gateway takes the money, the sslcommerz-ipn edge function calls the perform_coffee_gift RPC, which books the payment through process_service_payment and stores the Coffee gift.Gift actionapps/marketingsslcommerz-initedge functionPayment gatewaySSLCommerzsslcommerz-ipnedge functionperform_coffee_giftRPCprocess_service_paymenttransactions,wallets, activitiescoffee_gifts

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 ​

PartWhere it livesWhat it does
Schema filesapps/backend/supabase/schemas/Every table, RPC, policy, trigger and scheduled job, by domain; see Schema files
Migrationsapps/backend/supabase/migrations/The SQL that hosted databases run, written from the schema change
Edge functionsapps/backend/supabase/functions/One folder per function, all entering through one serve wrapper; see Edge functions
Object storageapps/backend/supabase/functions/_shared/storage/s3.tsUploads to Cloudflare R2 through signed URLs, with an Image check for public images; see Storage and uploads
pgTAP testsapps/backend/supabase/tests/Database tests, in the same domain folders as the schemas; see Tests
Headless databaseapps/backend/scripts/local-db/The disposable Postgres each worktree runs its tests against; see Headless database
Stack leaseapps/backend/scripts/local-db/lease-cli.tsWhich worktree may use the one Full stack; see Stack lease
Seedsapps/backend/supabase/seeds/Local test data only, written through the real RPCs
Common typesapps/backend/supabase/schemas/platform/common.sqlThe 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 ​

  1. 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.
  2. Start the Full stack for a dev server: bunx nx run @hobenakicoffee/backend:dev. It needs Docker and the Stack lease. It worked when bun run db:lease show, from apps/backend, names this worktree.
  3. Change the schema: edit the file under apps/backend/supabase/schemas/. From apps/backend, run supabase migration new <name> </dev/null and write the migration. Add a pgTAP test. It worked when bunx nx run @hobenakicoffee/backend:test passes; the full steps are in apps/backend/AGENTS.md.
  4. Fill the Full stack with test data: bun run db:seed from apps/backend. It needs the Stack lease and resets the Full stack first. It worked when bun run db:seed:verify passes.

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 the report-failures edge function sends to Sentry (ADR 0049).
  • A deploy reaches production. Read Deploy to production before any hosted step.