Departments across the organisation

[garden-ai-dev]

PR Summary

Introduces first-class Departments support across the organisation, allowing workspaces, projects, issues, agents, and members to be grouped under departments. This enables access control, cost allocation, reporting, and cross-department collaboration at scale without creating siloed workspaces for every team.

Problem Statement

Today, Garden is organised around workspaces and projects. As an organisation grows, this flat model breaks down in several ways:

• No team boundary inside a workspace. A single workspace containing multiple teams (Engineering, Design, Product, Operations) mixes all issues, agents, and contexts together. Filtering becomes the only way to focus.
• Permission granularity is coarse. You can invite someone to a workspace, but you cannot limit them to a particular department or set of projects.
• Reporting and billing lack team dimensions. It is impossible to attribute agent usage, connector spend, storage, or compute to a specific department or business unit.
• Cross-department collaboration is fragile. Members jump between workspaces to collaborate, which fragments context and makes it hard to trace decisions back to a common origin.
• Default workspace routing issues. Returning users sometimes land in a different workspace than expected because there is no stable team-level anchor to restore.

Goals and Non-Goals

Goals

• Create a Department entity scoped to an organisation.
• Allow workspaces, projects, issues, agents, documents, and members to belong to one or more departments.
• Provide department-aware permissions: viewer, member, lead, admin.
• Surface department context in search, chat, issue boards, billing dashboards, and workspace switchers.
• Support a default department per user/workspace pair so routing is deterministic.

Non-Goals

• Replacing workspaces with departments. Workspaces remain the primary collaboration boundary; departments add a grouping layer above or across them.
• Reimplementing an enterprise LDAP/SCIM directory. We will integrate, not rebuild.
• Full multi-tenant isolation. Departments share an organisation; isolation is permission-based, not infrastructure-based.

Proposed Solution

Add a departments table and a polymorphic departmentables join table. Expose departments through a dedicated settings area, a department selector in the workspace header, department badges on issues/agents/docs, and department filters on search and issue boards.

Departments are created at organisation level and mapped into workspaces. A workspace member can see only the departments they are assigned to unless they hold an organisation-level or workspace-level admin role. Department leads can manage membership and approve connector/agent provisioning within a budget.

Detailed Design

Data Model

departments

Column	Type	Notes
id	uuid	Primary key
organisation_id	uuid	FK to organisations
slug	text	Unique within organisation
name	text	Display name
colour	text	Hex colour for badges
budget_credits	integer	Optional monthly budget
settings	jsonb	Notification defaults, approvals
created_at / updated_at	timestamp	Audit fields

department_members

Column	Type	Notes
department_id	uuid	FK to departments
user_id	uuid	FK to users
role	enum	viewer, member, lead, admin
added_by	uuid	FK to users
joined_at	timestamp	Audit

departmentables

Column	Type	Notes
department_id	uuid	FK to departments
entity_id	uuid	Polymorphic target
entity_type	text	workspace, project, issue, agent, document, connector
added_by	uuid	FK to users
added_at	timestamp	Audit

Entities can belong to multiple departments. The UI will treat the first department as primary for badge display unless overridden.

API Surface

Organisation-scoped

• GET /orgs/:org/departments — list departments the caller can see.
• POST /orgs/:org/departments — create a department (org admin).
• PATCH /orgs/:org/departments/:id — update department metadata.
• DELETE /orgs/:org/departments/:id — archive department.

Department-scoped

• GET /departments/:id — department details and members.
• POST /departments/:id/members — invite/add member.
• PATCH /departments/:id/members/:user_id — change role.
• DELETE /departments/:id/members/:user_id — remove member.
• GET /departments/:id/entities — list linked workspaces, projects, issues, agents, docs.

Entity-scoped

• POST /workspaces/:id/departments — link workspace to department.
• DELETE /workspaces/:id/departments/:dept_id — unlink.
• Same pattern for projects, issues, agents, documents, and connectors.

All endpoints respect the permission matrix defined below.

Permission Matrix

Role	View Department	Edit Members	Assign Entities	Spend Budget	Delete Department
Org Owner	Yes	Yes	Yes	Yes	Yes
Org Admin	Yes	Yes	Yes	Yes	No*
Department Admin	Yes	Yes	Yes	Yes	No
Department Lead	Yes	Yes	Yes	Within budget	No
Department Member	Yes	No	No	No	No
Department Viewer	Yes	No	No	No	No

*Soft-delete only; hard delete reserved for org owner.

Frontend Changes

1. Workspace switcher / header. Show department badge next to workspace name. Add a department dropdown to filter boards and search by department.
2. Settings. New "Departments" section under organisation settings. Lists departments, members, budgets, and linked connectors.
3. Issue board and chat. Add department badge and filter. Department members can be mentioned with @dept-name as a shorthand to notify all members.
4. Create flows. Creating a project, issue, agent, or document offers an optional department picker pre-filled with the user's default department.
5. Search. dept:engineering query operator plus a search filter chip.
6. Billing dashboard. Group usage and cost by department with CSV export.

Migration and Backwards Compatibility

• Introduce tables as additive-only.
• Existing workspaces and entities remain without a department (NULL is allowed).
• Organisation owners see a one-time onboarding prompt inviting them to create their first department and import workspace members.
• Feature is gated behind an org_has_departments flag so it can be rolled out organisation by organisation.
• API responses include a departments array; clients that ignore it continue to work.

Testing Strategy

• Unit: permission helper tests for every matrix cell.
• Integration: CRUD endpoints, member role transitions, entity linking/unlinking.
• E2E: create department, assign issue, filter board, mention department from chat, export billing CSV.
• Regression: ensure workspaces without departments behave exactly as before.
• Performance: list endpoints are paginated; add composite indexes on departmentables(department_id, entity_type) and department_members(department_id, user_id).

Risks and Mitigations

Risk	Mitigation
Departments become a second workspace people duplicate	Onboarding clearly explains departments are labels/groups, not containers
Permission conflicts between workspace and department roles	Department grant never reduces workspace access; effective permission is union
UI clutter from too many badges	Show primary department; collapse overflow behind a "+N" chip
Budget enforcement is bypassed by workspace admins	Credit checks are centralised; department budget constraints are applied at billing time

Acceptance Criteria

• Organisation admins can create, edit, and archive departments.
• Members can be assigned to a department with viewer/member/lead/admin roles.
• Workspaces, projects, issues, agents, documents, and connectors can be linked to one or more departments.
• Department badge appears in the workspace header, issue board, chat, and search results.
• Users can filter issue boards and search by department.
• Department members can be mentioned from chat and receive notifications.
• Billing dashboard can group usage by department and export to CSV.
• Users without department access cannot see entities restricted to that department.
• Existing workspaces without departments remain unaffected.

Related Work

• FLO-15 — Tag workspace members from chat.
• FLO-14 — Workspace routing restoration on re-entry.
• FLO-8 — Chat interface on issue board.
• FLO-10 — Enable GitHub connector.

PR Checklist

• PR description is complete.
• Migrations are additive and reversible.
• New endpoints have integration tests.
• Frontend changes have visual tests or storybook entries.
• Documentation updated (user guide and API reference).
• Feature flag added.
• Org owner onboarding copy reviewed.

[Umoren]

garden currently treats a workspace as the company/Better Auth organisation, while the issue also describes departments spanning several workspaces. i recommend that departments live inside one workspace. i also recommend that unassigned records should remain workspace-wide, while department-assigned records are visible only to members of an assigned department, plus workspace owners/admins.