What is SMTA?

SMTA (SaaS Multi-Tenant Architecture) is a PostgreSQL database design that handles the tenant infrastructure common to every SaaS application: organizations, sub-units, memberships, roles, auditing, and billing. It sits between your auth platform (Supabase, Payload CMS, or better-auth) and your application tables.

The Three Layers

Layer	Description
Application Layer	Your domain tables (app schema): projects, posts, documents, etc. Accessed via your DAL (CASL, Drizzle, Payload collections)
SMTA Layer	Tenant infrastructure: orgs, units, memberships, roles, audit, billing. Accessed via public.* SQL functions
Platform Layer	Authentication: Supabase JWT, Payload CMS session, or better-auth session

SMTA occupies the middle layer. You bring the application on top and pick the platform below.

@smta/core is adapter-agnostic and loads on stock PostgreSQL 18 — no Supabase, GoTrue, or PostgREST required. Each adapter (Supabase, Payload, better-auth) layers its platform-specific wiring on top.

What SMTA Asks

SMTA’s core question is: “Are you a member of this organization or unit?” — a yes/no gate on row visibility enforced at the database level via Row-Level Security (RLS).

Once that gate is answered, your application layer (using CASL for example) asks the follow-up: “Given that you have access, what are you allowed to do?”

This division is intended to declutter your RLS policies to keep your database scalable, while at the same time giving you full, granular user access control via your application.

Note

Use of a fine-grained, access control system like CASL is optional. SMTA can be used as a simple tenant management system without it, and more broad roles like ‘admin’ and ‘user’.

What SMTA Provides

• Organizations — top-level tenants with members and roles
• Units — sub-groups within an organization (teams, departments, projects)
• Memberships — links users to orgs and units with assigned roles
• Roles — named roles scoped per organization, integrated with CASL
• Invitations — invite users to join an organization by email
• Audit logs — automatic change tracking at the database level
• Soft deletion — records are flagged deleted, not physically removed
• Billing — subscription product and plan management, integrated with Stripe or Lemon Squeezy
• Secrets — per-tenant secret storage via the adapter’s secret mechanism
• Files — file metadata tracking scoped to organizations

What SMTA Does Not Provide

• Authentication — delegated to your adapter (Supabase, Payload, or better-auth)
• Application business logic — that lives in your app schema
• A backend API — public.* functions are exposed via PostgREST (Supabase), your Payload API layer, or better-auth plugin endpoints