# cajunsystems/cajun architecture

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

- Interactive diagram: https://gitdiagram.com/cajunsystems/cajun
- Repository: https://github.com/cajunsystems/cajun

## Overview

Cajun is a Java actor system for building concurrent applications. Applications define actors and handlers, configure and spawn them, then exchange messages through actor identities; actors process messages serially and can reply or create children. The broader product adds stateful recovery, backpressure, supervision, mailbox/thread-pool choices, and distributed messaging. The graph combines shown runtime calls with major README capabilities; several capability branches are represented at their source-directory level because their implementations were not sampled.

Main entry points: [`lib/src/main/java/com/cajunsystems/Actor.java`](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/Actor.java) (Actor processing), [`lib/src/main/java/com/cajunsystems/ActorSystem.java`](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/ActorSystem.java) (Actor system), [`lib/src/main/java/com/cajunsystems/internal/HandlerActor.java`](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/internal/HandlerActor.java) (Handler adapter), [`lib/src/main/java/com/cajunsystems/persistence`](https://github.com/cajunsystems/cajun/tree/main/lib/src/main/java/com/cajunsystems/persistence) (Persistence APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_actor_runtime["Actor runtime"]
  node_actor_system["Actor system<br/>[ActorSystem.java]"]
  node_actor_builder["Actor builder<br/>[ActorBuilder.java]"]
  node_actor["Actor processing<br/>[Actor.java]"]
  node_handler_actor["Handler adapter<br/>[HandlerActor.java]"]
  node_handlers["Actor handlers"]
  node_actor_context["Actor context<br/>[ActorContext.java]"]
  node_supervision["Supervision"]
end

subgraph group_messaging["Messaging and flow"]
  node_actor_ids["Actor identity<br/>[Pid.java]"]
  node_replies["Request replies"]
  node_backpressure["Backpressure"]
end

subgraph group_resilience["Resilience and persistence"]
  node_stateful_actors["Stateful actors"]
  node_persistence_api["Persistence APIs"]
  node_filesystem_store[("Filesystem persistence")]
  node_lmdb_store[("LMDB persistence")]
end

subgraph group_execution["Execution configuration"]
  node_mailboxes["Mailboxes"]
  node_thread_pools["Thread pools"]
end

subgraph group_distribution["Cluster runtime"]
  node_cluster_system["Cluster actor system"]
  node_cluster_factory["Cluster factory"]
  node_cluster_messaging["Cluster messaging"]
  node_metadata_store[("Cluster metadata")]
end

node_application(("Application"))

node_application -->|"creates actors"| node_actor_system
node_actor_system -->|"starts actors"| node_actor
node_actor_builder -->|"constructs"| node_handler_actor
node_handler_actor -->|"delegates messages"| node_handlers
node_handler_actor -->|"extends"| node_actor
node_actor_context -->|"sends messages"| node_actor_ids
node_actor_ids -->|"routes messages"| node_actor_system
node_actor_context -->|"replies to"| node_replies
node_actor -.->|"processes queued messages"| node_mailboxes
node_actor -.->|"runs on"| node_thread_pools
node_actor -.->|"manages pressure"| node_backpressure
node_actor -.->|"recovers failures"| node_supervision
node_stateful_actors -->|"runs stateful handlers"| node_handlers
node_stateful_actors -->|"uses persistence"| node_persistence_api
node_persistence_api -->|"implemented by"| node_filesystem_store
node_persistence_api -.->|"implemented by"| node_lmdb_store
node_actor_system -.->|"supports cluster mode"| node_cluster_system
node_cluster_factory -.->|"creates messaging"| node_cluster_messaging
node_cluster_factory -.->|"creates metadata store"| node_metadata_store
node_cluster_system -.->|"distributes messages"| node_cluster_messaging

click node_actor_system "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/ActorSystem.java"
click node_actor_builder "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/builder/ActorBuilder.java"
click node_actor "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/Actor.java"
click node_handler_actor "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/internal/HandlerActor.java"
click node_handlers "https://github.com/cajunsystems/cajun/tree/main/lib/src/main/java/com/cajunsystems/handler"
click node_actor_context "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/ActorContext.java"
click node_actor_ids "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/Pid.java"
click node_replies "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/ReplyingMessage.java"
click node_mailboxes "https://github.com/cajunsystems/cajun/tree/main/cajun-mailbox/src/main/java/com/cajunsystems/mailbox"
click node_thread_pools "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/config/ThreadPoolFactory.java"
click node_backpressure "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/backpressure/BackpressureManager.java"
click node_supervision "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/SupervisionStrategy.java"
click node_stateful_actors "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/internal/StatefulHandlerActor.java"
click node_persistence_api "https://github.com/cajunsystems/cajun/tree/main/lib/src/main/java/com/cajunsystems/persistence"
click node_filesystem_store "https://github.com/cajunsystems/cajun/tree/main/cajun-persistence/src/main/java/com/cajunsystems/persistence/filesystem"
click node_lmdb_store "https://github.com/cajunsystems/cajun/tree/main/cajun-persistence/src/main/java/com/cajunsystems/persistence/lmdb"
click node_cluster_system "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/cluster/ClusterActorSystem.java"
click node_cluster_factory "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/runtime/cluster/ClusterFactory.java"
click node_cluster_messaging "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/runtime/cluster/DirectMessagingSystem.java"
click node_metadata_store "https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/runtime/cluster/EtcdMetadataStore.java"

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_actor_system,node_actor_builder,node_actor,node_handler_actor,node_handlers,node_actor_context,node_supervision toneBlue
class node_actor_ids,node_replies,node_backpressure toneAmber
class node_stateful_actors,node_persistence_api,node_filesystem_store,node_lmdb_store toneMint
class node_mailboxes,node_thread_pools toneRose
class node_cluster_system,node_cluster_factory,node_cluster_messaging,node_metadata_store,node_application toneIndigo
```

## Components

### Actor runtime

- [Actor system](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/ActorSystem.java): `lib/src/main/java/com/cajunsystems/ActorSystem.java`
- [Actor builder](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/builder/ActorBuilder.java): `lib/src/main/java/com/cajunsystems/builder/ActorBuilder.java`
- [Actor processing](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/Actor.java): `lib/src/main/java/com/cajunsystems/Actor.java`
- [Handler adapter](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/internal/HandlerActor.java): `lib/src/main/java/com/cajunsystems/internal/HandlerActor.java`
- [Actor handlers](https://github.com/cajunsystems/cajun/tree/main/lib/src/main/java/com/cajunsystems/handler): `lib/src/main/java/com/cajunsystems/handler`
- [Actor context](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/ActorContext.java): `lib/src/main/java/com/cajunsystems/ActorContext.java`
- [Supervision](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/SupervisionStrategy.java): `lib/src/main/java/com/cajunsystems/SupervisionStrategy.java`

### Messaging and flow

- [Actor identity](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/Pid.java): `lib/src/main/java/com/cajunsystems/Pid.java`
- [Request replies](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/ReplyingMessage.java): `lib/src/main/java/com/cajunsystems/ReplyingMessage.java`
- [Backpressure](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/backpressure/BackpressureManager.java): `lib/src/main/java/com/cajunsystems/backpressure/BackpressureManager.java`

### Resilience and persistence

- [Stateful actors](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/internal/StatefulHandlerActor.java): `lib/src/main/java/com/cajunsystems/internal/StatefulHandlerActor.java`
- [Persistence APIs](https://github.com/cajunsystems/cajun/tree/main/lib/src/main/java/com/cajunsystems/persistence): `lib/src/main/java/com/cajunsystems/persistence`
- [Filesystem persistence](https://github.com/cajunsystems/cajun/tree/main/cajun-persistence/src/main/java/com/cajunsystems/persistence/filesystem): `cajun-persistence/src/main/java/com/cajunsystems/persistence/filesystem`
- [LMDB persistence](https://github.com/cajunsystems/cajun/tree/main/cajun-persistence/src/main/java/com/cajunsystems/persistence/lmdb): `cajun-persistence/src/main/java/com/cajunsystems/persistence/lmdb`

### Execution configuration

- [Mailboxes](https://github.com/cajunsystems/cajun/tree/main/cajun-mailbox/src/main/java/com/cajunsystems/mailbox): `cajun-mailbox/src/main/java/com/cajunsystems/mailbox`
- [Thread pools](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/config/ThreadPoolFactory.java): `lib/src/main/java/com/cajunsystems/config/ThreadPoolFactory.java`

### Cluster runtime

- [Cluster actor system](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/cluster/ClusterActorSystem.java): `lib/src/main/java/com/cajunsystems/cluster/ClusterActorSystem.java`
- [Cluster factory](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/runtime/cluster/ClusterFactory.java): `lib/src/main/java/com/cajunsystems/runtime/cluster/ClusterFactory.java`
- [Cluster messaging](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/runtime/cluster/DirectMessagingSystem.java): `lib/src/main/java/com/cajunsystems/runtime/cluster/DirectMessagingSystem.java`
- [Cluster metadata](https://github.com/cajunsystems/cajun/blob/main/lib/src/main/java/com/cajunsystems/runtime/cluster/EtcdMetadataStore.java): `lib/src/main/java/com/cajunsystems/runtime/cluster/EtcdMetadataStore.java`

### Other components

- **Application**

## Connections

- Application → Actor system: creates actors (evidence: `README.md`)
- Actor system → Actor processing: starts actors (evidence: `lib/src/main/java/com/cajunsystems/ActorSystem.java`)
- Actor builder → Handler adapter: constructs (evidence: `lib/src/main/java/com/cajunsystems/builder/ActorBuilder.java`)
- Handler adapter → Actor handlers: delegates messages (evidence: `lib/src/main/java/com/cajunsystems/internal/HandlerActor.java`)
- Handler adapter → Actor processing: extends (evidence: `lib/src/main/java/com/cajunsystems/internal/HandlerActor.java`)
- Actor context → Actor identity: sends messages (evidence: `lib/src/main/java/com/cajunsystems/ActorContext.java`)
- Actor identity → Actor system: routes messages (evidence: `lib/src/main/java/com/cajunsystems/Pid.java`)
- Actor context → Request replies: replies to (evidence: `lib/src/main/java/com/cajunsystems/ActorContext.java`)
- Actor processing → Mailboxes: processes queued messages (evidence: `lib/src/main/java/com/cajunsystems/Actor.java`)
- Actor processing → Thread pools: runs on
- Actor processing → Backpressure: manages pressure (evidence: `lib/src/main/java/com/cajunsystems/Actor.java`)
- Actor processing → Supervision: recovers failures (evidence: `lib/src/main/java/com/cajunsystems/Actor.java`)
- Stateful actors → Actor handlers: runs stateful handlers (evidence: `lib/src/main/java/com/cajunsystems/internal/StatefulHandlerActor.java`)
- Stateful actors → Persistence APIs: uses persistence (evidence: `lib/src/main/java/com/cajunsystems/internal/StatefulHandlerActor.java`)
- Persistence APIs → Filesystem persistence: implemented by (evidence: `cajun-persistence/src/main/java/com/cajunsystems/persistence/impl/FileSystemPersistenceProvider.java`)
- Persistence APIs → LMDB persistence: implemented by (evidence: `cajun-persistence/src/main/java/com/cajunsystems/persistence/lmdb/LmdbSnapshotStore.java`)
- Actor system → Cluster actor system: supports cluster mode
- Cluster factory → Cluster messaging: creates messaging
- Cluster factory → Cluster metadata: creates metadata store
- Cluster actor system → Cluster messaging: distributes messages
