Tenancy and Organization Model
Purpose
Section titled “Purpose”This document defines the initial tenancy model.
The platform must support multiple customers and flexible nested customer structures without assuming that every customer uses the same hierarchy.
Key Concepts
Section titled “Key Concepts”Tenant
Section titled “Tenant”A tenant is a hard security and data isolation boundary.
Examples:
- A direct customer.
- A customer environment.
- A legally or operationally separate data boundary.
Tenant data must not leak into another tenant.
Organization Unit
Section titled “Organization Unit”An organization unit is a flexible hierarchical structure inside a tenant.
Examples:
- Customer group.
- Sub-customer.
- Region.
- Branch.
- Store.
- Building.
- Site.
- Department.
- Warehouse.
- Custom grouping.
Not every tenant has the same structure.
Example structures:
- Tenant A -> McDonalds -> Store 1
- Tenant A -> SPAR Österreich -> Region East -> Branch 123
- Tenant B -> Lagerhalle 1 -> Sensor group
- Tenant C -> Direct devices without deeper hierarchy
Design Decision
Section titled “Design Decision”Use tenants for hard isolation.
Use organization units for flexible nested business structure.
Do not model every hierarchy level as a separate tenant unless a hard security boundary is required.
Access Model
Section titled “Access Model”A user may have access to:
- A whole tenant.
- One organization unit.
- Multiple organization units.
- A subtree below an organization unit.
Sub-customers and organization units must not see each other unless the user has explicit access.
Initial Roles
Section titled “Initial Roles”platform_admin
Section titled “platform_admin”Can administer the entire platform.
tenant_admin
Section titled “tenant_admin”Can administer one tenant.
org_admin
Section titled “org_admin”Can administer an assigned organization unit and optionally its subtree.
viewer
Section titled “viewer”Can view assigned data and request exports, but cannot administer users or devices unless explicitly allowed.
Device Assignment
Section titled “Device Assignment”Devices may be associated with one or more organization units.
The implementation must preserve historical correctness when devices move between organizations or tenants.
Tenant Isolation Rules
Section titled “Tenant Isolation Rules”Tenant scope must be explicit in:
- API routes.
- Repository methods.
- SQL queries.
- Internal events.
- Export jobs.
- Audit logs.
- Authorization checks.
Cross-tenant access is a security defect.
Open Decisions
Section titled “Open Decisions”- Final role permission matrix.
- Whether organization unit access is always subtree-based or can be individually scoped.
- Whether devices can belong to multiple organization units in V1 or whether this is prepared for later.
- How historical assignments are represented.