# rincon10/document-notification-system architecture

> Architecture diagram of the GitHub repository rincon10/document-notification-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rincon10/document-notification-system
- Repository: https://github.com/rincon10/document-notification-system

## Overview

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-notification-system/document-service/document-domain/document-application-service`](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/document-service/document-domain/document-application-service) (Document app), [`document-notification-system/infraestructure/kafka/kafka-model`](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/infraestructure/kafka/kafka-model) (Kafka model), [`document-notification-system/notification-service/notification-domain/notification-application-service`](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/notification-service/notification-domain/notification-application-service) (Notification app), [`document-notification-system/common/common-domain`](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/common/common-domain) (Common domain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_shared["Shared libs"]
  node_common_domain["Common domain<br/>shared domain"]
  node_common_api["Common API<br/>shared api"]
end

subgraph group_grp_customer["Customer service"]
  node_customer_api["Customer API<br/>rest adapter"]
  node_customer_app["Customer app<br/>use-case layer"]
  node_customer_core["Customer core<br/>domain model"]
  node_customer_data["Customer data<br/>jpa adapter"]
  node_customer_msg["Customer Kafka<br/>message adapter"]
end

subgraph group_grp_document["Document service"]
  node_document_api["Document API<br/>rest adapter"]
  node_document_app["Document app<br/>orchestration layer"]
  node_document_core["Document core<br/>domain model"]
  node_document_data["Document data<br/>jpa/outbox adapter"]
  node_document_msg["Document Kafka<br/>message adapter"]
end

subgraph group_grp_generator["Generator service"]
  node_generator_app["Generator app<br/>use-case layer"]
  node_generator_core["Generator core<br/>compute domain"]
  node_generator_data["Generator data<br/>jpa/outbox adapter"]
  node_generator_msg["Generator Kafka<br/>message adapter"]
end

subgraph group_grp_notification["Notification service"]
  node_notification_app["Notification app<br/>use-case layer"]
  node_notification_core["Notification core<br/>domain model"]
  node_notification_data["Notification data<br/>jpa/outbox adapter"]
  node_notification_container["Notification runtime<br/>spring boot"]
end

subgraph group_grp_infra["Infrastructure"]
  node_kafka_model["Kafka model<br/>avro contracts"]
  node_kafka_core["Kafka core<br/>kafka infra"]
  node_outbox_core["Outbox core<br/>reliable publish"]
  node_saga_core["Saga core<br/>workflow infra"]
end

node_common_domain -->|"shared primitives"| node_customer_core
node_common_domain -->|"shared primitives"| node_document_core
node_common_domain -->|"shared primitives"| node_generator_core
node_common_domain -->|"shared primitives"| node_notification_core
node_common_api -->|"global errors"| node_customer_api
node_common_api -->|"global errors"| node_document_api
node_kafka_model -->|"contracts"| node_customer_msg
node_kafka_model -->|"contracts"| node_document_msg
node_kafka_model -->|"contracts"| node_generator_msg
node_kafka_model -->|"contracts"| node_notification_app
node_kafka_core -->|"kafka plumbing"| node_customer_msg
node_kafka_core -->|"kafka plumbing"| node_document_msg
node_kafka_core -->|"kafka plumbing"| node_generator_msg
node_kafka_core -->|"kafka plumbing"| node_notification_app
node_outbox_core -->|"outbox runtime"| node_document_app
node_outbox_core -->|"outbox runtime"| node_generator_app
node_outbox_core -->|"outbox runtime"| node_notification_app
node_saga_core -->|"saga runtime"| node_document_app
node_customer_api -->|"calls"| node_customer_app
node_customer_app -->|"domain logic"| node_customer_core
node_customer_app -->|"repository port"| node_customer_data
node_customer_app -->|"event port"| node_customer_msg
node_customer_data -->|"maps to domain"| node_customer_core
node_customer_msg -->|"publishes"| node_kafka_model
node_document_api -->|"calls"| node_document_app
node_document_app -->|"domain logic"| node_document_core
node_document_app -->|"repository port"| node_document_data
node_document_app -->|"message port"| node_document_msg
node_document_app -->|"workflow"| node_saga_core
node_document_msg -->|"consumes/publishes"| node_kafka_model
node_document_data -->|"maps to domain"| node_document_core
node_generator_app -->|"domain logic"| node_generator_core
node_generator_app -->|"repository port"| node_generator_data
node_generator_app -->|"message port"| node_generator_msg
node_generator_data -->|"maps to domain"| node_generator_core
node_generator_msg -->|"consumes/publishes"| node_kafka_model
node_notification_app -->|"domain logic"| node_notification_core
node_notification_app -->|"repository port"| node_notification_data
node_notification_app -->|"sender adapter"| node_notification_container
node_notification_data -->|"maps to domain"| node_notification_core

click node_common_domain "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/common/common-domain"
click node_common_api "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/common/common-application-api"
click node_kafka_model "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/infraestructure/kafka/kafka-model"
click node_kafka_core "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/infraestructure/kafka"
click node_outbox_core "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/infraestructure/outbox"
click node_saga_core "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/infraestructure/saga"
click node_customer_api "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/customer-service/customer-application-api"
click node_customer_app "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/customer-service/customer-domain/customer-application-service"
click node_customer_core "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/customer-service/customer-domain/customer-domain-core"
click node_customer_data "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/customer-service/customer-dataaccess"
click node_customer_msg "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/customer-service/customer-messaging"
click node_document_api "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/document-service/document-application-api"
click node_document_app "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/document-service/document-domain/document-application-service"
click node_document_core "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/document-service/document-domain/document-domain-core"
click node_document_data "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/document-service/document-dataaccess"
click node_document_msg "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/document-service/document-messaging"
click node_generator_app "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/generator-service/generator-domain/generator-application-service"
click node_generator_core "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/generator-service/generator-domain/generator-domain-core"
click node_generator_data "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/generator-service/generator-dataaccess"
click node_generator_msg "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/generator-service/generator-messaging"
click node_notification_app "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/notification-service/notification-domain/notification-application-service"
click node_notification_core "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/notification-service/notification-domain/notification-domain-core"
click node_notification_data "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/notification-service/notification-dataaccess"
click node_notification_container "https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/notification-service/notification-container"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_common_domain,node_common_api toneBlue
class node_customer_api,node_customer_app,node_customer_core,node_customer_data,node_customer_msg toneAmber
class node_document_api,node_document_app,node_document_core,node_document_data,node_document_msg toneMint
class node_generator_app,node_generator_core,node_generator_data,node_generator_msg toneRose
class node_notification_app,node_notification_core,node_notification_data,node_notification_container toneIndigo
class node_kafka_model,node_kafka_core,node_outbox_core,node_saga_core toneTeal
```

## Components

### Shared libs

Cross-cutting domain and integration foundations used by multiple services.

- [Common domain](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/common/common-domain): shared domain · Base entities, events, value objects, utilities, and shared domain exceptions/constants. · `document-notification-system/common/common-domain`
- [Common API](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/common/common-application-api): shared 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](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/customer-service/customer-application-api): rest adapter · REST controller and exception handler for customer commands. · `document-notification-system/customer-service/customer-application-api`
- [Customer app](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/customer-service/customer-domain/customer-application-service): use-case layer · Customer command orchestration, ports, and mapping. · `document-notification-system/customer-service/customer-domain/customer-application-service`
- [Customer core](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/customer-service/customer-domain/customer-domain-core): domain model · Customer aggregate, domain service, event, and domain exception. · `document-notification-system/customer-service/customer-domain/customer-domain-core`
- [Customer data](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/customer-service/customer-dataaccess): jpa adapter · Customer persistence adapter, entity mapping, and repository. · `document-notification-system/customer-service/customer-dataaccess`
- [Customer Kafka](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/customer-service/customer-messaging): message adapter · 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](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/document-service/document-application-api): rest adapter · REST controller and exception handler for document creation. · `document-notification-system/document-service/document-application-api`
- [Document app](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/document-service/document-domain/document-application-service): orchestration layer · Document use-case orchestration, sagas, listeners, outbox helpers, and ports. · `document-notification-system/document-service/document-domain/document-application-service`
- [Document core](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/document-service/document-domain/document-domain-core): domain model · Document aggregate, items, addresses, domain events, and domain exceptions. · `document-notification-system/document-service/document-domain/document-domain-core`
- [Document data](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/document-service/document-dataaccess): jpa/outbox adapter · Document persistence plus generation and notification outbox tables. · `document-notification-system/document-service/document-dataaccess`
- [Document Kafka](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/document-service/document-messaging): message adapter · 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](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/generator-service/generator-domain/generator-application-service): use-case layer · Generation orchestration, request handling, helper logic, and outbox scheduling. · `document-notification-system/generator-service/generator-domain/generator-application-service`
- [Generator core](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/generator-service/generator-domain/generator-domain-core): compute domain · Generation aggregate, content generator, generation events, and generation status models. · `document-notification-system/generator-service/generator-domain/generator-domain-core`
- [Generator data](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/generator-service/generator-dataaccess): jpa/outbox adapter · Generation persistence plus outbox table and repository adapter. · `document-notification-system/generator-service/generator-dataaccess`
- [Generator Kafka](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/generator-service/generator-messaging): message adapter · 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](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/notification-service/notification-domain/notification-application-service): use-case layer · Notification orchestration, request handling, helper logic, and outbox scheduling. · `document-notification-system/notification-service/notification-domain/notification-application-service`
- [Notification core](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/notification-service/notification-domain/notification-domain-core): domain model · Notification aggregate, sender port, events, and notification value objects. · `document-notification-system/notification-service/notification-domain/notification-domain-core`
- [Notification data](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/notification-service/notification-dataaccess): jpa/outbox adapter · Notification persistence plus outbox table and repository adapter. · `document-notification-system/notification-service/notification-dataaccess`
- [Notification runtime](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/notification-service/notification-container): spring boot · 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](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/infraestructure/kafka/kafka-model): avro contracts · Shared Avro schemas and message models for inter-service contracts. · `document-notification-system/infraestructure/kafka/kafka-model`
- [Kafka core](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/infraestructure/kafka): kafka infra · Shared Kafka producer/consumer configuration and helpers. · `document-notification-system/infraestructure/kafka`
- [Outbox core](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/infraestructure/outbox): reliable publish · Reusable outbox scheduler and status abstractions. · `document-notification-system/infraestructure/outbox`
- [Saga core](https://github.com/rincon10/document-notification-system/tree/master/document-notification-system/infraestructure/saga): workflow infra · Shared saga status, step, and constants abstractions. · `document-notification-system/infraestructure/saga`

## Connections

- 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.
