alla-tms/docs/architecture/user-employee-domain-inventory.md

User-Employee Domain Inventory

This inventory records the current implementation state for Phase 1 remediation. It is intentionally descriptive, not aspirational.

Boundary Summary

• users owns authentication, session identity, active organization, permissions, notifications, and audit actors.
• employees owns HR master data, employee profile, training ownership, matrix targeting, and compliance subject scope.
• The current codebase still uses two linkage seams: users.employeeId and user_employee_maps.
• The effective relationship is User 0..1 <-> 0..1 Employee, but reconciliation is still needed.

Inventory

Domain	User Usage	Employee Usage	Current FK/Join	Data Owner	Issue	Required Change
Authentication and session	src/auth.ts, src/lib/auth/session.ts, src/types/next-auth.d.ts	session enrichment attaches employeeId	users.employeeId, syncUserEmployeeLink()	users for auth, employees for linked profile	login flow implicitly syncs employee linkage	document and later reconcile the linking source
User-employee linking	users.employeeId, user_employee_maps.userId	user_employee_maps.employeeId	direct FK plus mapping table	compatibility seam	dual source of truth risk	adopt a canonical linking strategy and enforce it with checks
Training records	userId, submittedByUserId, reviewedByUserId, createdBy	employeeId	mixed FK usage in training_records	split by intent	actor/owner split exists but is undocumented	preserve and codify the split
Training targets and policy	employee_training_targets.userId, creator/updater user fields	employee_training_targets.employeeId	unique indexes on user/year and employee/year	split by intent	two ownership axes coexist	document employees as canonical owner for runtime training scope
Training matrix	session actor only	compliance joins employees and trainingRecords.employeeId	training-matrix-data.ts joins	employees	feature relied on employee scope but page guard was missing	keep employee ownership and enforce page/API guard
Reports	current session user is actor	datasets scoped by employee joins	report-data.ts joins employees and training_records	employees for subject, users for actor	docs previously overstated employees as legacy-only	update architecture docs to reflect transitional reality
Overview	current session user defines access scope	KPIs and self-scope resolve through employee IDs	overview-data.ts employee joins	mixed	non-employee user handling is implicit	add explicit non-employee handling rules
Employee directory	optional user linking	employee is the primary record	employees.id, employee target APIs	employees	linkage lifecycle is not formally documented	keep employee-first workflow and document it
Audit and permission management	actor and target use users	none	audit_logs, permission_audit_logs	users	ownership is correct but undocumented as a rule	codify actor convention
Notifications	recipient uses users.userId	none	notifications.userId	users	no issue	keep user-only notification model

Confirmed Findings

• src/db/schema.ts still contains both users.employeeId and user_employee_maps.
• Training ownership is still employee-centric in training-records, training-policy, training-matrix, reports, and overview.
• Session enrichment still synchronizes user-to-employee linkage during login.
• The original audit note about /dashboard/training-matrix/new is outdated in the current repo state because src/app/dashboard/training-matrix/[matrixId]/page.tsx resolves the new segment dynamically.

Immediate Remediation Direction

1. Keep actor fields on users and owner fields on employees.
2. Standardize page guards on employee-scoped management routes.
3. Treat users.employeeId and user_employee_maps as a transition seam that must be reconciled, not expanded.
4. Add automated route and architecture checks before deeper schema migration work.