Concurrency-Safe Appointment Booking API with Slot Reservation

[meshackyaro]

Description

This issue aims to address the implementation of Concurrency-Safe Appointment Booking API with Slot Reservation.

The core objective is to: Design booking endpoints that prevent double-booking under concurrent requests via database-level locking and atomic slot reservation.

By completing this feature, we will ensure that the GuildWorkman protocol maintains its high standards for security, usability, and decentralized logic. This issue requires careful attention to the Backend architecture and adherence to the existing project conventions.

When picking up this issue, please ensure you document any new dependencies or architectural decisions made during development.

Component

Backend (Spring Boot / Java 17)

Difficulty

🔴 Hard

Tasks

• Review the existing Spring Boot structure under backend-api/src/main/java
• Implement the service and REST endpoints for: Concurrency-Safe Appointment Booking API with Slot Reservation
• Expose a per-worker availability read endpoint (booked + any active reservations/holds) — viewAllAppointment currently returns only the logged-in client's own bookings, so a booking UI has no way to see a worker's taken slots
• Add or adjust JPA entities, repositories, and schema migrations as needed
• Write unit and integration tests (Spring Boot Test; MockWebServer for external RPC calls)
• Add caching for Maven dependencies in CI
• Run ./mvnw verify and ./mvnw test to validate build and coverage

Acceptance Criteria

• Feature accurately implements the objective: Design booking endpoints that prevent double-booking under concurrent requests via database-level locking and atomic slot reservation.
• A per-worker availability endpoint returns that worker's taken/held slots so a booking UI can render availability and two different visitors cannot race for the same slot
• Any PR that introduces failing tests or compilation errors is automatically blocked
• Endpoints/services are covered by tests including failure and concurrency paths
• Public API is documented (OpenAPI) and errors follow a consistent response contract
• Code is properly reviewed and approved by codeowners

Frontend context (from guildworkman-web #34)

The booking calendar in guildworkman-web#34 (which closed guildworkman-web#28) shipped client-side only slot locking (localStorage + BroadcastChannel, 5-min TTL). That stops a single visitor double-booking themselves across tabs, but cannot stop two different visitors racing for the same slot — which is exactly what this issue closes at the authoritative layer.

Two things this issue must account for so that frontend context isn't lost:

• The per-worker availability read endpoint above is the missing counterpart to viewAllAppointment — without it the calendar can't see a worker's taken/held slots.
• Once this API lands, guildworkman-web should retire its client-only lock in src/lib/slotLock.ts and treat the server as the source of truth for availability (frontend follow-up depends on this).

Estimated Time

2-3 days

[Silver36-ship-it]

I would love to work on this professionally, please assign it to me

[balisdev]

Hi, I'd like to work on this issue, enhancing concurrency-safe appointment booking api with slot reservation to prevent double-booking

[grantfox-oss]

🦊 GrantFox — @balisdev has been assigned to this issue!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #24)
2. Your PR will be reviewed by the workman-labs maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@balisdev's PR #37 was approved and merged by @meshackyaro.

🏆 @balisdev: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (662 total points). Track your full progress on GrantFox.

👏 Great work, @balisdev! Keep contributing to workman-labs.