# slawlor/ractor architecture

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

- Interactive diagram: https://gitdiagram.com/slawlor/ractor
- Repository: https://github.com/slawlor/ractor

## Overview

##### Project type and purpose
- ractor is a pure-Rust actor framework library with an optional cluster extension (ractor_cluster).
- It provides Erlang-style gen_server semantics, actor supervision, timers, RPC, and named process registries.
- ractor_cluster adds networking: TCP listeners, node authentication, remote actors, and inter-node messaging via Protobuf protocols.

##### File structure
- Top-level crates:
– ractor: core actor framework
– ractor_cluster: distributed cluster support
– ractor_cluster_derive: procedural macros for message serialization
– ractor_cluster_integration_tests: end-to-end cluster tests in Docker
– ractor_example_entry_proc, ractor_playground: example consumers
– xtask: custom build/testing tasks
- Key directories in ractor:
– src/actor – actor lifecycle, ID, properties, supervisor logic
– src/concurrency – runtime adapters (tokio, async-std, WASM)
– src/factory – worker pools, routing, rate limiting
– src/registry – PID registry
– src/rpc – RPC primitives
– src/serialization – message serialization
– src/time – timer utilities
- In ractor_cluster:
– src/node – NodeServer, NodeSession, authentication
– src/net – TCP listener/session
– src/remote_actor – untyped serialized actor proxies
– protocol/*.proto – Protobuf definitions for control, meta, auth

##### README for additional insights
- Confirms core modules, feature flags (cluster, async-std, monitors, tracing)
- Describes actor model (signals, stop, supervision events, messages)
- Describes NodeServer responsibilities and NodeSession internals

##### Main components
a. Core Actor Runtime
– Actor API layer (Actor trait, Message trait)
– Supervisor subsystem (supervision trees, lifecycle events)
– Concurrency adapters (Tokio / Async-std / WASM)
– Message queue & dispatch engine
– Timers and scheduling
– Registry & process groups
– RPC handler
b. Cluster Extension
– NodeServer (TCP listener, cluster manager)
– NodeSession (network I/O, authentication, session actor)
– RemoteActor proxies (serialization boundary)
– Protobuf protocol modules
c. Application Layer
– User-defined actors (examples, playground, entry_proc)
– Procedural macros for deriving Message traits
– Integration test harness (Dockerized CA, env files)

##### Relationships and interactions
- Application code → uses Actor::spawn → communicates via Actor API → Core runtime
- Runtime → forks tasks onto underlying async runtime (Tokio/Async-std)
- Actors send messages to each other via the central message queue
- Supervision events flow from child actors up to supervisors
- Timers trigger actor messages
- Registry resolves actor names to ActorRefs
- RPC calls packaged and dispatched within the core RPC module
- When cluster feature is enabled:
– NodeServer spawns NodeSession per peer → manages TCP streams
– NodeSession serializes Actor messages (via prost using protocol/*.proto) → sends over TCP
– Incoming messages → NodeSession → deserializes → injects into local ActorRef as RemoteActor
- Integration tests use Docker Compose, CA certificates, and env files to simulate multi-node clusters

##### Architectural patterns and design principles
- Actor model with non-blocking, single-thread-per-actor semantics
- Supervision trees for fault tolerance (Erlang pattern)
- Adapter pattern for runtime binding (Tokio vs Async-std)
- Factory pattern for worker pools and routing
- Modular layering: Core runtime, cluster extension, user applications

##### Be detailed and capture essential elements
- Break the core into logical subcomponents (actor, concurrency, registry, RPC, factory, time)
- Async runtime adapters as a separate sub-layer
- In cluster, show the Protobuf files feeding into the serialization engine
- Avoid over-splitting: group similar modules but separate runtime, core logic, and network

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        Examples["Example Applications"]:::app
        Playground["Playground Application"]:::app
        EntryProc["Entry Procedure Example"]:::app
        TestHarness["Integration Test Harness"]:::app
        Xtask["Custom Build & Task Runner"]:::ext
    end

    %% Core Framework
    subgraph "Core Framework"
        subgraph "Core Runtime"
            ActorAPI["Core Actor API Layer"]:::core
            Supervisor["Supervisor Subsystem"]:::core
            ConcurrencyAdapters["Concurrency Adapters"]:::core
            MsgQueue["Message Queue & Dispatch Engine"]:::core
            Timers["Timers & Scheduling"]:::core
            Registry["Registry & Process Groups"]:::core
            RPC["RPC Handler"]:::core
            Serialization["Serialization Engine"]:::core
            Factory["Factory & Routing Subsystem"]:::core
            Errors["Core Errors & Utilities"]:::core
        end
    end

    %% Cluster Extension
    subgraph "Cluster Extension"
        NodeServer["NodeServer (Cluster Manager & TCP Listener)"]:::cluster
        TCPListener["TCP Listener"]:::cluster
        NodeSession["NodeSession (Network I/O & Authentication)"]:::cluster
        AuthMod["Authentication Module"]:::cluster
        RemoteActor["RemoteActor Proxies"]:::cluster
        Protodefs["Protobuf Protocol Definitions"]:::cluster
        DeriveMacros["Derive Macros for Message Serialization"]:::cluster
    end

    %% External Services
    subgraph "External Services"
        Network["TCP Network"]:::ext
        Docker["Docker Compose & CA"]:::ext
    end

    %% Connections - Application to Core
    Examples -->|"uses Actor::spawn"| ActorAPI
    Playground -->|"uses Actor::spawn"| ActorAPI
    EntryProc -->|"uses Actor::spawn"| ActorAPI
    TestHarness -->|"integration tests"| NodeServer
    Xtask -->|"runs build/test tasks"| Examples

    %% Core internal flows
    ActorAPI -->|"sends messages"| MsgQueue
    MsgQueue -->|"dispatches to"| ActorAPI
    ActorAPI -->|"lifecycle events"| Supervisor
    Supervisor -->|"controls"| ActorAPI
    MsgQueue -->|"handles timers"| Timers
    Timers -->|"schedules messages"| MsgQueue
    ActorAPI -->|"resolves names via"| Registry
    Registry -->|"provides ActorRefs"| ActorAPI
    ActorAPI -->|"invokes RPC"| RPC
    RPC -->|"uses"| Serialization
    Serialization -->|"serializes messages for"| RPC
    ConcurrencyAdapters -->|"binds to runtime"| ActorAPI
    ConcurrencyAdapters -->|"binds to runtime"| MsgQueue
    Factory -->|"routes work via"| ConcurrencyAdapters
    Errors -->|"common utilities for"| ActorAPI

    %% Cluster flows
    NodeServer -->|"listens on"| TCPListener
    TCPListener -->|"accepts peers"| NodeSession
    NodeSession -->|"auth via"| AuthMod
    NodeSession -->|"serializes via"| Serialization
    NodeSession -->|"creates"| RemoteActor
    RemoteActor -->|"injects into"| MsgQueue
    Protodefs -->|"define protobuf for"| Serialization
    DeriveMacros -->|"generate codecs for"| Serialization

    %% Cross-layer connections
    MsgQueue -->|"dispatches to remote over"| NodeSession
    NodeSession -->|"receives messages from"| MsgQueue

    %% External to Cluster/Tests
    Network -->|"transport for"| NodeSession
    Docker -->|"provides CA for"| AuthMod
    Docker -->|"simulates multi-node"| TestHarness

    %% Click Events
    click ActorAPI "https://github.com/slawlor/ractor/tree/main/ractor/src/actor"
    click Supervisor "https://github.com/slawlor/ractor/blob/main/ractor/src/actor/supervision.rs"
    click ConcurrencyAdapters "https://github.com/slawlor/ractor/tree/main/ractor/src/concurrency"
    click MsgQueue "https://github.com/slawlor/ractor/tree/main/ractor/src/thread_local"
    click Timers "https://github.com/slawlor/ractor/tree/main/ractor/src/time"
    click Registry "https://github.com/slawlor/ractor/tree/main/ractor/src/registry"
    click RPC "https://github.com/slawlor/ractor/tree/main/ractor/src/rpc"
    click Serialization "https://github.com/slawlor/ractor/blob/main/ractor/src/serialization.rs"
    click Factory "https://github.com/slawlor/ractor/tree/main/ractor/src/factory"
    click Errors "https://github.com/slawlor/ractor/blob/main/ractor/src/errors.rs"
    click NodeServer "https://github.com/slawlor/ractor/blob/main/ractor_cluster/src/node.rs"
    click TCPListener "https://github.com/slawlor/ractor/blob/main/ractor_cluster/src/net/listener.rs"
    click NodeSession "https://github.com/slawlor/ractor/blob/main/ractor_cluster/src/net/session.rs"
    click AuthMod "https://github.com/slawlor/ractor/blob/main/ractor_cluster/src/node/auth.rs"
    click RemoteActor "https://github.com/slawlor/ractor/blob/main/ractor_cluster/src/remote_actor.rs"
    click Protodefs "https://github.com/slawlor/ractor/tree/main/ractor_cluster/src/protocol"
    click DeriveMacros "https://github.com/slawlor/ractor/blob/main/ractor_cluster_derive/src/lib.rs"
    click Examples "https://github.com/slawlor/ractor/tree/main/ractor/examples"
    click Playground "https://github.com/slawlor/ractor/tree/main/ractor_playground/src"
    click EntryProc "https://github.com/slawlor/ractor/blob/main/ractor_example_entry_proc/src/lib.rs"
    click TestHarness "https://github.com/slawlor/ractor/tree/main/ractor_cluster_integration_tests"
    click Xtask "https://github.com/slawlor/ractor/blob/main/xtask/src/main.rs"

    %% Styles
    classDef core fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef cluster fill:#ccffcc,stroke:#33cc33,color:#000;
    classDef app fill:#ffdd99,stroke:#ff9900,color:#000;
    classDef ext fill:#eeeeee,stroke:#888888,color:#000;
```
