feat(freight:backoffice): added org structure managemnet

orgstructure.md

@@ -0,0 +1,142 @@
+# 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`