Permission Hierarchy (Fixed Backbone + Flex Tree)

MSK Core Concept — Permission Hierarchy

This page explains the "Permission Hierarchy" (Concept 1) among Multi-SaaS Kit's 6 core concepts.

Multi-SaaS Kit's permission system has three layers — a fixed backbone (separate tables) + a flex tree (organizations, unlimited depth) + a leaf (Member). The single source of truth for this decision is ADR-058.

One-line representation

Platform > SaaS > Tenant > [ Org ... Org ] > Member
└──────── fixed backbone ────────┘ └ flex tree ┘ └ leaf ┘

Level	Name	Layer	Stored in
0	Platform Admin	fixed backbone	(no FK — global)
1	SaaS Admin	fixed backbone	saas_products
2	Tenant Admin	fixed backbone	tenants
3	Organization Admin	flex tree	organizations (org_level=3)
4	Workspace Admin	flex tree	organizations (org_level=4)
5	Group Leader	flex tree	organizations (org_level=5)
6	Member	leaf	users.organization_id → leaf node

1. Fixed Backbone

The top three levels are a fixed structure, each with its own table.

• Level 0 Platform — platform-global. Not tied to a specific tenant/SaaS.
• Level 1 SaaS — saas_products. Product identity (pricing plan, feature flags, default theme, brand).
• Level 2 Tenant — tenants. Customer organization = data isolation (RLS) boundary.

These three levels are always preserved regardless of multi-SaaS usage. (Even in a 1 project = 1 SaaS deployment, one saas_products row exists — ADR-029.)

2. Flex Tree

Levels 3–5 are not separate tables; they are a self-referencing tree in the single organizations table.

Column	Role
parent_id	self reference (parent org)
path	Materialized Path (e.g. /1/3/7)
depth	0, 1, 2, … unlimited
org_level	3–5 recommended label (any integer allowed; no behavioral effect)
type	headquarters / branch / department / team, etc. (free)

• Unlimited tree depth — arbitrary depth via the Materialized Path pattern.
• Free mid-node insertion — inserting a parent/child org into an existing tree is cheap.
• Nodes with the same org_level may exist at multiple depths in the tree.

3. Leaf

• Level 6 Member — users.organization_id points to a leaf node of the tree.

⭐ users.level (fixed 0–6) vs tree depth (unlimited) — independent concepts

The most common misconception is to read the system as a "fixed 7-level tree". Precisely:

• The 0–6 classification of users.level is fixed (used by permission checks like hasLevelAtLeast()).
• The actual operational org tree depth is unlimited, and org_level is merely a recommended label attached to a node.
• That is, "permission classification (7 kinds)" and "org tree depth" are two independent concepts. What grows without limit is the number/depth of org nodes, not the number of permission Levels.

Minimal operating scenarios

Scenario	Structure	users.organization_id	Suitable domain
Simple SaaS	Platform > SaaS > Tenant > Member	NULL	B2C, personal
Standard SaaS (recommended default)	Platform > SaaS > Tenant > Org₁ > Member	Org₁.id	general B2B
Complex org	Platform > SaaS > Tenant > Org₁ > Org₂ > … > Member	leaf node id	enterprise/group

A new project's (make create) default seed creates 5 demo accounts at Levels 0/1/2/3/6. Level 4 (Workspace) and 5 (Group) nodes are added by the operator when the org tree is expanded.

Code/schema SSOT & related docs

• Design decisions: ADR-058 (fixed backbone + flex tree), ADR-009 (Active Levels)
• Schema: database/migrations/*_create_organizations_table.php (parent_id/path/depth/org_level/type)
• Related architecture: Permission System overview, Multi-tenancy, Data Isolation, Site Operating Model