Skip to the content.

Architecture

Open CRM is a React single-page app (Vite, TypeScript, Tailwind, shadcn/ui, TanStack Query) on one Supabase project: Postgres with row-level security, Auth, Storage, and edge functions on Deno. The browser talks to Postgres directly (through PostgREST, as the signed-in user) for everything row-level security can decide, and to an edge function for everything it cannot: work with secrets, email and text messages, encryption, public links, and steps that must happen together.

browser ──(anon key + user token)──> PostgREST ──> Postgres (RLS on every table)
   │                                                   ▲
   └──(user token / link token)──> edge functions ─────┘ (service role)
                                        │
            pg_cron tick ──(x-cron-secret)──> job-runner ──> other functions / SQL
                                        │
                              outbound adapter ──> Resend, Twilio, or dev_outbox

The feature registry

Each domain is a folder, src/features/<domain>/, with a manifest.tsx that exports a FeatureManifest (src/features/types.ts). A manifest declares what the domain contributes:

src/features/registry.ts lists the manifests and sorts each slot by order. The owner app, the shell, the portal and the public router read only the registry, so a domain adds a screen by editing its own manifest, never a shared file.

Manifests load with the entry bundle that every public page downloads, so a manifest imports only React, the router, icons and three small helpers; everything it points at is lazy (lazyNamed). Public pages live under src/features/<domain>/public/, the build names their chunks public-*, and bundleBoundary.test.ts proves none of them loads supabase-js. registry.test.ts checks the other rules (relative routes, unique keys and paths, every nav item opens a screen).

The owner shell and the workspace

The owner app is a shell of four zones (src/components/layout/AppShell.tsx): a permanent icon rail on the left (New, search, the rail items with each count drawn once on its icon’s corner, light and dark, the account), the content, and a bottom bar pinned to the window’s foot. Below md the rail is a labelled drawer opened from a top bar, and the bottom bar is not drawn.

Inside a domain: one api module with its own query keys, Zod at the boundaries, paged reads with a stable tiebreaker, and mutations with error toasts and rollback of optimistic updates. Shared CRM pieces (contact stages, revenue math, the contact picker, the pick-list hook) are in src/lib, src/api and src/hooks.

Principals

Defined once, in 0001_core and 0002_contacts:

A role claim in a token grants nothing. View as client is a client session that a statement trigger on every client-writable table, the storage policies and the edge handler all keep read-only.

The shared edge layer

Every function is supabase/functions/<name>/ with handler.ts (pure, every dependency injected, tested in vitest) and index.ts (wires Deno and Supabase). Common code is in supabase/functions/_shared/:

The outbound adapter

Every email and text message leaves through _shared/outbound.ts, which picks an adapter per send from the environment:

In production a missing provider throws: a message is never dropped silently and never parked in the outbox of a live install. A send answers sent, failed (the provider refused; safe to retry) or unknown (no answer; it may have been accepted, so it is never retried with a new idempotency key).

Background work: jobs and the job runner

No migration schedules anything. Background work is a row in public.jobs, and one scheduled tick runs the queue:

  1. npm run schedules:install stores the project URL and CRON_SHARED_SECRET in Vault and applies supabase/schedules.sql: an every-minute tick that posts to job-runner (reading the URL and secret from Vault when it runs), daily jobs that enqueue one row of each kind only when none is already waiting, an hourly View as client sweep, and a cron history trim.
  2. job-runner claims due jobs with a lease and routes each by its kind (supabase/functions/job-runner/kinds.ts): esign:expire_envelopes, needs:reminder_dispatch and portal:daily_digest post to their functions with the cron secret; ops:maintenance calls the server-only retention functions in SQL.
  3. Execution is at least once, so every callee is safe to run twice and treats “nothing to do” as success. Results (counts and ids only) are kept 30 days and shown on System, Jobs, where the owner can retry a failed job.

Migrations

supabase/migrations/, applied in filename order by npx supabase db push and by the PGlite test harness:

File Holds
0001_core The principals and org_profile, two-factor session checks and backup codes, the rate-limit buckets, the append-only audit log, app settings, the jobs queue, the dev outbox, CSP violation reports, and the shared trigger helpers.
0002_contacts Contacts and their pick-lists (stages, lead sources, organization types, services), businesses, emails, notes, relationships, quotes and upsells; portal accounts, invitations, client activity and tasks; View as client sessions and the read-only rules; the safe contact delete.
0003_documents Documents and folders, encryption metadata, annotations, the private documents bucket and its policies.
0004_messages Client messages and the organization’s message key.
0005_requests Requests, their items, answers and uploaded documents, request categories and tags, templates, and start links.
0006_esign Envelopes, their documents, pages, signers, fields and events, templates, text message codes, drawn signatures, and the e-sign working bucket.
0007_mcp The AI connector’s OAuth tables (every secret stored hashed) and the audited functions behind its tools.
0008_board Work items, their history, board stages and work item types.
0009_marketing Monthly targets and ad spend.
0010_email Group email campaigns, recipients, suppressions and unsubscribe tokens.
0011_control_center The lead-intake key and deliveries, and the public logo bucket.
0012_portal The server side of invitations, sign-in records, and the View as client credential lock.
0013_crm Client tiers and reversible archiving (stamped by the database), and the group email claim that skips archived contacts.
0014_requests Requests that close themselves once nothing is left to do, the once-a-day upload notice, and the guarded write a client’s contact confirmation goes through.
0015_mcp The AI connector’s pipeline, work board and request follow-up tools, and a consent version, bound to each approval, that makes older connector approvals re-consent.
0016_small Deactivating a portal account expires the contact’s pending start links in the same transaction.
0017_crm_full_access Notes that can be corrected and deleted (never relabelled), the database half of changing a portal sign-in email, and the AI connector’s whole-record, quote-accept, note, sign-in email, answer and document tools, with the consent version moved to 3.

Every migration states the schema’s rules in its header, and src/__tests__/db/invariants.test.ts checks the migrated catalog against them (row-level security and an MFA gate on every table, explicit grants, search_path pinned on every function, per-bucket storage policies, the View as client trigger on client-writable tables). CONTRIBUTING.md lists them.

Tests