# j5ik2o/pekko-persistence-typed-fsm architecture

> Architecture diagram of the GitHub repository j5ik2o/pekko-persistence-typed-fsm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/j5ik2o/pekko-persistence-typed-fsm
- Repository: https://github.com/j5ik2o/pekko-persistence-typed-fsm

## Overview

##### Main Components
- Core Library Interfaces:
- Effector: The key trait that wraps around event persistence operations.
- EffectorConfig: Provides the configuration needed to initiate an effector for a particular domain.
- MessageConverter: Handles wrapping of persisted events and recovered state, ensuring type safety and conversion between internal representations.
- Domain Logic:
- The provided example (BankAccount) acts as a case study where commands (e.g., DepositCash) trigger domain operations that yield events (e.g., CashDeposited) and then lead to state transitions.
- Aggregate state types (such as NotCreated and Created) along with associated events (and handlers) represent the DDD style of domain modeling.
- Integration with Apache Pekko:
- The actors in the system follow a Behavior-based actor model (Pekko’s recommendation). The "Effector" is typically used within an actor (child actor under an aggregate actor) for persisting state updates.

##### Identifying Relationships and Interactions
- How a domain actor (e.g., BankAccountAggregate) uses Effector to persist events when handling a command.

##### Architectural Patterns and Design Principles
- Event Sourcing Pattern:
- Actor Model:
- That the persistent actor (created via Effector) is the core component and that it is a child of the main aggregate actor.
- Separation of Concerns:
- Clear separation of persistence logic (Effector and its configuration) from domain logic (state transitions and command handling).
- Type Safety and Extensibility:
- Usage of Scala 3 type system features to enforce type safety in the definitions of state, events, and messages.

- Be as detailed as possible within each component block. For instance, you could annotate the Effector block with key functions (persist, persistAll) and include a note that this is used to eliminate double execution of domain logic.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Input command
    CMD["Command Message"]:::integration

    %% Domain Layer
    subgraph "Domain Layer"
        DActor["Domain Actor (Aggregate Actor)"]:::domain
        DLogic["BankAccount Logic"]:::domain
    end

    %% Core Library Components
    subgraph "Core Library"
        Effector["Effector\n(persist, persistAll)"]:::core
        EffectorConfig["EffectorConfig\n(configuration parameters)"]:::core
        MsgConv["MessageConverter\n(convert events & state)"]:::core
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        Pekko["Apache Pekko Actor System"]:::infra
        EventStore["Event Store / Persistent Actor"]:::infra
    end

    %% Connections
    CMD -->|"handle_command"| DActor
    DActor -->|"execute_domain_logic"| DLogic

    DActor -->|"persist_event"| Effector
    EffectorConfig -->|"configure"| Effector
    Effector -->|"use_converter"| MsgConv
    Effector -->|"persist_to_store"| EventStore
    EventStore -->|"persistence_confirmation"| DActor

    EventStore ---|"recover_event"| MsgConv
    MsgConv -->|"rehydrate_state"| DActor

    Pekko ---|"host"| DActor
    Pekko ---|"host"| EventStore

    %% Click Events
    click Effector "https://github.com/j5ik2o/pekko-persistence-typed-fsm/blob/main/src/main/scala/Effector.scala"
    click EffectorConfig "https://github.com/j5ik2o/pekko-persistence-typed-fsm/blob/main/src/main/scala/EffectorConfig.scala"
    click MsgConv "https://github.com/j5ik2o/pekko-persistence-typed-fsm/blob/main/src/main/scala/MessageConverter.scala"
    click DActor "https://github.com/j5ik2o/pekko-persistence-typed-fsm/blob/main/src/test/scala/example/BankAccountAggregate.scala"
    click DLogic "https://github.com/j5ik2o/pekko-persistence-typed-fsm/blob/main/src/test/scala/example/BankAccount.scala"
    click EventStore "https://github.com/j5ik2o/pekko-persistence-typed-fsm/blob/main/src/main/scala/EventStoreActor.scala"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef domain fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef integration fill:#FFD700,stroke:#000,stroke-width:1px;
```
