Implement simple orchestrated email notification pattern

README.md

@@ -1 +1,96 @@
-# nginx-remote-app-poc
+# Spring Boot Email Notification Pattern (Publish-Only)
+
+This project demonstrates a **boring, low-cognitive-load** notification pattern:
+
+- one orchestration flow for render + publish
+- one config catalog for YAML lookup
+- one builder per notification type for payload-to-template-model mapping
+- shared renderer and shared publisher interfaces
+
+The service **does not send email directly**. It only creates and publishes an `EmailPublicationRequest` to another delivery service.
+
+## Why this pattern keeps cognitive load low
+
+- You call a single entry point (`EmailNotificationOrchestrator.notify(...)`).
+- Shared concerns (config lookup, rendering, publishing, enabled checks) live in one place.
+- Notification-specific code stays tiny and local (just model builders + optional payload records).
+- No giant switch in domain services and no ad hoc per-notification pipelines.
+
+## Package structure
+
+```text
+src/main/java/com/example/notification
+├── NotificationApplication.java
+├── config
+│   ├── NotificationCatalog.java
+│   └── NotificationProperties.java
+├── domain
+│   └── NotificationType.java
+├── model
+│   ├── EmailPublicationRequest.java
+│   ├── HoldListCreatedPayload.java
+│   └── HoldListRemovedPayload.java
+├── orchestration
+│   ├── EmailNotificationOrchestrator.java
+│   ├── HoldListCreatedModelBuilder.java
+│   ├── HoldListRemovedModelBuilder.java
+│   └── NotificationModelBuilder.java
+├── publish
+│   ├── EmailPublicationPublisher.java
+│   └── LoggingEmailPublicationPublisher.java
+├── render
+│   ├── TemplateRenderer.java
+│   └── ThymeleafTemplateRenderer.java
+└── service
+    └── HoldListDomainService.java
+```
+
+## Runtime flow
+
+1. Domain service calls orchestrator `notify(type, payload)`.
+2. Orchestrator loads config from `NotificationCatalog`.
+3. Orchestrator resolves builder for `NotificationType`.
+4. Builder converts payload -> template model.
+5. Shared `TemplateRenderer` renders HTML.
+6. Orchestrator builds `EmailPublicationRequest`.
+7. Shared `EmailPublicationPublisher` publishes it.
+
+## Configuration example
+
+See `src/main/resources/application.yml`.
+
+## Template examples
+
+See:
+
+- `src/main/resources/templates/hold-list-created.html`
+- `src/main/resources/templates/hold-list-removed.html`
+
+## Example usage
+
+See `HoldListDomainService` for how business logic triggers notifications through one orchestrator entry point.
+
+## How to add a new notification type
+
+1. Add a new enum value in `NotificationType`.
+2. Add YAML config under `notifications.email.<TYPE>` in `application.yml`.
+3. Add template file in `resources/templates`.
+4. Add payload record (optional but recommended for type clarity).
+5. Add one `NotificationModelBuilder<T>` component for the new type.
+6. Start using `orchestrator.notify(NEW_TYPE, payload)` from domain service.
+
+No shared orchestration changes should be needed.
+
+## Focused tests
+
+- `NotificationCatalogTest`: config lookup + missing config behavior.
+- `EmailNotificationOrchestratorTest`: happy path publish, disabled behavior, payload mismatch guard.
+
+## Tradeoffs
+
+This pattern intentionally prefers explicit wiring over dynamic magic:
+
+- **Pros:** easy to trace, easy to debug, simple onboarding, low day-2 maintenance.
+- **Cons:** one small builder class per notification type (a bit more boilerplate).
+
+Given maintainability goals, this is a good trade.

pom.xml

@@ -0,0 +1,52 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.example</groupId>
+    <artifactId>notification-service-pattern</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <name>notification-service-pattern</name>
+
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.3.5</version>
+        <relativePath/>
+    </parent>
+
+    <properties>
+        <java.version>17</java.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-thymeleaf</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-configuration-processor</artifactId>
+            <optional>true</optional>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+</project>

src/main/java/com/example/notification/NotificationApplication.java

@@ -0,0 +1,15 @@
+package com.example.notification;
+
+import com.example.notification.config.NotificationProperties;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+
+@SpringBootApplication
+@EnableConfigurationProperties(NotificationProperties.class)
+public class NotificationApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(NotificationApplication.class, args);
+    }
+}

src/main/java/com/example/notification/config/NotificationCatalog.java

@@ -0,0 +1,22 @@
+package com.example.notification.config;
+
+import com.example.notification.domain.NotificationType;
+import org.springframework.stereotype.Component;
+
+@Component
+public class NotificationCatalog {
+
+    private final NotificationProperties properties;
+
+    public NotificationCatalog(NotificationProperties properties) {
+        this.properties = properties;
+    }
+
+    public NotificationProperties.NotificationDefinition getRequired(NotificationType type) {
+        NotificationProperties.NotificationDefinition definition = properties.getEmail().get(type);
+        if (definition == null) {
+            throw new IllegalArgumentException("No notification config found for type: " + type);
+        }
+        return definition;
+    }
+}

src/main/java/com/example/notification/config/NotificationProperties.java

@@ -0,0 +1,57 @@
+package com.example.notification.config;
+
+import com.example.notification.domain.NotificationType;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+import java.util.EnumMap;
+import java.util.List;
+import java.util.Map;
+
+@ConfigurationProperties(prefix = "notifications")
+public class NotificationProperties {
+
+    private final Map<NotificationType, NotificationDefinition> email = new EnumMap<>(NotificationType.class);
+
+    public Map<NotificationType, NotificationDefinition> getEmail() {
+        return email;
+    }
+
+    public static class NotificationDefinition {
+        private List<String> recipients;
+        private String templatePath;
+        private String subject;
+        private boolean enabled = true;
+
+        public List<String> getRecipients() {
+            return recipients;
+        }
+
+        public void setRecipients(List<String> recipients) {
+            this.recipients = recipients;
+        }
+
+        public String getTemplatePath() {
+            return templatePath;
+        }
+
+        public void setTemplatePath(String templatePath) {
+            this.templatePath = templatePath;
+        }
+
+        public String getSubject() {
+            return subject;
+        }
+
+        public void setSubject(String subject) {
+            this.subject = subject;
+        }
+
+        public boolean isEnabled() {
+            return enabled;
+        }
+
+        public void setEnabled(boolean enabled) {
+            this.enabled = enabled;
+        }
+    }
+}

src/main/java/com/example/notification/domain/NotificationType.java

@@ -0,0 +1,6 @@
+package com.example.notification.domain;
+
+public enum NotificationType {
+    HOLD_LIST_CREATED,
+    HOLD_LIST_REMOVED
+}

src/main/java/com/example/notification/model/EmailPublicationRequest.java

@@ -0,0 +1,10 @@
+package com.example.notification.model;
+
+import java.util.List;
+
+public record EmailPublicationRequest(
+        List<String> recipients,
+        String subject,
+        String htmlBody
+) {
+}

src/main/java/com/example/notification/model/HoldListCreatedPayload.java

@@ -0,0 +1,8 @@
+package com.example.notification.model;
+
+public record HoldListCreatedPayload(
+        String holdListId,
+        String createdBy,
+        int itemCount
+) {
+}

src/main/java/com/example/notification/model/HoldListRemovedPayload.java

@@ -0,0 +1,8 @@
+package com.example.notification.model;
+
+public record HoldListRemovedPayload(
+        String holdListId,
+        String removedBy,
+        String reason
+) {
+}

src/main/java/com/example/notification/orchestration/EmailNotificationOrchestrator.java

@@ -0,0 +1,76 @@
+package com.example.notification.orchestration;
+
+import com.example.notification.config.NotificationCatalog;
+import com.example.notification.config.NotificationProperties;
+import com.example.notification.domain.NotificationType;
+import com.example.notification.model.EmailPublicationRequest;
+import com.example.notification.publish.EmailPublicationPublisher;
+import com.example.notification.render.TemplateRenderer;
+import org.springframework.stereotype.Service;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+@Service
+public class EmailNotificationOrchestrator {
+
+    private final NotificationCatalog catalog;
+    private final TemplateRenderer templateRenderer;
+    private final EmailPublicationPublisher publisher;
+    private final Map<NotificationType, NotificationModelBuilder<?>> builders;
+
+    public EmailNotificationOrchestrator(NotificationCatalog catalog,
+                                         TemplateRenderer templateRenderer,
+                                         EmailPublicationPublisher publisher,
+                                         List<NotificationModelBuilder<?>> modelBuilders) {
+        this.catalog = catalog;
+        this.templateRenderer = templateRenderer;
+        this.publisher = publisher;
+        this.builders = indexByType(modelBuilders);
+    }
+
+    public <T> void notify(NotificationType type, T payload) {
+        NotificationProperties.NotificationDefinition definition = catalog.getRequired(type);
+        if (!definition.isEnabled()) {
+            return;
+        }
+
+        NotificationModelBuilder<T> builder = getBuilder(type, payload);
+        Map<String, Object> model = builder.buildModel(payload);
+        String htmlBody = templateRenderer.render(definition.getTemplatePath(), model);
+
+        EmailPublicationRequest request = new EmailPublicationRequest(
+                definition.getRecipients(),
+                definition.getSubject(),
+                htmlBody
+        );
+        publisher.publish(request);
+    }
+
+    private Map<NotificationType, NotificationModelBuilder<?>> indexByType(List<NotificationModelBuilder<?>> modelBuilders) {
+        Map<NotificationType, NotificationModelBuilder<?>> indexed = new HashMap<>();
+        for (NotificationModelBuilder<?> builder : modelBuilders) {
+            NotificationModelBuilder<?> previous = indexed.put(builder.supports(), builder);
+            if (previous != null) {
+                throw new IllegalStateException("Duplicate builder for type: " + builder.supports());
+            }
+        }
+        return indexed;
+    }
+
+    @SuppressWarnings("unchecked")
+    private <T> NotificationModelBuilder<T> getBuilder(NotificationType type, T payload) {
+        NotificationModelBuilder<?> candidate = builders.get(type);
+        if (candidate == null) {
+            throw new IllegalArgumentException("No model builder found for type: " + type);
+        }
+        if (!candidate.payloadType().isInstance(payload)) {
+            throw new IllegalArgumentException(
+                    "Payload type mismatch for " + type + ". Expected "
+                            + candidate.payloadType().getSimpleName() + " but got " + payload.getClass().getSimpleName()
+            );
+        }
+        return (NotificationModelBuilder<T>) candidate;
+    }
+}

src/main/java/com/example/notification/orchestration/HoldListCreatedModelBuilder.java

@@ -0,0 +1,30 @@
+package com.example.notification.orchestration;
+
+import com.example.notification.domain.NotificationType;
+import com.example.notification.model.HoldListCreatedPayload;
+import org.springframework.stereotype.Component;
+
+import java.util.Map;
+
+@Component
+public class HoldListCreatedModelBuilder implements NotificationModelBuilder<HoldListCreatedPayload> {
+
+    @Override
+    public NotificationType supports() {
+        return NotificationType.HOLD_LIST_CREATED;
+    }
+
+    @Override
+    public Class<HoldListCreatedPayload> payloadType() {
+        return HoldListCreatedPayload.class;
+    }
+
+    @Override
+    public Map<String, Object> buildModel(HoldListCreatedPayload payload) {
+        return Map.of(
+                "holdListId", payload.holdListId(),
+                "createdBy", payload.createdBy(),
+                "itemCount", payload.itemCount()
+        );
+    }
+}