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