# asynkron/protoactor-go architecture

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

- Interactive diagram: https://gitdiagram.com/asynkron/protoactor-go
- Repository: https://github.com/asynkron/protoactor-go

## Overview

##### Project Type and Purpose
- This is an open-source Go library implementing a distributed actor framework (“Proto Actor for Go”).
- It provides: a local actor runtime, pluggable middleware, remote messaging over gRPC/Protobuf, clustering (membership, gossip, identity lookup, pub/sub), persistence, routing, scheduling, event streams, metrics, logging, and code-generation tools.

##### High-Level Module/Directory Breakdown
- actor/            → Core actor runtime, message envelopes, mailbox, dispatch, lifecycle, supervision, futures, behaviors, middleware support
- remote/           → Remoting layer: gRPC server/client (EndpointManager, Activator), serializers (JSON/Proto), remote process/handler, activation, endpoint watcher/writer
- cluster/          → Clustering: membership (gossip, consensus), identity lookup/storage, pub/sub, grain management, providers (etcd, consul, k8s, zk, automanaged), cluster config/context
- persistence/      → Pluggable persistence providers (in-memory, Protobuf-CB), plugin interface, envelope transcoding, writer/receiver
- router/           → Router actors (broadcast, round-robin, consistent-hash, random), router groups/pools, router contracts
- scheduler/        → Timer service and examples
- eventstream/      → Global event bus for publications and subscriptions
- stream/           → Streaming support (typed, untyped)
- extensions/ctxext → Context extensions (propagation helpers)
- metrics/          → Metrics instrumentation for actors
- log/              → Logging middleware
- plugin/           → Actor plugins (e.g., passivation)
- protobuf/         → Codegen tool (protoc-gen-go-grain) for generating actor “grain” stubs from .proto
- internal/         → Internal queue implementations (goring, MPSC)
- examples/         → Dozens of end-to-end usage samples

##### Core Architectural Components
A. Actor Runtime
- Components: Props, PID, Context, Mailbox, Dispatcher, Behavior, Supervision, Futures.
- Responsibilities: local message dispatch, mailbox management, actor lifecycle, user message handling.

B. Middleware Chain
- Logging, tracing (OpenTracing propagation), protozip compression, custom propagators.
- Chained around message send/receive operations.

C. Remoting
- EndpointManager + Activator actors manage gRPC server listeners.
- EndpointWriter/Watcher handle node discovery and connection.
- Serializer interface for JSON or Protobuf.

D. Clustering
- Membership: gossip protocols, consensus checks, membership events.
- Identity lookup: distributed hash, cache, storage workers.
- Pub/Sub: topic creation, batching, delivery, producer/consumer abstractions.
- Grain activation: spawn remote actors by grain name.

E. Persistence
- PersistenceProvider interface, message encoding via Protobuf-CB.
- Plugin architecture for adding new backends.

F. Routing
- RouterActor with pluggable strategies: broadcast, round robin, consistent hash, random.
- Router groups and pools abstract over sets of routees.

G. Scheduling & Streams
- Timer service for delayed messages.
- Streaming layers for message streams (typed/untyped).

H. Supporting Services
- EventStream: publish/subscribe global events.
- Metrics: actor message counts, mailbox stats.
- Logging: structured actor logs.
- Context Extensions: propagate metadata across actors.

I. Tooling
- protoc-gen-go-grain: code generation tool plugged into protoc to scaffold actor stubs from .proto definitions.

##### Relationships and Interactions
- The RootContext/ActorSystem sits at the center: client code uses it to spawn actors.
- ActorRuntime core dispatches incoming messages (from local sends, remote deliveries, timers, or cluster/pubsub).
- Middleware wraps message send/receive paths.
- Remote layer and Cluster layer hook into ActorRuntime to route messages across nodes via gRPC or cluster pub/sub.
- Persistence and Plugins attach to actor lifecycles to snapshot or journal messages.
- Router, Scheduler, Stream, EventStream are specialized actor subsystems built on the core.
- Metrics and Logging subscribe to actor events/messages for instrumentation.
- Protoc-gen-go-grain runs at build time to generate message+grain glue code.

##### Architectural Patterns & Principles
- Actor Model for concurrency and failure isolation (supervision hierarchies).
- Pluggable middleware chain pattern.
- Micro-services style via gRPC streaming.
- Plugin architecture for persistence and codegen.
- Composition over inheritance: glue existing tech (gRPC, Protobuf).
- Event-driven message passing (local & remote).

– “Middleware Chain” (actor/middleware, logging, tracing, protozip)
– “Persistence” (persistence/)
– “Router” (router/)
– “Scheduler” (scheduler/)
– “EventStream” (eventstream/)
– “Stream” (stream/)
7. External dependencies: gRPC, Protobuf, Consul, etcd, Kubernetes API, ZooKeeper.

##### Final Touches
- Actor → Actor (local dispatch)
- ActorRuntime → Remote/Cluster (message export)
- Remote/Cluster → ActorRuntime (message import)
- ActorRuntime → Persistence (save/load)
- ActorRuntime → Scheduler (delayed send)
- Provide a note on supervision hierarchy (parent/child relationships inside ActorRuntime).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Layer"
        App["Application Actors / Examples"]:::external
    end

    subgraph "ActorRuntime Core"
        Core["Actor Runtime Core\n(actor/)"]:::core
        Internal["Internal Queues\n(internal/queue/)"]:::core
    end

    subgraph "Middleware Chain"
        MWChain["Middleware Chain\n(actor/middleware/, actor/middleware_chain.go)"]:::core
    end

    subgraph "Subsystems"
        Persistence["Persistence\n(persistence/, persistence/protocb/)"]:::sub
        Router["Routing\n(router/)"]:::sub
        Scheduler["Scheduling\n(scheduler/)"]:::sub
        StreamComp["Streaming\n(stream/)"]:::sub
        EventStream["EventStream\n(eventstream/)"]:::sub
        Metrics["Metrics & Logging\n(metrics/, log/log.go)"]:::sub
        ContextExt["Context Extensions\n(ctxext/extensions.go)"]:::sub
        PluginArch["Plugin Architecture\n(plugin/)"]:::sub
    end

    subgraph "Remote Layer"
        Remote["Remote Layer\n(remote/)"]:::sub
    end

    subgraph "Cluster Layer"
        Cluster["Clustering\n(cluster/, cluster/clusterproviders/)"]:::sub
        ExternalServices["External Services\n(Consul, etcd, k8s, ZooKeeper)"]:::infra
    end

    subgraph "Infrastructure"
        GRPC["gRPC"]:::infra
        Proto["Protobuf"]:::infra
    end

    subgraph "Tooling"
        Codegen["Code-Generation Tool\n(protobuf/protoc-gen-go-grain/)"]:::tool
    end

    %% Connections
    App -->|"Spawn/Send"| Core
    Core --> MWChain
    MWChain --> Core

    Core -->|"Invoke"| Persistence
    Core --> Router
    Core --> Scheduler
    Core --> StreamComp
    Core --> EventStream
    Core --> Metrics
    Core --> ContextExt
    Core --> PluginArch

    Core -->|"gRPC/Protobuf"| Remote
    Remote --> Core

    Core -->|"Cluster Pub/Sub"| Cluster
    Cluster --> Core
    Cluster --> ExternalServices

    Remote --> GRPC
    Remote --> Proto
    Cluster --> GRPC
    Cluster --> Proto

    Codegen -->|"Build-time codegen"| Core

    %% Click Events
    click Core "https://github.com/asynkron/protoactor-go/tree/dev/actor/"
    click Internal "https://github.com/asynkron/protoactor-go/tree/dev/internal/queue/"
    click MWChain "https://github.com/asynkron/protoactor-go/tree/dev/actor/middleware/"
    click MWChain "https://github.com/asynkron/protoactor-go/blob/dev/actor/middleware_chain.go"
    click Persistence "https://github.com/asynkron/protoactor-go/tree/dev/persistence/"
    click Persistence "https://github.com/asynkron/protoactor-go/tree/dev/persistence/protocb/"
    click Router "https://github.com/asynkron/protoactor-go/tree/dev/router/"
    click Scheduler "https://github.com/asynkron/protoactor-go/tree/dev/scheduler/"
    click StreamComp "https://github.com/asynkron/protoactor-go/tree/dev/stream/"
    click EventStream "https://github.com/asynkron/protoactor-go/tree/dev/eventstream/"
    click Metrics "https://github.com/asynkron/protoactor-go/tree/dev/metrics/"
    click Metrics "https://github.com/asynkron/protoactor-go/blob/dev/log/log.go"
    click ContextExt "https://github.com/asynkron/protoactor-go/blob/dev/ctxext/extensions.go"
    click PluginArch "https://github.com/asynkron/protoactor-go/tree/dev/plugin/"
    click Remote "https://github.com/asynkron/protoactor-go/tree/dev/remote/"
    click Cluster "https://github.com/asynkron/protoactor-go/tree/dev/cluster/"
    click Cluster "https://github.com/asynkron/protoactor-go/tree/dev/cluster/clusterproviders/"
    click Codegen "https://github.com/asynkron/protoactor-go/tree/dev/protobuf/protoc-gen-go-grain/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef sub fill:#E6FFEA,stroke:#28A745,color:#28A745;
    classDef infra fill:#FFF4E5,stroke:#DC7633,color:#DC7633;
    classDef tool fill:#FFF9C4,stroke:#F1C40F,color:#B7950B;
    classDef external fill:#F0F0F0,stroke:#7D7D7D,color:#7D7D7D;
```
