Core data model
SupaCloud’s schema is large (200+ migrations), but the tenancy + resource spine is
small and stable. This page documents that core; the full DDL lives in
server/migrations/ (see the migration index).
Entity relationships
Section titled “Entity relationships”
Tenancy
Section titled “Tenancy”| Table | Role | Key columns |
|---|---|---|
organizations |
Top tenant — billing, seats, SSO, invites | id, slug, kind (personal/team) — plan held on subscriptions (organization_id PK, plan_id) |
organization_members |
A user’s single org membership | user_id (UNIQUE), organization_id, role, seat_type_id |
workspaces |
Tenant resource container (was teams) |
id, slug, organization_id |
workspace_members |
Workspace membership | workspace_id, user_id, role (owner/admin/member) |
A user has exactly one organization; the active org is derived from the active workspace (no org switcher). See editions and entitlements.
Resources
Section titled “Resources”| Table | Role | Owning scope |
|---|---|---|
projects |
A repository/codebase target | workspace_id |
tasks |
An agent task | project_id |
runs |
A first-class execution (task, workflow, connector, …) | workspace_id + task_id/workflow_id |
workflows |
A node/edge orchestration graph | project_id |
workflow_nodes / workflow_edges |
The typed graph | workflow_id |
task_schedules |
Cron/interval triggers | workspace_id (project_id is an optional nullable association) |
agent_profiles |
Reusable agent configuration + execution mode | workspace_id |
agent_capabilities |
Skills/tools (kind='skill' Markdown) |
workspace_id |
Secrets
Section titled “Secrets”Every credential table carries an explicit organization_id plus a
<table>_scope_xor_team_org CHECK, and resolves by a uniform SQL precedence
(ADR 0038). See manage secrets.
All five envelope tables resolve by the uniform ADR 0038 precedence — a locked org row
short-circuits to win org-wide; otherwise: personal (user) › workspace › org.
There is no Shared-vs-Identity precedence split.
| Table | Precedence |
|---|---|
api_key_refs, env_vars, git_credentials, claude_oauth_tokens, tracker_oauth_credentials |
personal (user) › workspace › org (locked org wins org-wide) |
Auditing
Section titled “Auditing”audit_events records every org/workspace mutation (services::audit::record) —
actor, action, target, and a JSON detail blob.