OPD Token Allocation Engine

Problem Understanding

The goal is to design a backend service for a hospital OPD that manages doctor slots and token allocation. The core challenge is handling real-world variability such as emergencies, cancellations, and delays, while enforcing capacity limits. The system needs to be elastic (handling overflow) and fair (prioritizing urgent cases).

Architecture Overview

The solution is built using Java Spring Boot 3.x following a domain-driven, layered architecture. This ensures separation of concerns and testability.

Tech Stack

• Language: Java 17+
• Framework: Spring Boot (Web)
• Build Tool: Maven
• Testing: JUnit 5 (Infrastructure ready)
• Data Persistence: In-Memory (ConcurrentHashMap for thread safety in simulation)

Key Components

• Controller Layer (com.medoc.opd.controller)
  • Handles HTTP requests and response mapping.
  • Design Choice: Clean RESTful endpoints with proper status codes (200, 404, etc.).
• Service Layer (com.medoc.opd.service)
  • Encapsulates business logic (Allocation, Elasticity, Reallocation).
  • Design Choice: AllocationService acts as the brain, orchestrating Slot and Token interactions.
• Model Layer (com.medoc.opd.model)
  • Rich Domain Models (Doctor, Slot, Token).
  • Design Choice: Logic for availability and waitlist promotion resides in the Domain models (DDD), preventing anemic models.

Token Prioritization Logic

The system uses a weighted priority score to order the waitlist:

1. Emergency (Score: 100): Bypasses waitlist completely. Directly allocated to slot (Elastic Capacity).
2. Paid Priority (Score: 50): High priority in waitlist.
3. Follow-up (Score: 30): Medium priority.
4. Online/Walk-in (Score: 10): Standard priority (First-In-First-Out within their user group).

Waitlists are automatically sorted using Comparable<Token> based on this score.

API List

Detailed specification available in api-docs/api-spec.md

Method	Endpoint	Description
POST	/api/doctors	Create a new doctor and default schedule
GET	/api/doctors	Get all doctors and their slots
POST	/api/bookings	Book a token (Elastic allocation)
DELETE	/api/bookings/{docId}/{tokenId}	Cancel a token
POST	/api/doctors/{id}/delay	Report a delay (shifts schedule)

Edge Cases Handled

1. Slot Full: Standard patients are added to a Waitlist.
2. Emergency Overflow: Emergency tokens are always accepted, even if optimal capacity is reached (Capacity grows dynamically, e.g., 5 -> 6).
3. Cancellation: If a booked patient cancels, the system automatically promotes the highest-priority patient from the waitlist to the allocated set.
4. Delay: If a doctor reports a delay, all future slots are time-shifted to maintain the schedule structure.
5. VIP Jumping: A high-priority patient added to a full slot will jump ahead of existing standard patients in the waitlist.

Simulation Explanation

The application includes a SimulationRunner that executes on startup to demonstrate functionality without needing manual API calls. Location: simulation/opd_day_simulation.txt

1. Phase 1: Fills a slot with standard patients until waitlist triggers.
2. Phase 2: Adds a PAID_PRIORITY patient (verifying they take top waitlist spot) and an EMERGENCY patient (verifying they bypass the limit).
3. Phase 3: Cancels a booked patient, verifying that the VIP patient is promoted.
4. Phase 4: Simulates a delay, shifting slot timings.

Assumptions & Trade-offs

• Slots are Fixed: Slots are generated as 1-hour blocks (9-10, 10-11).
• In-Memory Volatility: Restarting the application resets all data.
• Single Doctor Mapping: Tokens are booked for a specific doctor, not a pool.

Production Considerations (Maturity Check)

1. Concurrency: Currently uses in-memory lists. In production, I would use Database Row-Locking (Pessimistic Write) or Redis Distributed Locks to prevent double-booking slots during high concurrency.
2. Scalability: The current stateful memory model doesn't scale horizontally. Ideally, state should be externalized to PostgreSQL or Redis.
3. Security: No Auth implemented. In production, we'd add OAuth2/JWT via Spring Security.

How to Run

mvn spring-boot:run