pawelkaczor/akka-ddd

This is a Scala-based framework for building distributed, event-sourced applications using the Akka actor model. It provides core abstractions for managing stateful actors, including aggregate roots, sagas, and process managers, while handling cluster sharding and reliable message delivery. The system also supports HTTP command routing, SQL-based view updates, and scheduled task execution, all backed by an EventStore persistence layer.

15 changes.

The project underwent a significant architectural overhaul, migrating to a multi-module build structure and modernizing its dependency management. Core Domain-Driven Design components, such as Aggregate Roots and Sagas, were refactored to improve separation of concerns, observability, and cluster sharding support. New features were introduced for process management, event sourcing, and reliable message delivery, while legacy test utilities and abstractions were removed.

13 changes.

This period focused on implementing core event-driven capabilities, including a new view-update module for SQL-based state management and a scheduling system for deadline tracking. The work also introduced HTTP command handling and message deduplication to support reliable message processing. Comprehensive test coverage was added for these new components to ensure correctness.

13 changes.

This period focused on expanding the Akka DDD framework with new protocol modules, monitoring capabilities, and message metadata support. The work included refactoring aggregate protocols, introducing event tagging for persistence, and adding comprehensive test coverage for domain models and core components.

Introduces the core components for integrating with EventStore as a persistence backend. This includes the EventStoreProvider for managing the connection, the EventSourceProvider for reading events via Akka's ReadJournal, and the EventStoreSerializer for handling serialization of domain events and metadata into the EventStore format.

eventstore-akka-persistence/src/main/scala · high confidence

The new akka-ddd-monitoring module introduces trace context management for tracking the duration of key DDD operations. AggregateRootMonitoring records the time between command creation and reception, as well as the handling of commands. ReceptorMonitoring tracks the time between an event's persistence in the event store and its reception. SagaMonitoring measures the time taken to react to domain events. These changes enable users to monitor performance and latency across the entire event-sourcing pipeline.

akka-ddd-monitoring · medium confidence

New utility classes have been added to the akka-ddd-protocol module. ImplicitUtils provides extension methods (asParameterizedBy, asParameterizedBy2) to safely cast generic types, replacing previous use of asInstanceOf. UUIDSupport introduces helper methods for generating and formatting UUIDs, including short variants (uuid7, uuid10).

akka-ddd-protocol/src/main/scala/pl/newicom/dddd/utils · high confidence

New projection scripts and metadata have been added to the Akka DDD scheduling module. The 'clock' projection emits a 'tick' event every minute based on system time, while the 'current-deadlines' projection listens for 'EventScheduled' events and monitors them against the clock's tick to identify and emit active deadlines. This introduces the underlying infrastructure for tracking and firing scheduled events based on time.

akka-ddd-scheduling/src/main/resources · high confidence

The Akka DDD protocol has been extracted into a new \akka-ddd-protocol\ module. This includes new implementations for cluster distribution strategies, delivery protocol definitions, and JSON serialization hint providers, alongside the relocation of existing serialization support classes into the new module.

akka-ddd-protocol/src/main/scala/pl/newicom/dddd/cluster, akka-ddd-protocol/src/main/scala/pl/newicom/dddd/delivery, akka-ddd-protocol/src/main/scala/pl/newicom/dddd/serialization · high confidence

The akka-ddd-messaging module now includes new abstractions for event sourcing: an EventMessage trait and companion object that wraps a DomainEvent with metadata, and an EventSourceProvider that uses Akka Persistence Query (via EventsByTagQuery) to stream events. This enables reading persisted events from the event store as a stream of EventMessage entries, supporting features like saga correlation and event replay.

akka-ddd-messaging · medium confidence

The akka-ddd-write-front module now provides a new HTTP command handling layer. HttpCommandHandler exposes a Route that accepts POST requests containing a command payload, automatically extracting an optional 'Command-ID' header to correlate requests. CommandDirectives supply the necessary HTTP directives for header parsing, while GlobalOfficeClientSupport manages the underlying cluster client connections for each office, ensuring commands are routed correctly to the appropriate actors.

akka-ddd-write-front · high confidence

The core library now includes an OfficeRegistry singleton that tracks all registered offices (both in-cluster and external) and provides methods to look up OfficeRef instances by EntityId or Command. OfficeFactory has been introduced to create and manage OfficeRef instances, with support for CoordinationOffice for Saga-based processes. This change adds logging via OfficeListener and establishes a central registry for office discovery and routing.

akka-ddd-core/src/main/scala/pl/newicom/dddd/office · high confidence

A new http-support module is added, providing Scala-based HTTP endpoint handling built on Akka HTTP. It includes an Endpoint trait for defining HTTP routes, JsonMarshalling for automatic JSON serialization and deserialization, and an ImplicitMaterializer to manage Akka Stream materializers within actors. This introduces a structured way to build HTTP services with JSON support in the application.

http-support · high confidence

The messaging protocol now supports attaching arbitrary metadata to messages via a new \Message\ trait and an \AddressableMessage\ interface. Users can attach metadata attributes such as tags, correlation IDs, and publisher types to messages, enabling more granular tracking and routing of events within the system.

akka-ddd-protocol/src/main/scala/pl/newicom/dddd/messaging · medium confidence

The view-update module introduces new core abstractions for handling event-driven view updates. This includes a ViewHandler abstract class that processes OfficeEventMessage instances and tracks event numbers, a ViewUpdateConfig for managing view names and event sources, and a UserGuardianStrategyConfigurator for defining Akka actor supervision strategies. These components form the foundation for the new view-update functionality.

view-update · medium confidence

The library now provides built-in support for Akka Cluster Sharding and Singleton Managers. Developers can now easily distribute stateful actors across a cluster using the new ShardingSupport trait, which handles entity routing and shard resolution, and manage singleton actors across the cluster via SingletonManagerFactory. This enables building scalable, distributed applications with automatic message routing and high-availability singleton services.

akka-ddd-core/src/main/scala/pl/newicom/dddd/cluster · high confidence

A new Scala package object for the process module was added, providing helper methods to create a command queue for a given department and to generate the corresponding RemoteOfficeId and sink name. This introduces the foundational components for the command queue feature referenced in the commit message.

akka-ddd-protocol/src/main/scala/pl/newicom/dddd/process · high confidence

The codebase introduces several new foundational components for the DDD framework. A \Config\ and \RespondingPolicy\ are added to control how aggregate roots respond to commands, allowing users to choose between replying with events or a sparse reply. The \Behavior\ and \Actions\ classes provide a DSL for defining command and query handlers, supporting composition via \orElse\ and \++\. A \CommandHandlerContext\ is introduced to pass configuration and metadata to command handlers. For persistence, \RegularSnapshotting\ and \SaveSnapshotRequest\ enable automatic snapshotting based on message counts. The \AtLeastOnceDeliverySupport\ trait and \DeliveryState\ manage reliable message delivery. Additionally, \ReceptorBuilder\ and \Receptor\ classes handle event stream subscription and message routing, while \OfficeRef\ and \LocalOfficeId\ provide a typed way to reference and interact with remote actors.

. · high confidence

Adds new classes and traits for managing business processes and sagas, including \ProcessConfig\ for configuration, \ProcessManager\ as the default saga implementation, and \SagaBase\ with state handling and collaboration logic. Also adds \CoordinationOffice\ and \CommandQueueReceptor\ for event routing and command queuing, along with supporting factories and listeners.

akka-ddd-core/src/main/scala/pl/newicom/dddd/process · high confidence

The messaging layer now includes a new Deduplication trait that acts as a ReceivePipeline to detect and handle duplicate messages. This component maintains a set of processed message IDs to prevent duplicate processing, with methods to check for prior receipt and to record new IDs after state updates. This provides a reusable mechanism for actors to ignore repeated messages based on their unique identifiers.

akka-ddd-core/src/main/scala/pl/newicom/dddd/messaging · high confidence

A new Scala package object in the scheduling module introduces factory methods for generating office identifiers. Specifically, it adds \schedulingOfficeId\ and \currentDeadlinesOfficeId\ to create remote office IDs for schedule events, and \schedulingLocalOfficeId\ to derive local office IDs for the scheduler. These utilities standardize how scheduling and deadline-related components resolve their target offices.

akka-ddd-scheduling/src/main/scala · high confidence

The akka-ddd-test module introduces new test fixtures and utilities to support testing of Process Managers and Aggregate Roots. This includes the addition of \GivenWhenThenPMTestFixture\ and \PMSpec\ for Process Manager testing, \GivenWhenThenARTestFixture\ and \ARSpec\ for Aggregate Root testing, and \OfficeRefStub\ for mocking office references. Additionally, cluster testing infrastructure is provided via \SimpleClusterSpec\, \MultiNodeWithLevelDbJournalSpec\, and \STMultiNodeSpec\, along with a \TestConfig\ for in-memory database and logging setup.

akka-ddd-test/src/main · high confidence

The view-update-sql module introduces a new SQL-backed implementation for updating database views from event streams. It provides a SqlViewUpdateService that manages database connections, ensures the view-metadata table is created on initialization, and executes projections transactionally to maintain consistency. The handler processes OfficeEventMessages by running a sequence of projection consumes followed by an upsert of the last processed event number, all within a single transactional boundary.

view-update-sql/src/main/scala · high confidence

A new TaggingEventAdapter has been introduced to enable event tagging in the persistence layer. The adapter reads tag configurations and applies them to events, but explicitly excludes events marked as 'reused' from receiving tags. This change allows users to tag specific events for querying or filtering, while ensuring that reused events remain untagged.

akka-ddd-core/src/main/scala/pl/newicom/dddd/persistence · high confidence

Removed the foundational building blocks for the DDD framework, including the AggregateRoot and Saga actor implementations, along with associated messaging, event handling, and cluster sharding support. This eliminates the ability to define and run persistent aggregate roots and sagas using the previous internal abstractions.

src/main · high confidence

The EventStore persistence plugin now supports tagged events. A new reference.conf file registers the EventStore serializer and binds PersistentRepr and SnapshotEvent to it, while also configuring a 'tagger' event adapter for EventMessage types. Additionally, a new tags.js file defines an EventStore stream projection that reads from all events and links them to specific tags found in the event metadata, enabling tag-based event filtering and processing.

eventstore-akka-persistence/src/main/resources · high confidence

A new reference.conf file was added to the view-update-sql module, defining the database profile as Slick's PostgresProfile and configuring the connection pool with the PostgreSQL JDBC driver. The configuration sets the database URL to localhost:5432 by default, but allows overriding the URL via the VIEW\_STORE\_URL environment variable, and sets the number of threads to 1.

view-update-sql/src/main/resources · medium confidence

A new Eventsourced trait is introduced, requiring a BusinessEntity and providing a streamName based on the entity's id. The BusinessEntity trait is also added, defining the id and department properties. This change establishes a new base for event-sourced components within the DDD protocol layer.

akka-ddd-protocol/src/main/scala/pl/newicom/dddd · medium confidence

The \CreationSupport\ trait has been renamed to \ActorFactory\ and refactored into an abstract class, while \ActorContextCreationSupport\ has been replaced by a \Supervisor\ trait that provides child actor management. Additionally, the \BusinessEntityActorFactory\ has been updated to use a more specific import path for \BusinessEntity\, and an \@implicitNotFound\ annotation has been added to improve the clarity of compilation errors when a required factory is missing.

akka-ddd-core/src/main/scala/pl/newicom/dddd/actor · medium confidence

The aggregate protocol module now includes a new Query base class and a package object defining type aliases for EntityId and DomainEvent. The Command trait has been updated to use the new AggregateId type instead of a raw String. Additionally, error handling has been refined: the original DomainException has been renamed to CommandRejected and made a concrete class, while a new QueryRejected exception class has been introduced to handle query-specific failures.

akka-ddd-protocol/src/main/scala/pl/newicom/dddd/aggregate · high confidence

The AggregateRoot implementation was restructured to improve separation of concerns and observability. A new \AggregateRootBase\ trait was introduced to handle core persistence, message tracking, and pipeline wiring, while \AggregateRoot\ now focuses on command/query handling and reaction execution. A dedicated \AggregateRootLogger\ trait was added to provide debug-level logging for commands, queries, and state changes. Additionally, the \EventHandler\ interface was updated to accept an \ActorRef\ and a sequence of \OfficeEventMessage\ instances, aligning with the new architecture.

akka-ddd-core/src/main/scala/pl/newicom/dddd/aggregate · medium confidence

The \EntityIdResolution\ class was introduced to handle entity ID resolution, specifically extracting the destination from the new \AddressableMessage\ type. Additionally, \AggregateIdResolution\ was updated to resolve the \aggregateId\ via \.value\ and updated its import to use the new \EntityIdResolver\ from the \cluster\ package, reflecting the broader refactoring of the messaging subsystem.

akka-ddd-core/src/main/scala/pl/newicom/dddd/messaging/correlation · medium confidence

The system now automatically routes commands to the appropriate office. If the target office is not available in the cluster, the command is enqueued for later delivery. This is implemented via a new \ToDeliverableCommandTransformation\ class that checks office availability using the \OfficeRegistry\.

akka-ddd-core/src/main/scala/pl/newicom/dddd/coordination · medium confidence

Add integration and unit tests for Saga and Receptor components; Add test infrastructure and SchedulerSpec for the scheduling module; Add tests for MetaAttribute tag merging; Added DMS sample tests for document management; Added dummy test fixtures for validating Aggregate Root and Saga behavior; Added integration test configuration for Akka persistence and H2 database; Added tests for SqlViewUpdateService and ViewMetadataDao; Added tests for aggregate behavior support; Added tests for the Lottery domain model; Removal of test helper classes and specs.

The build configuration has been refactored from a single-module project into a multi-module structure, introducing subprojects for protocol, messaging, core, write-front, view-update, eventstore-akka-persistence, http-support, scheduling, monitoring, and test utilities. The Scala version has been upgraded to 2.12.6, and Akka dependencies have been updated to version 2.5.1, including the addition of Akka HTTP support and various Akka modules. The project organization has also changed from 'pl.newicom' to 'pl.newicom.dddd'.

(dependencies) · medium confidence

The project's build system has been significantly modernized. The SBT version has been upgraded from 0.13.6 to 1.1.6, and the \project/Deps.scala\ file has been introduced to centralize all dependency versions, including Akka 2.5.13, Akka HTTP 10.1.3, Slick 3.2.3, and Kamon 0.6.6. Additionally, SBT plugins for release management (sbt-release) and Sonatype publishing (sbt-sonatype) have been added to \project/plugins.sbt\, and a \project/Publish.scala\ file has been created to configure Maven Central publishing metadata.

project · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 55 → 54 (-0.8)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 99 (-0.6)
• Architecture 100 → 91 (-9.4)
• Maturity 40 → 42 (+1.6)
• Readiness 57 → 50 (-7.0)
• Security 85 → 95 (+9.7)
• Domain Modelling 61 → 61 (+0.0)
• Event Sourcing 100 → 100 (+0.0)

• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• High: security finding (details withheld)
• High: security finding (details withheld)
• No exposed public API
• Test reliability not included
• complexity unreadable for .scala — churn × complexity hotspots could not be measured
• dormant codebase — no living knowledge left to concentrate

• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• TodoComment (akka-ddd-core/src/main/scala/pl/newicom/dddd/process/Receptor.scala)
• TodoComment (akka-ddd-test/src/main/scala/pl/newicom/dddd/office/SimpleOffice.scala)
• TodoComment (akka-ddd-test/src/test/scala/pl/newicom/dddd/process/ReceptorStressIntegrationSpec.scala)
• Workflow token permissions not restricted

• Containers 0 added · 0 removed · contexts 1 added · 1 removed · edges 0 added · 0 removed

• repository

• .

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

pawelkaczor/akka-ddd was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.