# User & Employee System Code Inventory

**Last Updated:** December 2025
**Purpose:** Complete inventory of code that touches user/employee data

---

## Summary

| Category | Files | Queries | Migration Complexity |
|----------|-------|---------|---------------------|
| User Models & Auth | 8 | ~40 | HIGH |
| Employee Management | 12 | ~60 | HIGH |
| User-Employee Linking | 6 | ~20 | MEDIUM |
| Workbook/Daybook | 8 | ~15 | LOW |
| Statistics & Reports | 5 | ~10 | MEDIUM |
| External Integrations | 6 | ~25 | HIGH |
| API Endpoints | 10 | ~30 | MEDIUM |
| **TOTAL** | **55+** | **200+** | |

---

## 1. User System Files

### Core Models

| File | Purpose | Key Methods | Complexity |
|------|---------|-------------|------------|
| `userfrosting/models/mysql/MySqlUser.php` | User ORM model | `verifyPassword()`, `checkAccess()`, `checkStoreGroup()`, `getGroups()`, `store()`, `delete()` | HIGH |
| `userfrosting/models/mysql/MySqlUserLoader.php` | User factory | `fetch()`, `fetchAll()`, `exists()`, `generateActivationToken()` | MEDIUM |
| `userfrosting/models/mysql/MySqlGroup.php` | Group model | `getUsers()`, `store()` | LOW |
| `userfrosting/models/mysql/MySqlAuthLoader.php` | Auth loader | `fetchUserAuthHook()`, `fetchGroupAuthHook()` | LOW |

### Authentication

| File | Purpose | Key Methods | Complexity |
|------|---------|-------------|------------|
| `userfrosting/src/BuyerKiosk/Core/Controllers/AccountController.php` | Login/logout | `login()`, `logout()`, `register()`, `forgotPassword()`, `resetPassword()` | HIGH |
| `userfrosting/middleware/UserSession.php` | Session management | Session init, RememberMe validation | MEDIUM |
| `userfrosting/auth/Authentication.php` | Password utilities | `hashPassword()`, `getPasswordHashType()` | LOW |
| `userfrosting/lib/NoCSRF.php` | CSRF protection | `generate()`, `check()` | LOW |

### User Management

| File | Purpose | Key Methods | Complexity |
|------|---------|-------------|------------|
| `userfrosting/src/BuyerKiosk/Core/Controllers/UserController.php` | User CRUD | `pageUsers()`, `pageEmployees()`, `createUser()`, `updateUser()` | MEDIUM |

---

## 2. Employee System Files

### Models

| File | Purpose | Key Methods | Complexity |
|------|---------|-------------|------------|
| `userfrosting/src/BuyerKiosk/Employee/Employee.php` | Employee entity | `fromRow()`, `toArray()`, `getFullName()`, `isOnLeave()` | LOW |
| `userfrosting/src/BuyerKiosk/Core/Employee.php` | Legacy employee | Basic CRUD | LOW (deprecated) |

### Managers

| File | Purpose | Key Methods | Complexity |
|------|---------|-------------|------------|
| `userfrosting/src/BuyerKiosk/Employee/EmployeeManager.php` | Facade | Routes to providers | MEDIUM |
| `userfrosting/src/BuyerKiosk/Employee/HomegrownProvider.php` | Manual CRUD | `getActiveEmployees()`, `createEmployee()`, `updateEmployee()` | MEDIUM |
| `userfrosting/src/BuyerKiosk/Employee/WhenIWorkProvider.php` | WhenIWork sync | `syncFromProvider()`, `createFromWhenIWork()` | HIGH |
| `userfrosting/src/BuyerKiosk/Employee/HomebaseProvider.php` | Homebase sync | Stub implementation | MEDIUM |

### Controllers

| File | Purpose | Key Methods | Complexity |
|------|---------|-------------|------------|
| `userfrosting/src/BuyerKiosk/Core/Controllers/EmployeeApiController.php` | Employee REST API | CRUD endpoints, sync, PIN, photo | MEDIUM |

### Routes

| File | Purpose | Endpoints |
|------|---------|-----------|
| `userfrosting/routes/employee.php` | Employee routes | `/:typeNum/api/employees/*`, `/admin/:typeNum/employees` |

---

## 3. User-Employee Linking Files

### Models

| File | Purpose | Key Methods | Complexity |
|------|---------|-------------|------------|
| `userfrosting/src/BuyerKiosk/UserEmployee/UserEmployeeLink.php` | Link entity | `fromRow()`, `toArray()` | LOW |
| `userfrosting/src/BuyerKiosk/UserEmployee/EmployeeInvitation.php` | Invitation entity | `isValid()`, `isExpired()` | LOW |

### Managers

| File | Purpose | Key Methods | Complexity |
|------|---------|-------------|------------|
| `userfrosting/src/BuyerKiosk/UserEmployee/UserEmployeeLinkManager.php` | Link management | `getLinkedEmployee()`, `createLink()`, `autoLinkByName()` | MEDIUM |
| `userfrosting/src/BuyerKiosk/UserEmployee/EmployeeInvitationManager.php` | Invitations | `createInvitation()`, `validateToken()` | MEDIUM |
| `userfrosting/src/BuyerKiosk/UserEmployee/UserEmployeePromotion.php` | Promotion | `promoteEmployee()` | MEDIUM |

### Controllers

| File | Purpose | Key Methods | Complexity |
|------|---------|-------------|------------|
| `userfrosting/src/BuyerKiosk/Core/Controllers/UserEmployeeLinkController.php` | Link API | `getAllLinks()`, `createLink()`, `removeLink()` | MEDIUM |
| `userfrosting/src/BuyerKiosk/Core/Controllers/EmployeeInvitationController.php` | Invitation API | `createInvitation()`, `completeRegistration()` | MEDIUM |

### Routes

| File | Purpose | Endpoints |
|------|---------|-----------|
| `userfrosting/routes/user-employee.php` | Linking routes | `/:typeNum/api/user-employee/*`, `/invite/*` |

---

## 4. Workbook/Daybook Files

### Time Punch

| File | Purpose | Employee Usage |
|------|---------|----------------|
| `userfrosting/src/BuyerKiosk/Workbook/Controllers/TimePunchController.php` | Clock in/out | Queries employees for PIN validation |
| `userfrosting/routes/workbook/timepunch.php` | Routes | Time punch endpoints |

### Notes & Tasks

| File | Purpose | Employee Usage |
|------|---------|----------------|
| `userfrosting/src/BuyerKiosk/Workbook/Controllers/NotesApiController.php` | Notes | Validates employeeId exists |
| `userfrosting/src/BuyerKiosk/Workbook/Controllers/WhiteboardApiController.php` | Whiteboard | Validates employeeId |
| `userfrosting/src/BuyerKiosk/Workbook/Controllers/TasksApiController.php` | Tasks | Validates employeeId |

### Schedule

| File | Purpose | Employee Usage |
|------|---------|----------------|
| `userfrosting/src/BuyerKiosk/Workbook/ScheduleManager.php` | Schedule facade | Maps externalId to employeeId |
| `userfrosting/src/BuyerKiosk/Workbook/WhenIWorkSchedule.php` | WhenIWork shifts | Joins with employees table |
| `userfrosting/routes/workbook/schedule.php` | Routes | Schedule endpoints |

---

## 5. Statistics & Reports Files

| File | Purpose | Employee Usage | Complexity |
|------|---------|----------------|------------|
| `userfrosting/src/BuyerKiosk/Core/BuyerStats.php` | Buyer performance | JOINs buyQueue with employees | MEDIUM |
| `userfrosting/src/BuyerKiosk/Core/CompletedBuys.php` | Completed buys | JOINs with employees | MEDIUM |
| `userfrosting/src/BuyerKiosk/Stats/Controllers/StatsApiController.php` | Stats API | Queries employees | MEDIUM |
| `userfrosting/src/BuyerKiosk/DailyReport/EmailReport.php` | Daily emails | JOINs uf_user with groups | MEDIUM |

---

## 6. External Integration Files

### WhenIWork

| File | Purpose | Complexity |
|------|---------|------------|
| `userfrosting/src/BuyerKiosk/WhenIWork/Controllers/EmployeesController.php` | WhenIWork employees | MEDIUM |
| `userfrosting/routes/groups/wiw.php` | WhenIWork routes | LOW |

### DRS

| File | Purpose | Complexity |
|------|---------|------------|
| `userfrosting/routes/groups/drs.php` | DRS integration | LOW |

### Mobile API

| File | Purpose | Complexity |
|------|---------|------------|
| `userfrosting/src/BuyerKiosk/MobileApi/Controllers/MobileApiController.php` | Mobile app API | MEDIUM |
| `userfrosting/routes/groups/mobile.php` | Mobile routes | LOW |

---

## 7. Buy Queue Files

| File | Purpose | Employee Usage |
|------|---------|----------------|
| `userfrosting/src/BuyerKiosk/Core/BuyQueue.php` | Queue item | Looks up buyer/sorter names from employees |

---

## 8. Database Queries by Table

### `uf_user` Table

| Location | Query Type | Purpose |
|----------|------------|---------|
| `MySqlUserLoader::fetch()` | SELECT | Load user by ID or username |
| `MySqlUserLoader::fetchAll()` | SELECT | Load all users |
| `MySqlUser::store()` | INSERT/UPDATE | Save user |
| `MySqlUser::delete()` | DELETE | Remove user |
| `AccountController::login()` | SELECT | Find user for login |
| `UserController::pageUsers()` | SELECT | List users |

### `uf_group_user` Table

| Location | Query Type | Purpose |
|----------|------------|---------|
| `MySqlUser::fetchGroups()` | SELECT | Get user's groups |
| `MySqlUser::store()` | INSERT/DELETE | Update group membership |
| `MySqlGroup::getUsers()` | SELECT | Get group members |

### `employees` Table

| Location | Query Type | Purpose |
|----------|------------|---------|
| `HomegrownProvider::getActiveEmployees()` | SELECT | List active employees |
| `HomegrownProvider::getEmployee()` | SELECT | Single employee |
| `HomegrownProvider::createEmployee()` | INSERT | Create employee |
| `HomegrownProvider::updateEmployee()` | UPDATE | Update employee |
| `HomegrownProvider::deactivateEmployee()` | UPDATE | Soft delete |
| `WhenIWorkProvider::syncFromProvider()` | SELECT/INSERT/UPDATE | Sync from WhenIWork |
| `TimePunchController::getEmployees()` | SELECT | Clock-eligible employees |
| `BuyerStats::getBuyerStats()` | SELECT (JOIN) | Performance stats |
| `ScheduleManager::mapExternalToEmployee()` | SELECT | externalId lookup |

### `user_employee_links` Table

| Location | Query Type | Purpose |
|----------|------------|---------|
| `UserEmployeeLinkManager::getLinkedEmployee()` | SELECT | Get employee for user |
| `UserEmployeeLinkManager::getLinkedUser()` | SELECT | Get user for employee |
| `UserEmployeeLinkManager::createLink()` | INSERT | Create link |
| `UserEmployeeLinkManager::removeLink()` | DELETE | Remove link |
| `UserEmployeeLinkManager::autoLinkByName()` | SELECT/INSERT | Auto-link |

---

## 9. Migration Impact by File

### HIGH Impact (Core System Changes)

| File | Reason |
|------|--------|
| `MySqlUser.php` | Core user model - complete rewrite |
| `MySqlUserLoader.php` | User loading - complete rewrite |
| `AccountController.php` | Authentication - significant changes |
| `WhenIWorkProvider.php` | Sync logic - rewrite for unified table |
| `HomebaseProvider.php` | Sync logic - rewrite for unified table |
| `UserEmployeeLinkManager.php` | Replace with store assignments |

### MEDIUM Impact (Query Updates)

| File | Reason |
|------|--------|
| `EmployeeManager.php` | Update to use unified table |
| `HomegrownProvider.php` | Update queries |
| `EmployeeApiController.php` | Update API responses |
| `UserController.php` | Update user management |
| `TimePunchController.php` | Update employee queries |
| `BuyerStats.php` | Update JOINs |
| `ScheduleManager.php` | Update employee mapping |

### LOW Impact (Minimal Changes)

| File | Reason |
|------|--------|
| `Employee.php` | Entity model - adapt to new schema |
| `UserEmployeeLink.php` | May be deprecated |
| `NotesApiController.php` | Simple validation - update table name |
| `WhiteboardApiController.php` | Simple validation |
| `TasksApiController.php` | Simple validation |

---

## 10. API Endpoint Inventory

### User Endpoints (Central)

| Method | Endpoint | Controller | Action |
|--------|----------|------------|--------|
| POST | `/account/login` | AccountController | login |
| POST | `/account/logout` | AccountController | logout |
| POST | `/account/register` | AccountController | register |
| POST | `/account/forgot-password` | AccountController | forgotPassword |
| POST | `/account/reset-password/:token` | AccountController | resetPassword |
| GET | `/api/users` | UserController | pageUsers |
| POST | `/api/users` | UserController | createUser |
| PUT | `/api/users/:id` | UserController | updateUser |

### Employee Endpoints (Per-Store)

| Method | Endpoint | Controller | Action |
|--------|----------|------------|--------|
| GET | `/:typeNum/api/employees` | EmployeeApiController | getEmployees |
| GET | `/:typeNum/api/employees/:id` | EmployeeApiController | getEmployee |
| POST | `/:typeNum/api/employees` | EmployeeApiController | createEmployee |
| PUT | `/:typeNum/api/employees/:id` | EmployeeApiController | updateEmployee |
| DELETE | `/:typeNum/api/employees/:id` | EmployeeApiController | deactivateEmployee |
| POST | `/:typeNum/api/employees/sync` | EmployeeApiController | syncEmployees |
| POST | `/:typeNum/api/employees/:id/pin` | EmployeeApiController | setEmployeePin |
| POST | `/:typeNum/api/employees/:id/photo` | EmployeeApiController | uploadPhoto |
| DELETE | `/:typeNum/api/employees/:id/photo` | EmployeeApiController | deletePhoto |

### User-Employee Link Endpoints

| Method | Endpoint | Controller | Action |
|--------|----------|------------|--------|
| GET | `/:typeNum/api/user-employee/my-employee` | UserEmployeeLinkController | getMyEmployee |
| GET | `/:typeNum/api/user-employee/links` | UserEmployeeLinkController | getAllLinks |
| GET | `/:typeNum/api/user-employee/unlinked-employees` | UserEmployeeLinkController | getUnlinkedEmployees |
| GET | `/:typeNum/api/user-employee/unlinked-users` | UserEmployeeLinkController | getUnlinkedUsers |
| POST | `/:typeNum/api/user-employee/links` | UserEmployeeLinkController | createLink |
| DELETE | `/:typeNum/api/user-employee/links/:id` | UserEmployeeLinkController | removeLink |
| POST | `/:typeNum/api/user-employee/auto-link` | UserEmployeeLinkController | triggerAutoLink |
| POST | `/:typeNum/api/employees/:id/promote` | UserEmployeeLinkController | promoteEmployee |

### Invitation Endpoints

| Method | Endpoint | Controller | Action |
|--------|----------|------------|--------|
| GET | `/:typeNum/api/employee-invitations` | EmployeeInvitationController | getPending |
| POST | `/:typeNum/api/employee-invitations` | EmployeeInvitationController | createInvitation |
| POST | `/:typeNum/api/employee-invitations/:id/resend` | EmployeeInvitationController | resendInvitation |
| DELETE | `/:typeNum/api/employee-invitations/:id` | EmployeeInvitationController | revokeInvitation |
| GET | `/invite/:token` | EmployeeInvitationController | showInvitationPage |
| POST | `/invite/:token` | EmployeeInvitationController | completeRegistration |

---

## 11. Database Migrations

### Existing Migrations

| File | Purpose |
|------|---------|
| `20250301_010_employee_schema_upgrade.json` | Employee table enhancements |
| `20250301_011_employee_sync_log.json` | Sync audit log |
| `20250301_012_stores_employee_config.json` | Store employee source config |
| `20250302_001_user_employee_links.json` | User-employee linking table |
| `20250302_002_employee_invitations.json` | Invitation table |
| `20250302_003_employees_has_user_account.json` | hasUserAccount flag |
| `20251201_001_employee_clock_pin.json` | clockPin column |
| `20251201_001_employee_avatar_override.json` | avatarOverride column |

### Required Migrations (Unified System)

| Migration | Purpose |
|-----------|---------|
| Create `users` table | Unified user/employee table |
| Create `user_store_assignments` | Store-specific data |
| Create `user_groups` | Replace uf_group_user |
| Create `user_permissions` | Replace uf_authorize_user |
| Create `oauth_refresh_tokens` | New auth system |
| Create `user_sessions` | Session management |
| Create `auth_audit_log` | Security logging |
| Create `user_sync_log` | Centralized sync log |
| Create compatibility views | Backward compatibility |
| Data migration scripts | Move data to new tables |

---

## Related Documentation

- [User & Employee Architecture](./user-employee-architecture.md)
- [Authentication Architecture](./authentication-architecture.md)
- [Security Vulnerabilities](./security-vulnerabilities.md)
- [Unified Users Specification](../specs/unified-users-modern-auth-spec.md)