Workspace Groups vs Knowledge Base Groups

This document describes the two-level grouping schema used by the platform: workspaces are grouped at the org level, and knowledge bases are grouped within each workspace. Historical design reference: Figma – Main structure.

1. Hierarchy

The product model uses this hierarchy:

Workspaces (root)
├── [Workspace groups] e.g. Group 1, Group 2, Ungrouped
│   ├── Workspace 1
│   ├── Workspace 2
│   └── Workspace 3 (under "Ungrouped")
│
└── Under each Workspace: [KB groups] (separate from workspace groups)
    ├── Workspace 1 → Group 1 (KB 1, KB 2), Group 2 (KB 3, KB 4)
    ├── Workspace 2 → Group 1 (KB 1, KB 2), Group 2 (KB 3, KB 4)
    └── Workspace 3 → Group 1 (KB 1), No group (KB 2)

Workspaces have their own groups. These are org-level: they organize which workspace belongs to which group (e.g. “Group 1”, “Group 2”, “Ungrouped”). There is a default group at this level (e.g. “Default group”).
Knowledge bases have their own groups. These are workspace-scoped: within each workspace, KBs are organized into groups (e.g. “Group 1”, “Group 2”, “No group”). Each workspace has its own set of KB group names.

Workspace groups and KB groups are not linked. They are separate namespaces. So a workspace group and a KB group can share the same name (e.g. “Default group” at workspace level and “Default group” as a KB group inside a workspace) — that is allowed. Uniqueness applies only within the same level: among workspace groups, names must be unique org-wide; among KB groups within a workspace, names must be unique within that workspace. You cannot use the same name for two different groups at the same level (e.g. two workspace groups cannot both be named “Default group”; two KB groups in the same workspace cannot both be named “Group 1”).

2. Workspace groups (implemented)

Aspect	Description
Scope	Organization-wide. All workspaces belong to exactly one workspace group.
Entities	`WorkspaceGroup` (id, name). `Workspace.groupId` references the group.
Uniqueness	Names must be unique among workspace groups only (org-wide, case-insensitive). Names are not shared with KB groups; e.g. “Default group” can exist as a workspace group and also as a KB group name. See Workspaces – Group names: uniqueness.
UI	Workspaces page: groups as section headers (GroupBadge); workspace open page: group badge for current workspace’s group.

Implemented in: src/types/workspaces.ts (WorkspaceGroup, Workspace.groupId), src/app/account/workspaces/_data/seed.ts, WorkspacesContext, GroupBadge, Add group / Rename / Delete group flows.

3. Knowledge base groups (partially implemented)

Aspect	Description
Scope	Per workspace. Each workspace has its own set of KB groups. A “Group 1” under Workspace 1 is independent of “Group 1” under Workspace 2 or the workspace-level “Group 1”.
Historical reference	Legacy mockups show KBs under a workspace grouped by labels such as “Group 1”, “Group 2”, “No group”. They also allow “Ungrouped” or “No group” for KBs that are not in any group.
Current app	KB groups are stored in context (`state.kbGroups`, `actions.addKbGroup`, `selectors.getKbGroupsForWorkspace`). On the workspace open page, the group badge menu’s Add group adds a KB group for this workspace; validation uses only KB group names in this workspace, so a name that exists at the workspace level (e.g. “test”) is allowed. KBs do not yet have a `groupId` — assigning KBs to KB groups is not implemented; the Add group flow creates the group only.
Future	Assign KBs to KB groups (`KnowledgeBase.groupId` or similar); show KBs grouped by KB group on the workspace open page; Rename/Delete for KB groups in the UI.

4. Namespaces and uniqueness (same level only)

Workspace groups and KB groups are not linked. The same display name (e.g. “Default group”) may be used for a workspace group and for a KB group; they are in different namespaces.
Uniqueness is per level:
- Workspace groups: No two workspace groups may have the same name (org-wide, case-insensitive).
- KB groups (when implemented): No two KB groups in the same workspace may have the same name (within that workspace). Different workspaces may each have a KB group with the same name (e.g. “Group 1” in Workspace A and “Group 1” in Workspace B).
There is a default group at the workspace level (e.g. id "default", name “Default group”). The same name is allowed for a KB group.

5. Summary

Level	Groups organize	Scope	Uniqueness	Implemented
Workspace groups	Workspaces	Org-wide	Unique among workspace groups	Yes
KB groups	Knowledge bases	Per workspace	Unique among KB groups in that workspace	Partially

Data model — Workspace and Knowledge Base entities
Default workspace and KB — Default workspace and KB rules
Workspaces route — Workspace groups UI and uniqueness