Skip to main content

Directory Schema — the Global Database

Drumee keeps two kinds of data. Tenant data belongs to one organization: its workspaces, files, conversations and tasks. The directory belongs to no single organization: it says who exists, which organizations exist, and who belongs to what. The directory lives in the global database, and every request starts there.

This page is the reference for the global database.

The central idea​

Three questions are answered by the directory, in this order, for every request:

QuestionAnswered by
Who is calling?sessions → users
What do they belong to?org_members (organizations) and workspace_members (workspaces)
Where is the data?tenants — which names the database that holds the tenant's data

Memberships are global on purpose. A person can belong to several organizations, and can be a member of a workspace owned by an organization they are not part of (a guest or an outside member). Neither fact could be recorded inside one tenant's data.

Entity relationships​

  • Every user has exactly one personal tenant, created at sign-up together with a personal workspace.
  • A tenant is personal or org. Subscribing to a team plan turns the personal tenant into an organization in place — the data does not move.
  • An organization's role ladder is stored on org_members.level; a workspace's on workspace_members.role. They are independent. → RBAC System

Databases​

DatabaseHoldsSelected by
GlobalThe directory and everything that spans tenantsAlways the same
Tenant poolThe data of all tenants that share a database; every document carries tenant_idtenants.isolation = "pool"
DedicatedThe data of one tenant alonetenants.isolation = "dedicated", named by tenants.db_name

The storage layer resolves a tenant ID to its database. Code never chooses a database itself, and filters by tenant_id in every query regardless of which database it lands in.

How a request finds its data​

No part of the chain depends on a value the client provides beyond the session and the resource ID: the tenant comes from the membership row, and the role with it.

Conventions​

ConventionRule
IDsULID: 26 characters, sortable by creation time. IDs identify; they are not secrets
SecretsRandom tokens (sessions, links, codes) are generated separately from IDs and stored only as hashes
TimestampsUTC. created_at and updated_at on most documents
Soft deletedeleted_at marks a removed document; a purge date says when it is destroyed
ExpiryShort-lived documents carry expires_at and are removed automatically by a TTL index
EmailStored in lower case

Identity​

users — accounts​

FieldTypeMeaning
_idstringUser ID
emailstringLower case; unique
email_verifiedboolThe address has been confirmed
password_hashstringArgon2id hash; absent for accounts that only sign in with a provider
oauth_onlyboolSigned up with Google or Apple and never set a password
first_name, last_namestringDisplay name
username, username_lcstringOptional handle and its lower-case form
bio, avatar_blob_id, languagestringProfile
personal_tenant_idstringThe user's own tenant → tenants._id
statusstringactive · blocked · archived · pending_deletion · registration_incomplete
status_changed_atdateWhen status last changed
delete_afterdateWhen an account in pending_deletion is removed
deleted_emailstringThe original address of a deleted account, after it has been released
mfaobjectTwo-factor authentication — see below
oautharrayLinked sign-in providers — see below
credentials_changed_at, credentials_versiondate, intIncremented when the password or the second factor changes; invalidates sign-in steps started before the change
email_notificationsboolEmail notification preference
phoneobjectOptional phone number
onboardingobjectProduct tours seen, survey state
referral_code, referred_bystringReferral program
last_seen_atdateLast activity
app_idstringSet on the bot account of an installed app; such an account has no password and no session
support_accountboolMarks the in-app support contact
created_at, updated_atdate

mfa

FieldMeaning
enabledTwo-factor authentication is on
enforced_by_orgAn organization the user belongs to requires it
totp_secretAuthenticator seed, encrypted (AES-256-GCM)
totp_enabled_atWhen the authenticator was set up
recovery_hashesRecovery codes, as keyed digests; a used code is removed

oauth[]

FieldMeaning
providergoogle or apple
subjectThe provider's identifier for the person
emailThe address the provider reported
linked_atWhen the link was made
sign_inThe link may be used to sign in
refresh_token, client_idProvider token, encrypted, kept where the provider requires it for revocation

Indexes: unique email · unique referral_code (when set) · unique username_lc (when set) · unique (oauth.provider, oauth.subject) (when set) · (status, delete_after).

sessions — signed-in devices​

FieldTypeMeaning
_idstringSession ID
user_idstring→ users._id
token_hashstringSHA-256 of the session token. The token itself is never stored
deviceobjectname, os, browser, ua — shown in the list of devices
ipstringAddress at sign-in
current_tenant_idstringReserved
created_at, last_used_atdate
expires_atdateIdle expiry, extended on use
revoked_at, revoked_reasondate, stringSet when the session is ended
reauth_atdateLast re-authentication, required for sensitive actions
pushobjectMobile push registration
cookie_vintCookie format version

Indexes: unique token_hash · (user_id, revoked_at) · TTL on expires_at · unique push.token (when set).

FieldMeaning
_id, user_id
kindverify · reset · email_change · email_undo
token_hashSHA-256 of the token in the link
addressThe address concerned, for an email change
dataKind-specific payload
triesSubmissions that reached the check, for reset links
expires_at, used_at, created_at

Indexes: unique token_hash · TTL on expires_at · address (when set).

otp_codes — one-time codes​

FieldMeaning
_id, user_id
actionWhat the code authorizes (sign-in, email change, data export, …). A code is valid for one action only
code_hashKeyed digest of the six-digit code, bound to the user and the action
attemptsWrong attempts so far
expires_at, used_at, created_at

Indexes: (user_id, action, created_at) · TTL on expires_at.

login_events — sign-in history​

FieldMeaning
_id, user_id, email
ip, uaAddress and client
resultok · bad_password · not_found · locked · blocked · mfa_pending · superseded
created_at

Indexes: (user_id, created_at) · attempts on unknown addresses expire after 30 days.


Tenants and organizations​

tenants — the unit of ownership​

FieldTypeMeaning
_idstringTenant ID — the value of tenant_id everywhere else
kindstringpersonal or org
namestringOrganization name
identstringUnique short identifier (when set)
owner_idstring→ users._id. The owner is always at the top of the organization ladder
isolationstringpool or dedicated
db_namestringDatabase name, for a dedicated tenant
planobjectThe limits in force — see below
usageobjectstorage_bytes, seats_used
quota_statestringnormal · read_only · hard_locked
over_seatsboolMore members than seats
grace_untildateEnd of the grace period before a read-only tenant is locked
directoryobjectvisibility (all · nobody) and info (all · name_only): what plain members see of each other
securityobjectmfa_required_admins, mfa_required_all
filesobjectcross_workspace_move, cross_org_move: who may move content across workspaces and organizations
trialobjectcampaign, plan_code, ends_at, ended
flagsobjectPer-tenant feature switches
created_at, updated_at, deleted_atdate

plan — the limits in force, stored on the tenant itself.

FieldMeaning
codefree · team · business · self_hosted
storage_bytesStorage limit; 0 means unlimited
seatsNumber of members
max_internal, max_externalNumber of internal and external workspaces; 0 means unlimited
ext_guestsGuests allowed per external workspace
ext_membersOutside members: 0 none, -1 allowed with approval
meeting_max_minMaximum meeting length in minutes; 0 means unlimited
version_history_daysHow long file versions are kept
teams, move_policies, audit, api, ssoFeatures included
sourceWhere the plan comes from: stripe · trial · partner · manual · free

Indexes: unique ident (when set) · owner_id · isolation.

org_members — who belongs to which organization​

FieldTypeMeaning
tenant_idstring→ tenants._id
user_idstring→ users._id
levelstringmember · org_view · org_manage · org_security · org_admin · owner
statusstringactive · blocked · archived. Only an active membership grants anything
status_changed_atdate
departmentsarrayIDs of the teams the member belongs to
invited_bystring→ users._id
created_by_orgboolThe account was created by the organization
created_atdate

Indexes: unique (tenant_id, user_id) · user_id · (tenant_id, status).

A person can have rows in several organizations. The owner of a tenant holds the owner level by virtue of tenants.owner_id, even without a row.

org_departures — when a person left​

One row per (tenant_id, user_id), recording when the person last left the organization or was removed from it. The clean-up of what they held inside the organization relies on it: only someone who really was a member is swept, and only of what they held before that moment.

Index: unique (tenant_id, user_id).

subscriptions — billing state​

One document per tenant, with _id equal to the tenant ID: a mirror of the payment provider's subscription.

FieldMeaning
_idTenant ID
user_idThe buyer — the owner
stripe_customer_id, stripe_subscription_idProvider references
plan_code, cyclePlan and billing cycle (month · year)
statusactive · past_due · canceled_pending_end · unpaid · canceled
current_period_end, cancel_at_period_end
pending_changeA plan change scheduled for the end of the period
past_due_since, last_event_at, reconciled_at, updated_at

No card or bank data is stored by Drumee: payment details stay with the payment provider.


Workspace membership​

workspace_members — who has which role in which workspace​

FieldTypeMeaning
tenant_idstringThe tenant that owns the workspace — not the member's own tenant
workspace_idstring→ workspaces._id, in that tenant's data
user_idstring→ users._id
rolestringviewer · chatter · editor · admin · owner
added_by, added_atstring, date
autoboolJoined automatically through the workspace's visibility or a team, rather than by hand
role_setboolThe role of an automatic member was changed by hand; a later change of the workspace's default role leaves it alone
locked, unlocked_atbool, dateThe row is kept but gives no access, because the tenant's plan no longer covers shared internal workspaces; access returns when the plan does
chat_sincedateWhen the member's role last rose to Chatter or above; realtime replay of the workspace's conversations starts there for them
appboolThe member is the bot account of an installed app

Indexes: unique (tenant_id, workspace_id, user_id) · (user_id, tenant_id) · workspace_id.

This collection is what makes external collaboration possible: the row sits in the directory, names the owning tenant, and so lets a person from anywhere hold a role in a workspace without belonging to its organization.

The owner of a workspace is defined by workspaces.owner_id; the owner also has a member row with the role owner. A member row alone never makes someone the owner.

workspace_role_caps​

One row per (workspace_id, user_id): the role a person held by hand when their membership ended. It serves as a ceiling if their membership is later re-created automatically.

Index: unique (workspace_id, user_id).

invitations — invitations to a workspace​

FieldMeaning
_id, tenant_id, workspace_id, workspace_name
emailThe invited address. Only the account with this verified address can accept
roleThe role offered: viewer · chatter · editor · admin
statuspending · accepted · declined · cancelled · expired
inviter_id, inviter_name, message
code_hashSHA-256 of the code in the invitation link
invitee_user_id, answered_by, answered_at
created_at, expires_atAn invitation is valid for 7 days

Indexes: unique code_hash · (workspace_id, email, status) · (email, status).

An invitation is re-validated when it is accepted: the inviter must still be allowed to invite, and the plan must still have room.

org_invitations — invitations to an organization​

Same shape, with tenant_id, tenant_name, the organization level offered and optional team_ids in place of the workspace and role.

Indexes: unique code_hash · (tenant_id, status) · (email, status).


People and conversations across tenants​

contacts, contact_requests, contact_blocks​

A personal address book. A contact belongs to its owner_id and may point at another account (user_id) or be a plain entry with emails, phones, address, tags and a note. Requests carry from_user_id, to_user_id or to_email, a status and an expiry. A block is a pair (blocker_id, blocked_id).

Indexes: unique (owner_id, user_id) · unique (blocker_id, blocked_id).

dm_conversations, dm_messages, dm_read_cursors​

Direct conversations between two people, who may belong to different organizations — which is why they live in the directory rather than in a tenant.

CollectionKey fields
dm_conversationskind (direct · support), participants, pair_key (unique per pair), last_message, last_message_at
dm_messagesconversation_id, sender_id, client_id, content, attachments, mentions, reply_to, reactions, deleted_at, created_at
dm_read_cursors(conversation_id, user_id) → last_read_message_id

dm_messages has a unique index on (conversation_id, client_id): sending the same message twice stores it once.

Workspace conversations use the same document shapes but are stored with the tenant's data.

notifications, user_prefs​

CollectionKey fields
notificationsuser_id, tenant_id (the organization it comes from), type, group, title_key and params (translated on the client), actor, target, count (similar notifications are merged), read_at, bookmarked_at, expires_at
user_prefsOne document per user: pinned workspaces, muted items, seen markers

Notifications expire after 90 days.

calls​

The log of direct audio and video calls: caller_id, callee_id, kind, status, ended_reason, answered_at, ended_at, duration_ms.


Other global collections​

CollectionPurpose
checkout_sessions, billing_customers, stripe_events, promo_codes, trial_claims, upgrade_hintsBilling: checkouts in progress, provider customers, processed provider events (so that each is applied once), promotions and trials
gdrive_links, gdrive_importsA user's linked Google Drive account (tokens encrypted) and the state of import jobs
data_exportsAccount data exports; at most one active export per user
transfer_requestsRequests to move content across workspaces or organizations that need an approval
content_reportsAbuse reports; kept for one year
apps, app_installations, app_user_grants, app_webhook_deliveriesThe app platform: registered apps, where they are installed, user authorizations, webhook delivery log
metrics_events, surveysOnboarding metrics and survey answers

Tenant data​

For completeness, the collections that hold a tenant's own data. Every document carries tenant_id, and indexes start with it.

CollectionHolds
workspacesname, kind (personal · internal · external), owner_id, root_node_id, visibility (all · teams · private), team_ids, default_role, deleted_at, purge_after
departmentsThe organization's teams: name, position
nodes, blobs, node_versions, upload_sessionsThe file tree and its content references → File Storage
office_snapshots, office_segmentsThe edit history of co-edited documents
share_links, share_grants, share_access_logsShare links, approved access requests, access log
conversations, messages, topics, read_cursorsWorkspace, topic and file conversations
tasks, task_columns, task_sprints, task_epics, task_labels, task_comments, task_activities, task_watchesTask boards
meetings, rooms, meeting_guest_linksCalendar, meeting rooms and guest links
audit_logsactor_id, action, target_kind, target_id, workspace_id, meta, request_id, at; kept for one year

The access hierarchy​

Putting the directory together, the rights of a person are read at three levels:

LevelStored inDecides
TenanttenantsWhat the plan allows, and whether the tenant accepts writes
Organizationorg_members.levelAdministration: members, teams, policies, audit, billing
Workspaceworkspace_members.roleEverything inside one workspace

How these values are turned into a decision is described in RBAC System.