Workspace Modules Rollout Runbook

Workspace Modules Rollout Runbook

Scope

This runbook covers rollout, verification, and rollback for workspace module gating:

• module keys: people, publications, works, projects, activity, users, import
• tables: module_catalog, workspace_modules
• migration: migrations/drizzle/0017_workspace_modules.sql

Rollout Steps

1. Deploy app code with module-aware sidebar and route guards.
2. Apply DB migration 0017_workspace_modules.sql.
3. Run static rollout verification:
   • pnpm --filter @apps/dashboard verify:workspace-modules
4. Validate in UI:
   • open admin users page
   • assign/unassign workspace modules
   • verify sidebar and direct-route behavior for disabled modules

SQL Verification

Run these checks against DB_0:

SELECT key, name, is_paid, is_active, sort_order
FROM module_catalog
ORDER BY sort_order, key;

SELECT entity_id, COUNT(*) AS module_count
FROM workspace_modules
GROUP BY entity_id
ORDER BY entity_id;

SELECT entity_id, module_key
FROM workspace_modules
ORDER BY entity_id, module_key;

Expected:

• module_catalog has the 7 canonical module keys.
• existing non-admin workspaces are backfilled with all 7 modules.

Rollback

If module rollout must be reverted quickly:

1. Revert app deployment to pre-module-gating build.
2. Optionally remove module tables if needed:

DROP TABLE IF EXISTS workspace_modules;
DROP TABLE IF EXISTS module_catalog;

3. Re-deploy pre-module build.

Note: table drop is destructive. Prefer app rollback first, then schema rollback only when required.

Operational Notes

• superadmins bypass module route guard checks.
• sidebar fallback defaults to canonical module keys when module query data is not yet loaded.
• module enforcement is server-side via route guard (requireWorkspaceModule), not only UI hiding.