Configuration

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 schema names are derived from the org slug at registration time and never change, even if the org name changes.

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:

  1. A slug is chosen (derived from the tenant name, must be unique)
  2. An org record is created in public.orgs
  3. A new PostgreSQL schema tenant_{slug} is created and all tables are migrated into it
  4. 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:

TabWhat it's for
GeneralPlatform-wide settings. The default tab when opening System Admin.
OrganizationsGroups 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.
TenantsThe full list of individual tenant orgs โ€” status, plan, and org-level actions (suspend, delete). Searchable, filterable by status, and sorted alphabetically by default.
UsersA 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.
StoragePer-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.

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

VariableDescription
SYSTEM_ADMIN_ORGSlug of the system admin tenant. Admins in this org get cross-tenant admin access.
DATABASE_URLPostgreSQL connection string for the shared database.
JWT_SECRETSecret used to sign access tokens.
APP_URLBase 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 / SECRETGoogle OAuth credentials.
MICROSOFT_CLIENT_ID / SECRETMicrosoft OAuth credentials.
REPLY_HMAC_SECRETSecret used to sign email reply tokens.