commit

docs/adr/ADR-001-user-employee-domain-boundary.md

@@ -0,0 +1,100 @@
+# ADR-001: User-Employee Domain Boundary
+
+## Status
+
+Accepted
+
+## Context
+
+The application already uses `users` for authentication and permissions, while training, reporting, and HR master data still rely on `employees`. The repo also has two linkage seams:
+
+- `users.employeeId`
+- `user_employee_maps`
+
+Phase 1 remediation needs a stable, documented boundary before more invasive schema work begins.
+
+## Problem
+
+Without an explicit boundary, new work can:
+
+- create dual source-of-truth behavior
+- put audit actors on `employees`
+- put training ownership on `users`
+- expand both linking strategies at the same time
+
+## Definitions
+
+- `users`: authenticated system identity
+- `employees`: HR-owned worker profile
+
+## Decision
+
+Adopt this boundary for the current remediation phase:
+
+- `users` own authentication, login identity, session context, permissions, organization membership, notifications, and audit actor fields.
+- `employees` own employee code, employee profile, department/position assignment, training ownership, training targets, matrix applicability, and compliance reporting subject.
+
+## Data Ownership
+
+| Data | Owner |
+|---|---|
+| login email, username, password, account status | `users` |
+| active organization, membership, permissions | `users` + membership tables |
+| audit actor, created by, approved by, published by | `users` |
+| employee code, employee name, company, department, position, employment status | `employees` |
+| training owner, target, matrix applicability, compliance subject | `employees` |
+
+## Relationship Cardinality
+
+Canonical relationship during remediation:
+
+- `User 0..1 <-> 0..1 Employee`
+
+This supports:
+
+- super admins or service identities without employee records
+- employees that exist before a user account is provisioned
+
+## Linking Strategy
+
+Short term:
+
+- preserve both current compatibility seams
+- treat `user_employee_maps` as the explicit linkage record
+- treat `users.employeeId` as a compatibility pointer that must stay synchronized
+
+## Mapping Strategy
+
+- New query logic should prefer explicit linkage semantics and document fallback behavior.
+- New features must not introduce additional user-employee link columns or tables.
+
+## Non-Employee User Handling
+
+Allowed. A user may authenticate and operate without an employee profile when their work is administrative or service-oriented.
+
+## Employee Without User Handling
+
+Allowed. Employee master data may exist before a user account is provisioned.
+
+## Migration Strategy
+
+1. Inventory all current user/employee joins and ownership assumptions.
+2. Standardize docs and runtime guards around the split boundary.
+3. Add automated checks for route and guard drift.
+4. Reconcile the dual-linking seam in a later schema-focused slice with backfill and verification.
+
+## Compatibility Strategy
+
+- Keep `users.employeeId` readable during the transition.
+- Keep `user_employee_maps` operational until reconciliation is complete.
+- Do not expand either seam without a follow-up ADR.
+
+## Consequences
+
+- Documentation now matches the current transitional implementation more honestly.
+- Training and reporting code may continue using `employees` as owner scope for now.
+- Future migration work must explicitly retire one linking seam instead of letting both continue to grow.
+
+## Rollback Strategy
+
+Rollback is documentation-only for this ADR. Runtime rollback is not required unless a later schema migration changes persisted data.