Multi-Tenant Architecture
Every business on Servelo is an isolated tenant with its own database schema, users, settings, and data. No tenant can access another tenant's data.
Schema isolation
Servelo uses PostgreSQL schema-per-tenant isolation. Each tenant gets its own schema named tenant_{slug} (with hyphens replaced by underscores). For example, an org with slug your-company has its data in the tenant_your_company schema.
All tenant tables (users, tickets, clients, quotes, revenue, expenses, settings, etc.) are created inside the tenant schema. The shared public schema holds only cross-tenant records: the orgs table, magic links, refresh tokens, and the user-org index for OAuth routing.
Tenant resolution
The server identifies the tenant from the request's Host header. The subdomain maps to the org slug:
your-company.serveloapp.com โ slug: your-company โ schema: tenant_your_company
In local development, the slug can be passed via the X-Tenant-Slug header or a query parameter when the host is localhost.
Switching tenants
If your email belongs to more than one tenant, a switch button sits next to your email at the bottom of the sidebar. It opens the tenant picker. Each browser tab stays on its own tenant: you can keep one business open in one tab and another business in a second tab, and saving in one never lands in the other. A new tab opens on the tenant you used last. Tabs on the same tenant share one sign-in. Tenants owned by the same company can be grouped into an organization, which is a group of tenants, not a tenant itself.
Creating a new tenant
New tenants can register at the root domain. During registration:
- A slug is chosen (derived from the tenant name, must be unique)
- An org record is created in
public.orgs - A new PostgreSQL schema
tenant_{slug}is created and all tables are migrated into it - The first admin user is created and a session is started
Plans
Plans are off for now: pricing is set with each customer, and every org gets every feature with no user or ticket limits. An org's billing state is trial (with a trial end date), active, cancelled, or past_due, managed by the system admin.
Suspending an org
A system admin can suspend a tenant by setting is_active = false on the org record. Suspended orgs cannot be accessed, all API requests return a 403. Magic link verification and token refresh are also blocked. The org's data is fully preserved and access can be restored by reactivating.
System admin org
One tenant is designated as the system admin tenant via the SYSTEM_ADMIN_ORG environment variable (set to the org slug). Admin users in that org gain access to the System Admin panel in the application, which provides cross-org management capabilities, split into five tabs:
| Tab | What it's for |
|---|---|
| General | Platform-wide settings. The default tab when opening System Admin. |
| Organizations | Groups multiple tenants under one parent company (e.g. several tenants belonging to the same legal entity). A tenant stays standalone until grouped. Searchable and sortable by name or tenant count. |
| Tenants | The full list of individual tenant orgs โ status, plan, and org-level actions (suspend, delete). Searchable, filterable by status, and sorted alphabetically by default. |
| Users | A cross-tenant user directory: users are grouped by email address across every org they belong to, showing every membership, the master-admin badge, last-used auth method, and last login. Searchable and sortable. |
| Storage | Per-org S3 storage usage for ticket file attachments, with a grand total across all tenants. Drill into an org to see its tickets, then into a ticket to see individual photos โ each can be deleted directly from here to reclaim space. |
The system admin org itself cannot be deleted or suspended through the admin panel. The master admin account (the admin user in that org) cannot be modified through the panel either.
Cross-Tenant Clients
Tenants grouped under the same parent company (see Organizations in the table above) can optionally share client records with each other, so the same customer doesn't have to be re-created in every sibling tenant.
An admin turns this on per source tenant from Settings > Security > Cross-Tenant Clients (only visible when the tenant belongs to a group with at least one sibling). Checking a sibling tenant lets staff in the current tenant search and link that sibling's clients directly on tickets, quotes, and invoices, in the same picker used for local clients.
- A linked client record stays owned by its home tenant. Staff in the borrowing tenant can view it but cannot edit it there.
- Turning a sibling off immediately stops new lookups against it. Tickets, quotes, and invoices already linked to that sibling's clients keep working.
- Revenue tracking recognizes external clients too, so P&L and reporting stay accurate even when the client belongs to another tenant.
OAuth user routing
When a user signs in via Google or Microsoft OAuth, Servelo needs to know which tenant they belong to before they are authenticated (since the OAuth callback doesn't include the tenant). The public.user_org_index table maps email addresses to org slugs, allowing the server to route the user to the correct schema after OAuth completes.
Users are added to user_org_index when they are invited or register. A user can exist in multiple tenants (multiple entries with different org slugs).
Key environment variables
| Variable | Description |
|---|---|
SYSTEM_ADMIN_ORG | Slug of the system admin tenant. Admins in this org get cross-tenant admin access. |
DATABASE_URL | PostgreSQL connection string for the shared database. |
JWT_SECRET | Secret used to sign access tokens. |
APP_URL | Base URL of the app (e.g. https://serveloapp.com). Used in email links. |
AWS_* | S3 and SES credentials for file storage and email sending. |
GOOGLE_CLIENT_ID / SECRET | Google OAuth credentials. |
MICROSOFT_CLIENT_ID / SECRET | Microsoft OAuth credentials. |
REPLY_HMAC_SECRET | Secret used to sign email reply tokens. |