Skip to content

CONCEPT Cited by 1 source

Workspace-scoped to org-wide migration

Workspace-scoped to org-wide migration is the specific multi-tenant re-architecture in which an enterprise SaaS product — originally designed around the assumption that a user session is scoped to one tenant (workspace, team, project, org) — consolidates into a session-scope spanning a parent container (org, enterprise) where the original tenant becomes an intra-parent sub-tenant, often reduced from a routing/scoping axis to a user-facing filter.

The canonical wiki instance is Slack's Unified Grid project (2023–2024, Source: sources/2024-08-26-slack-unified-grid-how-we-re-architected-slack-for-our-largest-customers): Slack launched in 2013 with "each user belongs to a single workspace"; Enterprise Grid (2017) added a multi-workspace org container but users still navigated per-workspace; Unified Grid (2024) boots the client with an org-wide view and demotes the workspace to a filter.

The structural shift

Before (tenant-scoped)

  • Session token carries the tenant ID (e.g. workspace ID). See concepts/session-token-embedded-routing-context.
  • Backend parses the tenant ID to route queries to the tenant's shard and perform access control.
  • Client stores data per-tenant in distinct session stores.
  • To see data on a different tenant: log into a different session.

After (org-wide)

  • Session represents the user across the entire parent container. The tenant ID is no longer a routing axis.
  • APIs that operated on "the tenant in the session" must be re-taught: three canonical strategies (see Slack's playbook below).
  • Client stores data at the parent-container level, or some data at the container level and some at the tenant level during transition.
  • The parent container is the new unit of aggregation; the tenant becomes a filter in the UI.

Why the migration becomes necessary

The assumption "one tenant per session" fits the product's first decade because early usage matches it — most users of the first wave are in one tenant. As the product grows and customers centralise on the parent container:

  • Individual users end up in many tenants within the same parent container.
  • The product accumulates aggregated views (activity across tenants, cross-tenant channels, org-level DMs) as patches on top of the per-tenant substrate.
  • The patches' cost (context-switching UX, bugs from syncing org-wide data across per-tenant stores, impossibility of loading multi-tenant data in one API call) eventually exceeds the cost of revising the foundational assumption.

Slack's explicit framing: "when the architecture of an application drifts far enough from how that application is used, prototyping a path towards rewriting the core foundation is actually the best way to achieve your goals." See also concepts/incremental-delivery — the migration pays off only if each step is shippable.

Preconditions for feasibility

The migration is only tractable when the data layer has already been decoupled from the tenant axis on the hot path. Slack's case:

  1. The Vitess migration had re-sharded the hottest tables along different axes (messages by channel ID, not workspace ID). Queries for messages could simply drop the tenant-context routing. See concepts/horizontal-sharding.
  2. The RTM (real-time messaging) stack had been reworked to stop fanning org-wide data out to every tenant on the Grid.

Without these preconditions, the re-architecture has to be bundled with the sharding migration, which multiplies blast radius.

Three canonical API-fix strategies

When every API rooted in the old tenant scope needs to be retaught:

  1. Drop tenant routing entirely if the underlying table has been re-sharded by a different key.
  2. Prompt the user to pick a tenant if the API genuinely acts on one tenant (e.g. "create a channel in which workspace?"). The tenant becomes an explicit API parameter instead of an implicit session context.
  3. Iterate over the user's tenants as a last-resort fallback. Bounded in pathological (admin) cases by a relevance cap (Slack: 50 workspaces).

Avoid a fourth strategy — cross-tenant joins in-database — because the tables were deliberately sharded per-tenant; this would be scatter-gather at the DB layer.

Any enterprise SaaS whose early design assumed one tenant per user and later needed org-wide views faces a structurally-similar migration:

  • GitHub — personal repos / per-org view → Enterprise accounts with cross-org surface.
  • Atlassian — per-site (Jira / Confluence instance) → Atlassian Cloud identity spanning sites.
  • Notion — per-workspace session → multi-workspace account surfaces.
  • Figma — per-team view → organisations with cross-team visibility.

Slack's canonicalisation is load-bearing for the wiki because it is the most mechanism-disclosed public case: the three-strategy API-fix playbook, the 50-workspace cap, the session-token-embedded-routing-context call-out, and the parallel-integration-test-suite-for-context-switch test methodology are all rare public disclosures for this class of migration.

Seen in

  • sources/2024-08-26-slack-unified-grid-how-we-re-architected-slack-for-our-largest-customers — canonical wiki instance. Slack's decade-long (2013→2024) evolution from workspace-scoped single-tenant sessions to org-wide sessions under the Unified Grid project. Load-bearing mechanism disclosures: session-token-embedded routing context as the core coupling; the three API-fix strategies; the 50-workspace relevance cap for admin long-tail fan-out; the parallel-integration-test-suite context-swap for test reuse; Unified Grid as foundational dependency for IA4 client redesign.
Last updated · 470 distilled / 1,213 read