# otterbrix/actor-zeta architecture

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

- Interactive diagram: https://gitdiagram.com/otterbrix/actor-zeta
- Repository: https://github.com/otterbrix/actor-zeta

## Overview

actor-zeta is a header-only C++20 actor runtime. Its principal workflow is that a caller uses send() to create a typed mailbox message and, when applicable, a future; the actor is scheduled to process messages and the caller observes a reply through the future. The graph also preserves actor definition/addressing, cooperative scheduling, mailbox delivery, and coroutine/future support. Several internals and integrations are represented only by documented capabilities or tree paths; edges without direct evidence are omitted.

Main entry points: [`header/actor-zeta/send.hpp`](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/send.hpp) (Send Dispatch), [`header/actor-zeta/scheduler/worker.hpp`](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/scheduler/worker.hpp) (Worker Loop), [`header/actor-zeta/actor/cooperative_actor.hpp`](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/actor/cooperative_actor.hpp) (Cooperative Actor), [`header/actor-zeta/detail/future.hpp`](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/future.hpp) (Unique Future)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Actor API"]
  node_actor_def["Actor Definition<br/>[implements.hpp]"]
  node_actor_address["Actor Address<br/>[address.hpp]"]
  node_spawn["Spawn Actors<br/>[spawn.hpp]"]
end

subgraph group_messaging["Message Delivery"]
  node_send["Send Dispatch<br/>[send.hpp]"]
  node_message["Message Creation<br/>[make_message.hpp]"]
  node_mailbox["Default Mailbox"]
end

subgraph group_execution["Cooperative Execution"]
  node_cooperative_actor["Cooperative Actor"]
  node_scheduler["Scheduler<br/>[scheduler.hpp]"]
  node_worker["Worker Loop<br/>[worker.hpp]"]
  node_job_ptr["Resumable Job<br/>[job_ptr.hpp]"]
  node_policy["Work Sharing Policy<br/>[work_sharing.hpp]"]
end

subgraph group_async["Async Results"]
  node_future["Unique Future<br/>[future.hpp]"]
  node_future_awaiters["Future Awaiters"]
  node_shared_state["Shared State<br/>[shared_state.hpp]"]
end

subgraph group_internals["Runtime Internals"]
  node_result_storage["Result Storage<br/>[result_storage.hpp]"]
  node_linked_list["Linked Queue<br/>[linked_list.hpp]"]
  node_launch_thread["Thread Launcher<br/>[launch_thread.hpp]"]
end

node_caller(("Caller"))

node_caller -->|"sends via"| node_send
node_send -->|"creates"| node_message
node_send -->|"enqueues on"| node_cooperative_actor
node_send -->|"dispatches through"| node_actor_address
node_cooperative_actor -->|"pushes messages"| node_mailbox
node_cooperative_actor -.->|"requests scheduling"| node_scheduler
node_scheduler -.->|"runs workers"| node_worker
node_worker -->|"resumes job"| node_job_ptr
node_worker -->|"delegates scheduling"| node_policy
node_worker -->|"launches thread"| node_launch_thread
node_job_ptr -.->|"resumes actor"| node_cooperative_actor
node_message -->|"returns future"| node_future
node_future -.->|"observes state"| node_shared_state
node_future_awaiters -.->|"awaits"| node_future
node_shared_state -->|"stores result"| node_result_storage
node_mailbox -.->|"queues messages"| node_linked_list
node_caller -.->|"creates actors"| node_spawn
node_spawn -.->|"instantiates"| node_actor_def

click node_actor_def "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/actor/implements.hpp"
click node_actor_address "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/actor/address.hpp"
click node_spawn "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/spawn.hpp"
click node_send "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/send.hpp"
click node_message "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/mailbox/make_message.hpp"
click node_mailbox "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/mailbox/default_mailbox.hpp"
click node_cooperative_actor "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/actor/cooperative_actor.hpp"
click node_scheduler "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/scheduler/scheduler.hpp"
click node_worker "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/scheduler/worker.hpp"
click node_job_ptr "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/scheduler/job_ptr.hpp"
click node_policy "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/scheduler/policy/work_sharing.hpp"
click node_future "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/future.hpp"
click node_future_awaiters "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/future_awaiters.hpp"
click node_shared_state "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/shared_state.hpp"
click node_result_storage "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/result_storage.hpp"
click node_linked_list "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/queue/linked_list.hpp"
click node_launch_thread "https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/launch_thread.hpp"

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_def,node_actor_address,node_spawn toneBlue
class node_send,node_message,node_mailbox toneAmber
class node_cooperative_actor,node_scheduler,node_worker,node_job_ptr,node_policy toneMint
class node_future,node_future_awaiters,node_shared_state toneRose
class node_result_storage,node_linked_list,node_launch_thread,node_caller toneIndigo
```

## Components

### Actor API

- [Actor Definition](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/actor/implements.hpp): `header/actor-zeta/actor/implements.hpp`
- [Actor Address](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/actor/address.hpp): `header/actor-zeta/actor/address.hpp`
- [Spawn Actors](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/spawn.hpp): `header/actor-zeta/spawn.hpp`

### Message Delivery

- [Send Dispatch](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/send.hpp): `header/actor-zeta/send.hpp`
- [Message Creation](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/mailbox/make_message.hpp): `header/actor-zeta/mailbox/make_message.hpp`
- [Default Mailbox](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/mailbox/default_mailbox.hpp): `header/actor-zeta/mailbox/default_mailbox.hpp`

### Cooperative Execution

- [Cooperative Actor](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/actor/cooperative_actor.hpp): `header/actor-zeta/actor/cooperative_actor.hpp`
- [Scheduler](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/scheduler/scheduler.hpp): `header/actor-zeta/scheduler/scheduler.hpp`
- [Worker Loop](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/scheduler/worker.hpp): `header/actor-zeta/scheduler/worker.hpp`
- [Resumable Job](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/scheduler/job_ptr.hpp): `header/actor-zeta/scheduler/job_ptr.hpp`
- [Work Sharing Policy](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/scheduler/policy/work_sharing.hpp): `header/actor-zeta/scheduler/policy/work_sharing.hpp`

### Async Results

- [Unique Future](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/future.hpp): `header/actor-zeta/detail/future.hpp`
- [Future Awaiters](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/future_awaiters.hpp): `header/actor-zeta/detail/future_awaiters.hpp`
- [Shared State](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/shared_state.hpp): `header/actor-zeta/detail/shared_state.hpp`

### Runtime Internals

- [Result Storage](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/result_storage.hpp): `header/actor-zeta/detail/result_storage.hpp`
- [Linked Queue](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/queue/linked_list.hpp): `header/actor-zeta/detail/queue/linked_list.hpp`
- [Thread Launcher](https://github.com/otterbrix/actor-zeta/blob/master/header/actor-zeta/detail/launch_thread.hpp): `header/actor-zeta/detail/launch_thread.hpp`

### Other components

- **Caller**

## Connections

- Caller → Send Dispatch: sends via (evidence: `header/actor-zeta/send.hpp`)
- Send Dispatch → Message Creation: creates (evidence: `header/actor-zeta/send.hpp`)
- Send Dispatch → Cooperative Actor: enqueues on (evidence: `header/actor-zeta/send.hpp`)
- Send Dispatch → Actor Address: dispatches through (evidence: `header/actor-zeta/send.hpp`)
- Cooperative Actor → Default Mailbox: pushes messages (evidence: `header/actor-zeta/actor/cooperative_actor.hpp`)
- Cooperative Actor → Scheduler: requests scheduling
- Scheduler → Worker Loop: runs workers
- Worker Loop → Resumable Job: resumes job (evidence: `header/actor-zeta/scheduler/worker.hpp`)
- Worker Loop → Work Sharing Policy: delegates scheduling (evidence: `header/actor-zeta/scheduler/worker.hpp`)
- Worker Loop → Thread Launcher: launches thread (evidence: `header/actor-zeta/scheduler/worker.hpp`)
- Resumable Job → Cooperative Actor: resumes actor
- Message Creation → Unique Future: returns future
- Unique Future → Shared State: observes state
- Future Awaiters → Unique Future: awaits
- Shared State → Result Storage: stores result (evidence: `header/actor-zeta/detail/result_storage.hpp`)
- Default Mailbox → Linked Queue: queues messages
- Caller → Spawn Actors: creates actors
- Spawn Actors → Actor Definition: instantiates
