# Scheduling System — Future Improvement Ideas Ideas brainstormed during the keyholder/position refactor (April 2026). These are enhancements that don't fit naturally into the current implementation but would add significant value. --- ## My Schedule — Employee-Facing View A simplified view for non-manager employees showing just their own schedule: - Their shifts with position and time - Who's the opener/closer (their "boss" for the day) - Who else is working and in what positions - Tasks assigned to their shifts Mostly a filtered/reformatted version of existing calendar data. Could be a dedicated page, a simplified calendar mode, or a panel in the Team app. **Value**: Employees currently see the full manager calendar which is information overload. This gives them just what they need to know. --- ## Shift Swap with Position Validation When two employees want to swap shifts, validate that both are trained in the required positions before allowing the swap. Check `employeeSchedulePositions` for both employees against both shifts' `positionId`. **Value**: Prevents invalid swaps that would leave unqualified people in positions. Nearly free once position matching is enforced. **Prerequisite**: Position matching enforcement (part of keyholder refactor). --- ## Copy Position Assignments from Another Employee When onboarding a new hire in a similar role, let the manager pick an existing employee and copy their position training assignments. "Train like Sarah" with one click instead of manually checking position boxes. **Value**: Small feature, saves real time during onboarding. Especially useful for stores with many custom positions. --- ## Position Coverage Summary At the top of the weekly calendar view, show filled vs. unfilled shift counts by position: ``` Buyers: 12/14 shifts | Cashiers: 8/10 | Backstock: 0/3 ``` Makes understaffing visible at a glance without scanning every shift block. Builds on data already queried for the calendar. **Value**: Managers can quickly see where they're short without mental math. --- ## Keyholder Availability Warnings When building a schedule for a future week, warn if any day has no keyholder with availability set (based on `scheduleAvailability` + `scheduleTimeOffRequests`). Catches "nobody can open next Thursday" before the AI scheduler even runs. **Value**: Proactive problem detection. Currently you'd only find out when the AI scheduler fails to fill the opener shift. --- ## Shift Handoff Notes Let the closing keyholder leave a brief note for the opening keyholder of the next day. Examples: - "Register 3 is short $20" - "Plumber coming at 9am" - "New hire starts tomorrow, show them the backstock system" Implementation: text field on shifts with `isCloser` flag. The next day's opener sees it in the Day Brief panel. **Value**: High operational value for minimal implementation cost. Replaces sticky notes and group texts. --- ## Smart Position Recommendations When the AI scheduler reports "No employees trained in [Position]", offer a one-click action to see which employees could be cross-trained based on their existing positions. For example, if nobody is trained in "Backstock" but 3 cashiers have been working for 6+ months, suggest them as cross-training candidates. **Value**: Closes the loop between "we have a gap" and "here's how to fix it." --- ## Schedule Publishing Notifications When a manager publishes the schedule for the week, automatically notify employees of their shifts via the notification system (push notification in Team app, optional SMS). Include their shifts, position, and who's opening/closing. **Value**: Employees don't have to check the app to know their schedule. Reduces "I didn't know I was working Tuesday" incidents. --- # Gap Analysis — April 2026 A pass comparing the scheduling module against WhenIWork / Homebase / Deputy / 7shifts. Items already covered earlier in this doc ("My Schedule", "Shift Handoff Notes", "Schedule Publishing Notifications") are skipped here. Grouped by value / customer demand. ## Tier 1 — Competitive gaps These are features competitors charge for and customers expect. Biggest retention and acquisition wins. ### PTO Accrual Ledger Currently we record time-off *requests* but not balances. No answer to "how many vacation days does Sarah have left?" Needs: - Accrual policy model (hours/year, accrual rate, carryover rules, probation period). - Balance ledger per employee (time-off requests debit; accrual job credits). - Nightly or per-pay-period accrual job. - UI: balances on the request form (employee sees remaining before submitting) and manager approval view. **Value**: Table stakes for any payroll-adjacent product. Very visible on the employee-facing side — once an employee sees a PTO balance, they feel the tool works for them, not just the employer. --- ### Calendar Sync (iCal feed per employee) Each employee gets a personal `webcal://` URL they add to Google / Apple / Outlook. Their calendar auto-pulls shift changes. Needs: - Endpoint serving `text/calendar` (`.ics`) content, authenticated by a per-user token (stable URL, rotatable). - One `VEVENT` per shift with summary, start/end, location. - UI: "Subscribe to my schedule" button on the employee page that reveals/copies the URL. **Value**: Employees who see their shifts in their personal calendar no-show less. Small feature, big retention win — maybe ~4 hours of work. --- ### Attendance Pattern Reports The raw data is already in `scheduleTimePunches` / `scheduleShiftAudit`. What's missing is aggregation. Report examples: - Who's been late (clock-in > N minutes after shift start) more than X times this month. - No-show rate by employee / position / day of week. - Called-out-on-Friday frequency. - Clock-out-early frequency. Surface as a Manager Dashboard panel + a dedicated report page. **Value**: Managers ask for this constantly. Currently they're scrolling through shift history manually. --- ### Payroll Export Presets `TimesheetExporter.php` already does generic CSV. Missing: named preset formats that match common payroll providers' import specs. Presets to add: QuickBooks Payroll, Gusto, ADP Run, Paychex Flex. Each is a column mapping (employee id format, hours breakdown, OT column expectations, pay period delimiters). **Value**: Removes the biggest manual step in customers' weekly flow. A franchise operator who's pasting hours into QuickBooks every Monday will remember you for this. --- ### Shift Trading Marketplace Currently only 1:1 swap (A ↔ B). A marketplace surface — "here are shifts up for grabs, any qualified employee can claim" — is a different UX. Needs: - New shift status: `offered_for_trade` (distinct from `open`). - Employees can post their own shift to the marketplace; other employees can claim (subject to position qualification + availability check). - Manager approval gate (optional, per policy). Extends existing `ShiftSwapService` rather than replacing it. **Value**: Reduces manager approval load. Employees resolve scheduling problems among themselves. --- ## Tier 2 — Compliance These unlock specific markets. Not having them means customers in those markets can't adopt the product. ### Minor / Underage Work-Hour Compliance No `dateOfBirth` (or equivalent) on the employee model. Can't enforce: - Max hours per day for under-18 (varies by state; typically 8h school day / 40h non-school). - Must-end-by time (often 10 PM school nights). - Required breaks for minors. Implementation: add age/DOB field → birthday-aware rule layer that plugs into `OvertimeCalculator`'s architecture. Block (or warn) on shift creation that would violate. **Value**: Any customer in a state with meaningful child-labor enforcement (most of them) is currently legally exposed using our product. --- ### Fair Workweek / Predictive Scheduling Laws Covered metros/states: NYC, Seattle, San Francisco, Philadelphia, Chicago, Oregon, Los Angeles (pending). Core rules vary but generally include: - 14-day advance schedule notice. - Predictability pay if the schedule is changed inside the notice window. - Right-to-rest: minimum gap between closing and opening shifts (commonly 10 hours). - "Clopening" disclosure and consent. - Good-faith estimate of hours at hire. `OvertimeCalculator`'s jurisdiction-rule engine is the right precedent — layer a Fair Workweek rule engine on top with the same pattern. **Value**: Without this, we can't sell to retailers/restaurants in those metros. Covers a lot of the country's population. --- ### Meal / Rest Break Law Enforcement We *track* breaks on `TimePunch` but don't *enforce*. California (the stickiest example): 30-min unpaid meal after 5 hours, second meal after 10 hours, 10-min paid rest every 4 hours, penalty pay if missed. Needs: - Per-jurisdiction meal/rest rules. - Shift-creation warnings (e.g., "this 8-hour shift needs a meal break"). - Time-punch validation (warn if an employee clocks out without a recorded meal break). - Penalty-pay calculator for missed breaks (California, Colorado, others). **Value**: High risk for any CA customer. Meal-break penalty pay lawsuits are common. --- ### Employee "Exempt" (Salaried) Flag Feedback item #19 from the original client list. No way to mark someone as OT-exempt → salaried managers accumulate bogus overtime hours in reports. Needs: - `isExempt` (or `exemptFrom: ['overtime','breaks']`) on the employee model. - `OvertimeCalculator` short-circuits calculation for exempt employees. - Reports and payroll exports respect the flag. Small scope, but it's a trust-breaker when it's missing. --- ## Tier 3 — UX wins Smaller features; mostly retention / satisfaction plays. ### Recurring Availability Exceptions `AvailabilityException` is currently single-date-only. Common use cases that need a recurrence rule: - "Unavailable every Wednesday in December." - "Night class every Tuesday, Jan–May." - "Can't work weekends this month." Reuse the `RecurrenceService` machinery that already exists for shifts. --- ### Split Shifts Support No explicit support for one employee with two shifts the same day (e.g., 7–11 AM and 5–9 PM). Shift records are independent, but some features may not treat them as one workday: - Overtime calculation: should both count toward the daily threshold? - Conflict detection: does it flag the gap as "available" or recognize the employee as working? - Meal-break rules: need a total-hours-per-day view. Audit these paths. If they break on split shifts, add the "same-day shifts" concept (explicit grouping, not just coincidence of date). --- ### Employee Max-Hours Cap Enforcement Config already exists (`maxHoursPerWeek` referenced in `MobileClockService`), but it's not enforced at shift creation. Add a check with a warning (not a hard block — managers need to override sometimes). --- ## Partial → Finish Features that are plumbed but not completed. ### Overtime Prevention Warnings at Shift-Create Time `OvertimeCalculator` can tell you that a proposed shift would push someone into overtime. The shift-create flow doesn't call it. Hook it up; return a warning object in the create-shift response and surface in the create modal ("Adding this shift puts Sarah at 46h this week"). --- ### Demand Forecasting `OverlayDataService` loads sales data and wait-time heat maps for the visual overlay. The next step — convert that into a "recommended headcount per hour" suggestion — isn't built. The AI subsystem is the right home for this. Could surface as a ghost layer on the timeline: "based on last 4 weeks, you typically want 3 buyers and 2 cashiers at this hour." --- ### External Provider Sync Decision The codebase has references to WhenIWork / Homebase (`externalProviderManualPunchFallbackEnabled` config, `WhenIWorkSchedule` format mentions) but no active pull/sync. Decision needed: - Commit to being the *integration target* (customers migrate *to* us) — remove the external references and clean up. - Commit to pulling *from* those systems (let customers keep existing tools and we layer on top) — this is a real project: OAuth, shift/user sync, conflict resolution. Either is fine; the ambiguity isn't. --- ## Recommended next three If I had to pick: **PTO accrual**, **calendar sync**, and **meal/rest break enforcement** — in that order. First two retain employees, third unlocks California customers. The Exempt flag (#19) is small and already on the backlog — knock it out alongside.