Notification Service: Persisted In-App Notifications & Email Fan-Out on Appointment Lifecycle Events #44

Description

This issue aims to address the implementation of Notification Service: Persisted In-App Notifications & Email Fan-Out on Appointment Lifecycle Events.

The core objective is to: Implement the notification service so that appointment lifecycle changes produce a persisted, readable in-app notification and a corresponding transactional email, instead of silently changing state that nobody is told about.

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

🟡 Medium

Current state

services/implmentations/NotificationServiceImpl.java is an empty @Service with no methods, and NotificationService is an empty interface — while data/models/Notification.java and NotificationRepository already exist and go unused. Meanwhile MailServiceImp can already send transactional email through Brevo.

So the pieces are on the table and simply not connected: when an appointment is booked, accepted, updated, or cancelled in AppointmentServiceImpl, neither party is notified by any channel.

Tasks

• Review the existing Spring Boot structure under backend-api/src/main/java
• Implement the service and REST endpoints for: Notification Service: Persisted In-App Notifications & Email Fan-Out on Appointment Lifecycle Events
• Define the notification methods on NotificationService and implement them against the existing Notification model and NotificationRepository
• Hook the appointment lifecycle in AppointmentServiceImpl — booked, accepted, updated, cancelled, deleted — so both the client and the worker are notified as appropriate
• Add read endpoints for a user's notifications with pagination, plus mark-as-read (single and bulk)
• Fan out to email via the existing MailService without letting a mail-provider failure roll back or block the appointment operation itself
• Send email outside the appointment's transaction boundary so a failed send never leaves a booking half-committed
• Ensure a user can only read and mark their own notifications
• Add or adjust JPA entities, repositories, and schema migrations as needed
• Write unit and integration tests (Spring Boot Test; MockWebServer for external RPC calls), including a mail-provider-down case
• 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: Implement the notification service so that appointment lifecycle changes produce a persisted, readable in-app notification and a corresponding transactional email, instead of silently changing state that nobody is told about.
• Every appointment lifecycle transition produces a persisted notification for the affected parties
• A failing or slow email provider does not fail the underlying appointment operation
• Users can list, paginate, and mark their notifications read — and cannot see anyone else's
• 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

Estimated Time

1-2 days