# 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`