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

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.