Replace Akka Persistence with custom persistent entity implementation #8

New issue

Open

opened 2026-01-27 14:26:28 +00:00 by mprihoda · 0 comments

mprihoda commented

2026-01-27 14:26:28 +00:00

(Migrated from github.com)

Summary

Replace Akka Persistence with a custom implementation for persistent entities. This is a research-first task to evaluate alternatives and implement a chosen solution.

Motivation

Akka Persistence adds significant complexity and dependency weight for what we actually use. We want a simpler, more focused solution that we control.

Current State

The Akka Persistence usage is contained in akka-persistence/ module:

Persistent Entities:

DocumentCounterBehavior - Event-sourced counter for sequence ID generation
- Uses Akka Cluster Sharding for distribution
- Snapshots every 100 events
- State: simple counter (Int)

Projections:

AkkaProjectionSupport - Processes events from journal to update read models
- Uses ViewProcessor[E] interface
- JDBC backend with Slick

Abstractions (to preserve):

SequenceIdGeneratorFactory / IdGenerator[T] - Interface for ID generation
ViewProcessor[Event] - Interface for event projection handlers

Key characteristics:

JDBC backend (MySQL) for event journal and snapshots
ZIO-JSON serialization
Cluster sharding for distributed counters

Research Questions

What do we actually need?
- Event sourcing? Or simpler state persistence?
- Distributed coordination? Or single-node is sufficient?
- Projections? Or can read models be updated differently?
Alternatives to evaluate:
- Simple database-backed state (no event sourcing)
- ZIO-based event sourcing (custom implementation)
- Other libraries (e.g., zio-entity, sourcerer)
- Hybrid approach
Distribution concerns:
- Do we need cluster sharding equivalent?
- Can we use database-level locking instead?
- Single-writer per entity type acceptable?

Scope

Replace:

DocumentCounterBehavior and related code
AkkaProjectionSupport (if projections are still needed)
Akka serializers (AkkaZioJsonSerializer)
Akka configuration

Preserve interfaces:

SequenceIdGeneratorFactory
IdGenerator[T]
ViewProcessor[Event] (if projections remain)

Remove:

Akka Persistence dependencies
Akka Cluster Sharding dependencies
Related Akka configuration

Deliverables

Research document with alternatives analysis
Chosen approach with justification
Implementation of custom persistent entity solution
Migration of DocumentCounterBehavior
Migration of projections (if applicable)
Removal of Akka Persistence module

Checklist

Research alternatives and document findings
Decide on approach
Design new persistent entity abstraction
Implement core persistence mechanism
Migrate DocumentCounter
Migrate/replace projections
Update tests
Remove akka-persistence module
Update documentation

## Summary Replace Akka Persistence with a custom implementation for persistent entities. This is a research-first task to evaluate alternatives and implement a chosen solution. ## Motivation Akka Persistence adds significant complexity and dependency weight for what we actually use. We want a simpler, more focused solution that we control. ## Current State The Akka Persistence usage is contained in `akka-persistence/` module: **Persistent Entities:** - `DocumentCounterBehavior` - Event-sourced counter for sequence ID generation - Uses Akka Cluster Sharding for distribution - Snapshots every 100 events - State: simple counter (Int) **Projections:** - `AkkaProjectionSupport` - Processes events from journal to update read models - Uses `ViewProcessor[E]` interface - JDBC backend with Slick **Abstractions (to preserve):** - `SequenceIdGeneratorFactory` / `IdGenerator[T]` - Interface for ID generation - `ViewProcessor[Event]` - Interface for event projection handlers **Key characteristics:** - JDBC backend (MySQL) for event journal and snapshots - ZIO-JSON serialization - Cluster sharding for distributed counters ## Research Questions 1. **What do we actually need?** - Event sourcing? Or simpler state persistence? - Distributed coordination? Or single-node is sufficient? - Projections? Or can read models be updated differently? 2. **Alternatives to evaluate:** - Simple database-backed state (no event sourcing) - ZIO-based event sourcing (custom implementation) - Other libraries (e.g., zio-entity, sourcerer) - Hybrid approach 3. **Distribution concerns:** - Do we need cluster sharding equivalent? - Can we use database-level locking instead? - Single-writer per entity type acceptable? ## Scope **Replace:** - `DocumentCounterBehavior` and related code - `AkkaProjectionSupport` (if projections are still needed) - Akka serializers (`AkkaZioJsonSerializer`) - Akka configuration **Preserve interfaces:** - `SequenceIdGeneratorFactory` - `IdGenerator[T]` - `ViewProcessor[Event]` (if projections remain) **Remove:** - Akka Persistence dependencies - Akka Cluster Sharding dependencies - Related Akka configuration ## Deliverables 1. Research document with alternatives analysis 2. Chosen approach with justification 3. Implementation of custom persistent entity solution 4. Migration of `DocumentCounterBehavior` 5. Migration of projections (if applicable) 6. Removal of Akka Persistence module ## Checklist - [ ] Research alternatives and document findings - [ ] Decide on approach - [ ] Design new persistent entity abstraction - [ ] Implement core persistence mechanism - [ ] Migrate DocumentCounter - [ ] Migrate/replace projections - [ ] Update tests - [ ] Remove akka-persistence module - [ ] Update documentation