Product Requirements Document: Shift Swap Hub

1. Executive Summary

Shift Swap Hub is a centralized platform designed to eliminate the friction and compliance risks associated with manual shift swapping in hourly work environments like retail, hospitality, and healthcare. By replacing fragmented chat-based communication with an automated marketplace and a real-time labor compliance engine, the platform reduces managerial overhead, ensures adherence to local labor laws, and empowers employees with greater schedule flexibility.

2. Problem Statement

Hourly workers and managers currently waste hours coordinating shift trades through unofficial channels (WhatsApp, SMS, Slack). This lack of centralization leads to:

Scheduling Blind Spots: Managers lose track of who is working, leading to "no-shows."
Compliance Violations: Manual swaps often result in unintended overtime or violations of mandatory rest periods (e.g., "clopenings").
Manager Burnout: High volume of manual approval requests and schedule editing.
Data Silos: Lack of audit trails for labor disputes or payroll reconciliation.

3. Goals & Success Metrics

Efficiency: Reduce the average time a manager spends on shift swap approvals by 70%.
Compliance: Maintain a 0% rate of "Hard Constraint" labor law violations.
Engagement: Achieve a Monthly Active User (MAU) rate of >80% among staff.
Reliability: Reduce "uncovered" shifts by 25% through the automated marketplace.

4. User Personas

5. User Stories

As a staff member, I want to post my assigned shift to a marketplace so that my colleagues can see and claim it.
As a staff member, I want to see shifts I’m eligible for based on my certifications so I can pick up extra hours.
As a manager, I want the system to automatically flag if a swap would trigger overtime so I can make an informed decision.
As a manager, I want to see an audit trail of who approved a change in case of a payroll discrepancy.
As a compliance officer, I want to set mandatory rest periods (e.g., 11 hours) that the system enforces automatically.

6. Functional Requirements

6.1 Shift Marketplace

Users can list assigned shifts as "Available."
Users can filter available shifts by date, location, and estimated pay.
"Shift Call-out" broadcasting for urgent needs (emergency coverage).

6.2 Labor Compliance Engine

Hard Constraints: Block swaps that violate laws (e.g., working 7 consecutive days).
Soft Constraints: Warn managers about swaps that trigger overtime or "Predictive Scheduling" penalties.
Logic: Implement "Anti-Pyramiding" logic for daily vs. weekly overtime.

6.3 Approval Workflow

Two-stage validation: Peer Acceptance -> System Compliance Check -> Manager Approval.
One-tap approval/rejection from push notifications.

6.4 Calendar & Notifications

Two-way sync with Google Calendar and Microsoft Outlook.
Real-time Push Notifications for new marketplace postings and status changes.

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

Backend: NestJS v11.1.12 (Node.js 24.x) using TypeScript 5.x.
Frontend (Web): React.js 19.x with Tailwind CSS.
Mobile: React Native v0.83.x (New Architecture/Fabric enabled).
Database: PostgreSQL v18.1 with Row-Level Security (RLS) enabled.
ORM: Prisma using Client Extensions for RLS session management.
Infrastructure: AWS ECS Fargate for compute; Amazon Aurora Serverless v2 for DB.

7.2 Key Integrations

Calendar: Nylas SDK v3 (Grants-based logic) for 2-way sync.
Outlook: Microsoft Graph API (Direct integration as EWS is decommissioned).
Notifications: Firebase Cloud Messaging (FCM) with "Live Activities" support for iOS.
Location: react-native-background-geolocation (Transistorsoft) for geofencing.

8. Data Model

8.1 Core Entities

User: uuid, organization_id, role, max_hours_per_week, certifications[].
Shift: uuid, user_id, start_time, end_time, status (ASSIGNED, MARKETPLACE, PENDING_SWAP).
SwapRequest: uuid, offered_shift_id, requesting_user_id, compliance_status, manager_id, approval_status.
ComplianceRule: uuid, org_id, min_rest_hours, max_consecutive_days, overtime_threshold_daily.
AuditLog: uuid, actor_id, action, before_state (JSON), after_state (JSON), effective_time.

9. API Specification (Key Endpoints)

10. UI/UX Requirements

Mobile First: The associate experience must be optimized for one-handed use.
Status Clarity: Use distinct color coding for shift status (Green: Confirmed, Orange: Pending Manager, Blue: In Marketplace).
Conflict Visuals: If a swap is blocked, the UI must clearly state the specific rule violated (e.g., "Violation: Less than 11 hours rest since previous shift").
Manager Dashboard: A "Calendar View" on the web dashboard with a sidebar for "Pending Approvals."

11. Non-Functional Requirements

Security: Implement PostgreSQL Row-Level Security (RLS) to ensure Organization A cannot see Organization B's data. Use SET LOCAL app.current_tenant in all Prisma transactions.
Performance: Marketplace updates must reflect via WebSockets in <200ms.
Availability: 99.9% uptime requirement; critical for 24/7 healthcare/hospitality.
Auditability: Bi-temporal data modeling to preserve the history of schedule edits for 3 years (FLSA compliance).

12. Out of Scope

Full payroll processing (will integrate via exports/API instead).
Employee performance reviews.
Hiring and onboarding workflows.

13. Risks & Mitigations

Risk: High GPS drift in indoor malls/hospitals affecting geofencing.
Mitigation: Use Wi-Fi SSID/BSSID scanning as a secondary proximity factor.
Risk: "Connection Pool Pollution" in multi-tenant RLS.
Mitigation: Use SET LOCAL within Prisma $transaction blocks to ensure tenant ID resets after every query.

14. Implementation Tasks

Phase 1: Project Setup & Core Infrastructure

[ ] Initialize NestJS 11.1.12 project with TypeScript 5.
[ ] Initialize React Native 0.83.x project with New Architecture enabled.
[ ] Set up PostgreSQL 18.1 with RLS policies and tenant_id column on all tables.
[ ] Configure AWS CDK for ECS Fargate and Aurora Serverless v2.
[ ] Implement Auth0 for Multi-Factor Authentication.

Phase 2: Compliance Engine & Backend Logic

[ ] Create IConsistencyRule interface for the labor logic engine.
[ ] Implement "Anti-Pyramiding" overtime calculator.
[ ] Build the "Look-back/Look-ahead" rest period algorithm ($T_s - T_{prev_end}$).
[ ] Set up Prisma Client Extensions for automated app.current_tenant injection.
[ ] Build Audit Logging system with JSON diffing for every shift change.

Phase 3: Marketplace & Mobile App

[ ] Implement marketplace API with real-time WebSocket updates via NestJS Gateways.
[ ] Integrate react-native-background-geolocation for site-based check-ins.
[ ] Build "Shift Claim" workflow with optimistic UI updates using React 19 useOptimistic.
[ ] Implement push notification orchestration via Courier/FCM.

Phase 4: Integrations & Final Polish

[ ] Build Microsoft Graph API connector for Outlook 2-way sync (replacing EWS).
[ ] Integrate Nylas for Google/Apple Calendar sync.
[ ] Add AI-powered reliability scoring using a Scikit-learn microservice.
[ ] Conduct load testing for high-concurrency "Shift Drops" (10k+ concurrent users).
[ ] Perform security audit on RLS boundaries and PII encryption at rest.