add third-level hierarchy within organizations

[ericpaulsen]

We have a financial services customer in EMEA requiring a third subgroup to match their internal structure. See below:

Current Coder Architecture:

Organization (top-level)
├── Custom Roles (org-scoped)
├── Provisioners (org-scoped, tags scoped to org)
└── Groups (lower level)
    ├── Users
    └── Templates

Customer's Desired State:

Organization (single, top-level)
├── Custom Roles (granular role hierarchy)
├── Provisioners (consolidated, shared across groups)
└── Groups (hierarchical, multi-level)
    ├── Subgroups (departments: Java, Python, Mainframe, etc.)
    ├── Users (inherited from parent groups)
    ├── Templates (group-specific access)
    └── Template Admin Roles (prevent cross-group manipulation)

Validation Summary

Feature	Current State	Customer's Desired State	Gap Analysis
Organization	✅ Single or multiple orgs as top-level	Single org, top-level	✅ Supported
Custom Roles	✅ Org-scoped, granular permissions	Granular role hierarchy	✅ Supported - Custom roles are org-scoped and support fine-grained permissions
Provisioners	✅ Org-scoped with tags	Consolidated, shared across groups	⚠️ Partial - Provisioners are org-scoped, not group-scoped. Can be shared within an org via tags.
Groups	⚠️ Flat structure within org	Hierarchical, multi-level with subgroups	❌ Gap - No subgroup/nested group support
Subgroups	❌ Not supported	Departments: Java, Python, Mainframe, etc.	❌ Gap - No native subgroup hierarchy
User inheritance	❌ Not supported	Users inherited from parent groups	❌ Gap - No inheritance model
Template ACL	✅ Group-based ACL (group_acl jsonb)	Group-specific access	✅ Supported - Templates have group_acl for access control
Template Admin Roles	⚠️ Partial	Prevent cross-group manipulation	⚠️ Partial - Custom roles can restrict template admin scope, but ACLs are per-template, not per-group

---

Key Gaps

1. No Subgroup/Nested Group Support

The groups table is flat with no parent_group_id or hierarchy mechanism. Groups exist at a single level within an organization.

2. No User Inheritance

Users are directly assigned to groups via group_members. There's no concept of inheriting membership from a parent group.

3. Template Admin Isolation

While templates have group_acl and user_acl for access control, preventing "cross-group manipulation" would require custom roles scoped to specific groups (not currently supported) or separate organizations per department.

---

Recommendations

Desired Feature	Workaround/Alternative
Subgroups (Java, Python, Mainframe)	Use naming conventions (e.g., dept-java, dept-python) + IDP sync to manage membership. Or use multiple organizations per department.
User inheritance	Use IDP group sync to assign users to multiple groups automatically (e.g., user in dept-java also added to all-developers group).
Template Admin isolation	Create custom roles per department with template-specific permissions. Alternatively, use separate organizations for full isolation.
Shared provisioners across groups	✅ Already works - provisioners are org-scoped and can be shared via tags.

---

Bottom Line

Current Coder supports a two-level hierarchy: Organization → Groups/Templates/Provisioners

Customer wants a three-level hierarchy: Organization → Groups → Subgroups

This third level is not natively supported. The customer would need to either:

1. Flatten their hierarchy using naming conventions and IDP sync
2. Use multiple organizations to achieve stronger isolation between departments
3. Wait for potential subgroup support