How rincon10/document-notification-system works
1. Repository shape
This is a multi-module Maven monorepo with three business bounded contexts: customer-service, document-service, generator-service, plus shared infrastructure libraries under common and infraestructure. Each bounded context is split into a consistent hexagonal layout: domain-core, application-service, dataaccess, messaging, and container; some also have an application-api module for REST entry points.
2. Core architectural style
The codebase is organized around Clean Architecture / Hexagonal Architecture + DDD. The inner modules hold the business model and use-case orchestration; the outer modules implement adapters for REST, JPA, Kafka, and Spring Boot bootstrapping. The dependency direction is intended to point inward only.
3. Shared foundation
The common modules provide reusable primitives across services: base entities/aggregates, domain event abstractions, shared constants, utility classes, IDs, statuses, money/value objects, and global exception handling. This is the main cross-cutting code boundary used to avoid duplicating low-level domain infrastructure.
4. Customer service boundary
customer-service is the simplest bounded context: it exposes a REST controller in customer-application-api, orchestrates commands in customer-domain/customer-application-service, persists customer data through JPA in customer-dataaccess, and publishes customer-created events through customer-messaging to Kafka. The domain core contains the Customer aggregate and CustomerCreatedEvent.
5. Document service boundary
document-service is the central orchestration service. Its domain core models documents, document items, addresses, document events, and domain exceptions. The application service coordinates document creation, listens for customer and downstream responses, and drives the document generation + notification workflow. Its dataaccess module persists document state plus two outbox tables, while its messaging module handles Kafka publishers/listeners for cross-service communication.
6. Generator service boundary
generator-service receives document generation requests, performs document/content generation in the domain layer, persists generation state, and publishes generation results back to Kafka. It also uses an outbox for reliable event publication. The generator domain includes generation status models and a content generator implementation, indicating that this service is the compute-heavy worker in the flow.
7. Notification service boundary
notification-service consumes notification requests, sends notifications via a concrete adapter (EmailNotificationSender in the container module), tracks notification state, and publishes notification results back to Kafka. It also has a data access layer and outbox support, showing it is built for reliable asynchronous delivery rather than synchronous API calls.
8. Primary runtime composition
Each service has a *-container module with the Spring Boot application entry point and bean wiring. That module composes the domain/application ports with the infrastructure adapters and also loads schema/init SQL. The container is the deployment boundary for each bounded context.
9. Messaging backbone
Kafka is the main integration mechanism between services. The infraestructure/kafka modules centralize Kafka config, producer/consumer helpers, and shared Avro schema/model definitions for message contracts. The services’ messaging modules adapt these shared Kafka primitives into service-specific publishers and listeners.
10. Reliability pattern: Outbox
The repo implements the Outbox pattern in multiple services. Document, generator, and notification each have outbox entities, repositories, schedulers, and helper classes dedicated to draining pending messages safely. This means state changes and message publication are decoupled to reduce lost/duplicate event risk in distributed flows.
11. Distributed workflow / saga
The document flow is coordinated as a saga-like process: customer data can enter document processing, document creation can trigger generation, generation results can trigger notification, and each step publishes a response event for the next participant. The shared infraestructure/saga module contains generic saga status/step abstractions, while the document application service has explicit saga classes for generation and notification orchestration.
12. Persistence model
Each service appears to use its own relational schema, likely PostgreSQL, with JPA repositories in the dataaccess modules. The document service is the richest schema: it persists document headers, items, addresses, and separate outbox records for generation and notification. This suggests clear data ownership per bounded context, with no shared database domain model.
13. External contracts
Kafka message schemas are defined in the shared kafka-model module using Avro models and schema files. This is an important architectural boundary: inter-service communication relies on versionable message contracts rather than shared Java entities. The document and generator/notification services map their domain messages to these Avro contracts in their messaging layers.
14. Operational/infrastructure layer
The infraestructure/docker-compose setup includes Kafka, Zookeeper, and init scripts, which are required to run the system locally. The repo also includes schema initialization SQL for each service, reinforcing the “service owns its data store” model. GitHub Actions and Maven CI are present for build validation.
15. What an architecture diagram should emphasize
The most important boxes are: the three bounded contexts, each split into domain/application/adapter/container layers; the Kafka event bus connecting them; the outbox schedulers inside each service for reliable publication; and the shared common + Kafka infra modules as cross-cutting libraries. The clearest data flow is: customer/document input → document service → generation service → notification service → response events back through Kafka.
Main entry points: document-application-service Document app · kafka-model Kafka model · notification-application-service Notification app · common-domain Common domain
Components 24
Shared libs
Cross-cutting domain and integration foundations used by multiple services.
- Common domain · Base entities, events, value objects, utilities, and shared domain exceptions/constants.
document-notification-system/common/common-domain - Common API · Global exception handling and shared API DTO boundary.
document-notification-system/common/common-application-api
Customer service
REST-driven customer bounded context.
- Customer API · REST controller and exception handler for customer commands.
document-notification-system/customer-service/customer-application-api - Customer app · Customer command orchestration, ports, and mapping.
document-notification-system/customer-service/customer-domain/customer-application-service - Customer core · Customer aggregate, domain service, event, and domain exception.
document-notification-system/customer-service/customer-domain/customer-domain-core - Customer data · Customer persistence adapter, entity mapping, and repository.
document-notification-system/customer-service/customer-dataaccess - Customer Kafka · Publishes customer-created events to Kafka.
document-notification-system/customer-service/customer-messaging
Document service
Central orchestration bounded context with saga and outbox flows.
- Document API · REST controller and exception handler for document creation.
document-notification-system/document-service/document-application-api - Document app · Document use-case orchestration, sagas, listeners, outbox helpers, and ports.
document-notification-system/document-service/document-domain/document-application-service - Document core · Document aggregate, items, addresses, domain events, and domain exceptions.
document-notification-system/document-service/document-domain/document-domain-core - Document data · Document persistence plus generation and notification outbox tables.
document-notification-system/document-service/document-dataaccess - Document Kafka · Kafka listeners and publishers for customer, generation, and notification flow.
document-notification-system/document-service/document-messaging
Generator service
Worker bounded context that generates document content and replies via Kafka.
- Generator app · Generation orchestration, request handling, helper logic, and outbox scheduling.
document-notification-system/generator-service/generator-domain/generator-application-service - Generator core · Generation aggregate, content generator, generation events, and generation status models.
document-notification-system/generator-service/generator-domain/generator-domain-core - Generator data · Generation persistence plus outbox table and repository adapter.
document-notification-system/generator-service/generator-dataaccess - Generator Kafka · Consumes generation requests and publishes generation responses.
document-notification-system/generator-service/generator-messaging
Notification service
Asynchronous notification bounded context with email delivery and outbox reliability.
- Notification app · Notification orchestration, request handling, helper logic, and outbox scheduling.
document-notification-system/notification-service/notification-domain/notification-application-service - Notification core · Notification aggregate, sender port, events, and notification value objects.
document-notification-system/notification-service/notification-domain/notification-domain-core - Notification data · Notification persistence plus outbox table and repository adapter.
document-notification-system/notification-service/notification-dataaccess - Notification runtime · Bootstraps the notification service and wires the email sender adapter.
document-notification-system/notification-service/notification-container
Infrastructure
Kafka, outbox, saga, and local runtime support modules.
- Kafka model · Shared Avro schemas and message models for inter-service contracts.
document-notification-system/infraestructure/kafka/kafka-model - Kafka core · Shared Kafka producer/consumer configuration and helpers.
document-notification-system/infraestructure/kafka - Outbox core · Reusable outbox scheduler and status abstractions.
document-notification-system/infraestructure/outbox - Saga core · Shared saga status, step, and constants abstractions.
document-notification-system/infraestructure/saga
Connections 40
- Common domain → Customer core: shared primitives · Customer domain reuses shared entities, value objects, and event abstractions.
- Common domain → Document core: shared primitives · Document domain reuses shared domain foundations and value objects.
- Common domain → Generator core: shared primitives · Generator domain reuses shared domain foundations and value objects.
- Common domain → Notification core: shared primitives · Notification domain reuses shared domain foundations and value objects.
- Common API → Customer API: global errors · Shared API exception handling supports the customer REST boundary.
- Common API → Document API: global errors · Shared API exception handling supports the document REST boundary.
- Kafka model → Customer Kafka: contracts · Customer Kafka adapter maps to shared Avro message contracts.
- Kafka model → Document Kafka: contracts · Document messaging maps domain messages to shared Avro contracts.
- Kafka model → Generator Kafka: contracts · Generator messaging maps domain messages to shared Avro contracts.
- Kafka model → Notification app: contracts · Notification workflow uses shared Avro contract models for integration messages.
- Kafka core → Customer Kafka: kafka plumbing · Customer messaging uses shared producer/consumer infrastructure.
- Kafka core → Document Kafka: kafka plumbing · Document messaging uses shared producer/consumer infrastructure.
- Kafka core → Generator Kafka: kafka plumbing · Generator messaging uses shared producer/consumer infrastructure.
- Kafka core → Notification app: kafka plumbing · Notification listeners use shared producer/consumer infrastructure.
- Outbox core → Document app: outbox runtime · Document outbox schedulers rely on shared outbox runtime support.
- Outbox core → Generator app: outbox runtime · Generator outbox schedulers rely on shared outbox runtime support.
- Outbox core → Notification app: outbox runtime · Notification outbox schedulers rely on shared outbox runtime support.
- Saga core → Document app: saga runtime · Document orchestration uses shared saga abstractions.
- Customer API → Customer app: calls · REST endpoints delegate to customer use cases.
- Customer app → Customer core: domain logic · Use cases orchestrate the customer aggregate and domain events.
- Customer app → Customer data: repository port · Customer use cases persist through the repository adapter.
- Customer app → Customer Kafka: event port · Customer use cases publish customer-created events through messaging.
- Customer data → Customer core: maps to domain · Persistence adapter maps between entities and customer domain objects.
- Customer Kafka → Kafka model: publishes · Customer Kafka publisher serializes to shared event contracts.
- Document API → Document app: calls · REST endpoints delegate to document orchestration.
- Document app → Document core: domain logic · Document use cases coordinate document aggregate behavior and events.
- Document app → Document data: repository port · Document orchestration persists state and outbox records through adapters.
- Document app → Document Kafka: message port · Document orchestration reacts to and emits Kafka workflow messages.
- Document app → Saga core: workflow · Document orchestration uses saga coordination across service boundaries.
- Document Kafka → Kafka model: consumes/publishes · Document messaging adapts shared Avro contracts to service-specific messages.
- Document data → Document core: maps to domain · Persistence adapter maps document entities, items, and outbox records.
- Generator app → Generator core: domain logic · Generation use cases invoke the generation aggregate and content generator.
- Generator app → Generator data: repository port · Generation state and outbox records are persisted via adapters.
- Generator app → Generator Kafka: message port · Generation use cases consume requests and publish responses through Kafka.
- Generator data → Generator core: maps to domain · Persistence adapter maps generation entities and outbox records.
- Generator Kafka → Kafka model: consumes/publishes · Generator messaging adapts shared Avro contracts to service-specific messages.
- Notification app → Notification core: domain logic · Notification use cases orchestrate notification sending and state transitions.
- Notification app → Notification data: repository port · Notification state and outbox records are persisted via adapters.
- Notification app → Notification runtime: sender adapter · The container provides the concrete email sender implementation.
- Notification data → Notification core: maps to domain · Persistence adapter maps notification entities and outbox records.