Workspaces (multi-tenancy): design doc

[antiv]

Part of #178, feature 5 (a 2.0 theme). For 1.5.0, the preparation is this design doc: documents/design/workspaces.md. The schema doesn't change yet.

What the code shows

• Installation-wide today:
  • users and their global roles;
  • a yes/no administrator for the whole installation;
  • a dashboard API that is admin-only through the middleware;
  • projects without members;
  • logs without a project (usage per project goes through agent → project);
  • settings, model prices and provider keys.
• Agent names are unique across the installation, and the name is also the ADK app name. It appears in /apps/{name}, the session keys, token_usage_logs.agent_name and agent budget scopes.

Proposal

• Agent names stay unique across the installation in 2.0. Creating or importing an agent refuses a name another workspace uses. Internal names would touch URLs, sessions, logs, budgets, A2A/MCP and standalone builds for a cosmetic gain.
• New tables: workspaces, and workspace_members with the roles owner, admin and member.
• Projects get projects.workspace_id, and everything that belongs to a project follows from it.
• Log rows get workspace_id, written when the row is written (usage, guardrails, responses, audit). Costs and audit entries stay where they were recorded, even when agents move or are deleted.
• Budgets and alerts get a workspace scope, and personal access tokens are bound to one workspace.
• A default workspace holds all existing data. An installation with one workspace looks the same as today.
• The scoping is the real work:
  • one dependency gives each route its (workspace_id, role);
  • the middleware checks for an admin of the current workspace;
  • the RBAC callback checks membership first.
• A cross-workspace test walks every /dashboard/api/ route against a two-workspace fixture, so a missed filter fails CI.

Open questions:

• provider keys per workspace, which decide whether workspaces serve departments or clients;
• model prices per workspace;
• moving projects between workspaces;
• self-service sign-up;
• SSO domains per workspace.

A cheap step for after 1.5.0, useful even without workspaces: write project_id onto token_usage_logs and audit_logs.