System requirements:

Functional:

• The system should have a convenient and simple user interface.
• The users can swap their shifts with colleagues according to the schedule
• The users can get the history of their successful shift swap.
• The user uses the client application, in which the user can swap shifts with other employees and view the history of previous shift swaps.
• The users have 2 roles: employee and manager. A manager should approve the employee shift swap.
• The shift swap is a multi-step process: employees agree on the shift swap, and their managers should approve it as well.
• The system resolves the conflict if a few employees want to swap the same shift simultaneously.
• The users should be notified in the client application if the shift swap is completed or canceled.

Non-Functional:

• The system guarantees compliance with labor laws and fairness measures to prevent favoritism and unequal shift distribution.
• The system stores the shift history for one year.
• The users can see only the other shifts approved by a manager.
• The system should be reliable and available even under high load.
• The user can make a shift swap up to one week in advance.
• If the client application loses the connection to the backend, the client retries the last operation.
• The client application works on mobile and platforms.

API design

1. Authentication & User Service

2. Shift Management Service

3. Shift Swap Service

4. Notification Service (WebSocket + REST)

5. Enhanced Error Handling

6. Rate Limiting Headers

High-level design

The system is built around a microservices architecture to ensure separation of concerns, independent scalability, and resilience. Communication between services is a mix of synchronous (HTTP/REST, WebSocket) and asynchronous (Kafka) patterns.

1. Load Balancer and API Gateway (LB/AG)

Improvements:

• Clearly separates the concerns of a Load Balancer (infrastructure) and an API Gateway (application logic).
• Adds critical security and routing features.
• API Gateway:
  • Single Entry Point: Acts as a reverse proxy to route requests from web and mobile clients to the appropriate backend services (UserService, ShiftMatchingService, etc.).
  • Authentication: Intercepts requests and validates JWT tokens with the Authentication Service. Unauthenticated requests are rejected immediately.
  • Rate Limiting: Protects backend services from abuse and DDoS by limiting the number of requests per user/IP.
  • Request/Response Transformation: Can tailor responses for different clients (e.g., mobile vs. web).
  • TLS Termination: Handles SSL decryption, offloading this work from the internal services.
• Load Balancer (sitting in front of the API Gateway instances):
  • Traffic Distribution: Distributes client traffic across multiple, stateless instances of the API Gateway to ensure high availability and scalability.
  • Health Checks: Monitors the health of API Gateway instances and stops routing traffic to unhealthy ones.

2. Services (Refined and Clarified)

A. User & Authentication Service

• Responsibilities:
  • POST /register: Register new employees.
  • POST /login: Authenticate users (e.g., with username/password). Upon success, it generates and returns a signed JWT. The JWT should contain claims like user_id, role (e.g., employee, manager), and permissions.
  • POST /logout (Optional): Invalidate the JWT on the server-side if using a blacklist (stored in Redis).

B. Employee Shift Service (Source of Truth for Shifts)

• Responsibilities:
  • GET /shifts/{id}: Get a specific shift.
  • GET /employees/{id}/shifts: Get an employee's shift schedule, including the last 100 swaps (as per the original requirement).
  • Kafka Consumer: Listens for SHIFT_SWAP_APPROVED events from the Shift Matching Service and permanently updates the shift ownership in the PostgreSQL database. This service is the ultimate authority on "who is working when."
• Data Persistence (PostgreSQL):
  • users table: id, name, email, role, etc.
  • shifts table: id, employee_id (foreign key), start_time, end_time, status (SCHEDULED, IN_PROGRESS, CANCELED).
  • shift_swaps_history table: A log of all completed swaps for audit and display purposes.

C. Shift Matching Service (The Swap Orchestrator)

This is the most complex service. Its logic is refined for clarity and robustness.

• Responsibilities:
  1. GET /swap/options: Provides a list of potential shifts an employee can swap for.
     • How it works: It calls the Employee Shift Service to get the current user's upcoming shifts. Then, it finds all other SCHEDULED shifts from other employees that do not cause scheduling conflicts (e.g., overlapping shifts). The simple "Hungarian algorithm" mention is replaced with a more practical conflict-detection query in the database. Results can be cached in Redis for a short period to reduce load.
  2. POST /swap/request: Initiates a swap request.
     • Payload: { "my_shift_id": "123", "requested_shift_id": "456" }
     • Logic:
       • Acquires a Redis Lock using my_shift_id and requested_shift_id as part of the key. This prevents race conditions for the same shifts.
       • Checks if both shifts are still SCHEDULED and available.
       • Creates a new Swap Proposal in the database with status PENDING.
       • Releases the lock.
       • Sends a notification to the owner of the requested shift (employee_456).
  3. POST /swap/{id}/approve: Allows an employee to accept a swap proposed to them.
     • Changes the Swap Proposal status to ACCEPTED_BY_EMPLOYEE.
     • Sends a notification to the relevant Manager for final approval.
  4. POST /swap/{id}/manager-approve: Manager gives final approval.
     • Changes the Swap Proposal status to APPROVED.
     • Produces a Kafka event: SHIFT_SWAP_APPROVED containing the details of the swap (the two shift IDs and the two employee IDs).
     • The Employee Shift Service consumes this event and updates the shift ownership.
  5. POST /swap/{id}/cancel: Allows either involved employee or a manager to cancel a swap at any state (PENDING, ACCEPTED_BY_EMPLOYEE). Status becomes CANCELED.
• Data Persistence: This service has its own database (or schema) to manage the swap lifecycle, separate from the core shift data.
  • swap_proposals table: id, requesting_employee_id, requesting_shift_id, receiving_employee_id, receiving_shift_id, status, created_at.

D. Notification Service

• Responsibilities:
  • Kafka Consumer: Listens for events like SWAP_REQUESTED, SWAP_ACCEPTED, SWAP_APPROVED, SWAP_CANCELED.
  • Multi-Channel Dispatcher: Based on user preference and event type, it sends notifications via:
    • WebSocket: For real-time updates in the client application. The service maintains a connection map (user_id -> WebSocket session).
    • Email/SMS: Using external SMTP/SMS providers (e.g., SendGrid, Twilio) for offline users. These are queued and retried upon failure.
  • The service is designed to be highly available and resilient, ensuring no notification is lost.

3. Client Application (Enhanced Strategy)

• Real-Time Updates: Instead of long-polling, the client establishes a WebSocket connection to the Notification Service via the API Gateway. This is more efficient and provides instant push notifications for swap status changes.
• Optimistic UI: When a user initiates a swap, the UI can immediately show the state as "Pending," improving perceived performance.
• Retry Logic with Exponential Backoff: For all API calls, implement robust retry logic with exponential backoff and jitter to handle temporary network failures gracefully.
• Connection Health Checks: The client periodically pings the server to ensure the WebSocket connection is alive and automatically reconnects if it drops.

4. Data & Messaging Layer

• Kafka:
  • Event Streaming Backbone: Serves as a durable log of all critical business events.
  • Key Topics:
    • shift_swap_requests
    • shift_swap_approvals (consumed by the Employee Shift Service)
    • notification_events (consumed by the Notification Service)
  • Benefits: Provides decoupling, allows for replayability of events, and enables future addition of new services (e.g., an Analytics Service) without modifying existing ones.
• Redis:
  • Caching: Caches frequently accessed but rarely updated data, like an employee's list of potential swap options (with a short TTL of e.g., 1 minute).
  • Distributed Locking: Used by the Shift Matching Service to prevent race conditions during swap creation and approval, ensuring data consistency. The lock key is typically lock:shift:{shift_id}.
  • Session Store (Optional): Can be used to store JWT blacklists if needed.
• PostgreSQL:
  • Source of Truth: Stores all persistent data for Users, Shifts, and Swap Proposals. Chosen for its ACID compliance, which is crucial for financial and scheduling data integrity.

This improved design is more robust, scalable, and clearly defines the data flow and responsibilities of each component.

Detailed component design

1. API Gateway & Service Mesh

Improvements:

• Intelligent Routing: Uses employee_id for consistent hashing to ensure same-user requests route to same service instances
• Circuit Breaker Pattern: Implements failure thresholds to prevent cascading failures
• Request Deduplication: For retried requests from mobile clients
• JWT Validation: Offloads authentication verification from backend services

2. Employee Shift Matching Service (Redesigned)

Critical Fixes:

• Removed Hungarian Algorithm for real-time recommendations (impractical at scale)
• Added Practical Matching Logic based on business rules
• Improved State Management with proper persistence

3. Realistic Shift Swap Flow with State Management

State Transitions:

4. Enhanced Conflict Resolution

5. Redis Cluster Design

Redis Data Structure:

6. Client Application Resilience

7. Enhanced Notification Service

8. Realistic Autoscaling Configuration

9. External Service Integration with Circuit Breaker

Database design

Realistic Capacity Estimation

Storage Requirements Breakdown

Users Table:

• 1,000 employees + 100 managers = 1,100 users
• Per row: ~500 bytes
• Total: 1,100 × 500 = 550 KB

Shifts Table:

• Each employee: 5 shifts/week × 52 weeks = 260 shifts/year
• 1,100 users × 260 shifts = 286,000 shifts/year
• Per row: ~300 bytes
• Total: 286,000 × 300 = 85.8 MB/year

Swap Proposals Table:

• 10% of shifts have swap attempts: 28,600 proposals/year
• Per row: ~400 bytes
• Total: 28,600 × 400 = 11.4 MB/year

Swap History Table:

• 30% of proposals succeed: 8,580 completed swaps/year
• Per row: ~350 bytes
• Total: 8,580 × 350 = 3 MB/year

Notifications Table:

• 5 notifications per swap proposal: 143,000 notifications/year
• Per row: ~600 bytes (including message text)
• Total: 143,000 × 600 = 85.8 MB/year

5-Year Projection with Growth:

• Year 1: 187 MB
• Year 2: 374 MB (15% growth: 215 MB)
• Year 3: 589 MB (15% growth: 247 MB)
• Year 4: 836 MB (15% growth: 284 MB)
• Year 5: 1,120 MB (15% growth: 327 MB)

Total after 5 years: ~3.2 GB (including indexes and overhead)

Critical Performance Optimizations

Partitioning Strategy

Essential Indexes

Request flows

Trade offs/Tech choices

Choose to share one swap matrix between all the Employee shift matching service instances, whereas it's better to create a structure to partition that by shift_id between the

Employee shift matching service instances.

Need to invent the mechanism to restore the last swap shift information from the client application if the Employee shift matching service is down and loses the information, now it ignores that moment.

Failure scenarios/bottlenecks

The system would be deployed to AWS EKS and the service container would be orchestrated by Kubernetes.

If client applications request the swap history information frequently it gives the high load to Postgres and it may be cached.

If many employees would request changes of the swap shift intensively, it causes the race condition in Redis, so it's better to shard this process.

Future improvements

What are some future improvements you would make? How would you mitigate the failure scenario(s) you described above?

we improve this service in future by spending time on choose other object store.