edr-platform/orgstructure.md

IAM Org Structure

Core Model

Organization

• Top-level tenant or company.
• Entity: Organization
• Has: units, positions, employees
• Supports hierarchy through parent and branches

Unit

• Organizational subdivision under an organization.
• Entity: Unit
• Belongs to organizationId
• Supports hierarchy through parentUnit and subUnits
• Has: positions, positionTypes, employees, employeePositions

Department

• In the IAM UI, a department is effectively a Position.
• There is no separate backend Department entity in this package.
• In the org tree UI:
  • Organization -> Unit -> Department ~= Position
  • Sub-department ~= subPosition

Position

• The actual backend model behind the UI's department concept.
• Entity: Position
• Belongs to: unitId, organizationId
• Supports hierarchy through parentPositionId and subPositions
• Has assigned people through employeePositions
• Can have direct permissions through positionPermission
• Also linked to a positionType

Position Type

• Template or category for positions.
• Entity: PositionType
• Example seeded concepts include things like employee, team leader, director, deputy.
• Can carry permissions through position_type_permissions

Employee

• Org-scoped representation of a person inside an organization and unit.
• Entity: Employee
• Links a User into organizationId and unitId
• Has employeePositions[] for actual assignments
• Uses isCurrent and status to indicate active records

EmployeePosition

• Assignment join between Employee and Position.
• Entity: EmployeePosition
• Holds the active working context:
  • isCurrent
  • status
  • isDelegate
  • delegatorId
  • startDate and endDate
• This is the position context the auth layer ultimately uses

User

• Global identity record.
• Entity: User
• Has login/account fields like username, email, phoneNumber
• Has:
  • userRoles[]
  • employee[]
• A single user can have multiple employee records and multiple org assignments

Role

• RBAC grouping of permissions.
• Entity: Role
• Assigned to users via UserRole
• Has permissions via RolePermission

Permission

• Atomic authorization capability.
• Entity: Permission
• Main fields include key, name, and optional applicationKey
• Can be granted through:
  1. role_permissions
  2. position_permissions
  3. position_type_permissions

Relationship Summary

1. Organization contains many Unit records.
2. Unit contains many Position records.
3. The UI calls those positions departments.
4. User is the identity.
5. Employee links that user to an organization and unit.
6. EmployeePosition links the employee to one or more positions.
7. Role is assigned directly to the user via UserRole.
8. Permission can come from the user's roles, the position itself, or the position type.

Runtime Permission Model

At login, IAM builds a session userInfo payload that includes:

• roles: from userRoles
• permissions: flattened from role permissions
• employee.positions[].permissions: combined from:
  • direct positionPermission
  • inherited positionTypePermissions

This means authorization has two practical layers:

1. User-level permissions from roles
2. Position-context permissions from the active position and its type

Active Context During Requests

The auth guard uses request headers to decide which employee position is the current working context.

Important headers include:

• x-current-position-id
• x-delegator-position-id
• x-current-project-id
• x-organization-unit-id

That selected context becomes the active request.user.employee.position and is also used for auditing.

Practical Mental Model

Use this simplified model when reasoning about IAM:

1. A User is the account.
2. An Employee is that user inside an organization.
3. A Position is the department-like slot in the org tree.
4. An EmployeePosition says which employee occupies which position.
5. A Role gives broad user-level permissions.
6. A Position and PositionType give contextual working permissions.

UI Mapping

In @tria-plc/iamui-common user management:

• Organizations -> Organization
• Units -> Unit
• Departments -> Position
• Sub-departments -> child Position
• Team members/employees -> Employee plus EmployeePosition
• Roles -> Role
• Permissions -> Permission