Code Map

​

Top-level layout

• actor/: Core: ActorSystem, PID, Actor interface, spawn, mailbox, supervision.
• remote/: Remoting config, serializers, wire protocol.
• client/: Standalone cluster client for external callers (Tell, Ask, Spawn).
• crdt/: CRDT types, config, messages; Replicator implementation lives in actor/.
• discovery/: Pluggable discovery providers (Consul, etcd, K8s, NATS, mDNS, DNS-SD, static).
• datacenter/: Multi-DC support, control plane (NATS JetStream, etcd).
• supervisor/: Supervision strategies and directives.
• stream/: Reactive streams: Source, Flow, Sink, RunnableGraph; materialized on actors.
• passivation/: Passivation strategy types.
• reentrancy/: Reentrancy configuration for async Request/RequestName.
• extension/: Extension (system-wide) and Dependency (per-actor) interfaces.
• eventstream/: In-process event bus for system and cluster events.
• hash/: Consistent hashing for partition-based placement.
• breaker/: Circuit breaker for async outbound calls (e.g. PipeTo).
• memory/: Memory size helpers.
• tls/: TLS configuration for remoting.
• log/: Logging abstraction.
• errors/: Sentinel errors.
• testkit/: Testing helpers: Probe, GrainProbe, TestKit, MultiNodes, TestNode.
• benchmark/: Throughput and latency benchmarks (BenchmarkTell, BenchmarkGrainTell, …).
• mocks/: Generated mocks.
• protos/: Protobuf source definitions (.proto files).

​

Key files in actor/

​

Core API and runtime

• actor.go: Actor interface: PreStart, Receive, PostStop.
• actor_system.go: ActorSystem implementation; wires cluster, remoting, scheduling, passivation.
• actor_path.go: Address/path parsing and formatting for goakt://system@host:port/path URLs.
• api.go: Top-level API surface: Tell, Ask, BatchTell, BatchAsk.
• pid.go: PID: live reference to an actor; implements schedulable.runTurn.
• pid_option.go, pid_state.go, pid_tree.go: PID options, lifecycle state, and the parent/child tree structure.
• receive_context.go: ReceiveContext passed to Receive; messaging, stash, behaviors.
• context_pool.go: Sharded lock-free pool for ReceiveContext objects. See the book’s chapter on the receive context.
• context.go: Context passed to PreStart / PostStop.
• option.go: Options for NewActorSystem (logger, remoting, cluster, WithThroughputBudget, …).
• defaults.go: Package-level default constants.
• messages.go: Internal protocol messages (PostStart, Terminated, Panicking, …).
• no_sender.go: Sentinel PID used when a message has no sender.
• pools.go: Error-channel pool and per-request Ask reply channels (not ReceiveContext).
• pipe_option.go: Options for PipeTo (async outbound with circuit breaker).
• poison_pill_serializer.go: Registration of the PoisonPill control message with the serializer registry.
• reflection.go: Runtime type helpers; instantiate actor/grain from type name.
• metric.go: OpenTelemetry actor metrics.
• guardrails.go: Reserved actor/grain name guards.

​

Scheduler: the dispatcher pool

• dispatcher.go: Fixed worker pool; start / stop / signalStop / schedule.
• worker.go: Worker goroutine loop; local-queue reschedule helper.
• ready_queue.go: Per-worker local rings, shared global ring, work stealing, condvar parking.
• dispatch_state.go: Three-state atomic machine (Idle / Scheduled / Processing) per actor.

​

Mailboxes

• mailbox.go: Mailbox interface.
• unbounded_mailbox.go: Default MPSC FIFO mailbox.
• embedded_mailbox.go: Default user mailbox run on two words inside PID with no separate object.
• bounded_mailbox.go: Capacity-capped mailbox; backpressure when full.
• unbounded_priority_mailbox.go: Priority-ordered mailbox.
• unbounded_fair_mailbox.go: Fair-scheduled mailbox; prevents producer starvation.
• unbounded_segmented_mailbox.go: Segmented mailbox for throughput partitioning.

​

Behaviour, supervision, lifecycle

• stash.go: Stash buffer for deferred messages.
• behavior_stack.go: Become / UnBecome stack for behavior switching.
• reentrancy.go: RequestCall, RequestOption; async request handling.
• supervision_signal.go: Internal supervision signals routed to the parent’s system mailbox.
• passivation_manager.go: Tracks idle actors; triggers passivation.
• dead_letter.go: Captures messages to stopped / non-existent actors.
• death_watch.go: Cleans up terminated actors; removes from tree and cluster.
• shutdown_hook.go: User-registered hooks run during coordinated shutdown.
• system_eviction.go: Eviction strategy (LRU / LFU / MRU) and scheduling when the actor cap is hit.

​

Guardians, routing, scheduling, scheduled delivery

• root_guardian.go: Root of the actor hierarchy.
• system_guardian.go: Parent of system actors (dead letter, relocator, replicator, topic actor, …).
• user_guardian.go: Parent of user-spawned actors.
• router.go / router_option.go: Router actor; fans out to routees.
• routing_strategy.go: Round-robin, random, fan-out strategies.
• scheduler.go / schedule_option.go: Scheduled / recurring / cron message delivery.
• func_actor.go: FuncActor: create an actor from a plain function.
• topic_actor.go: Pub/sub topic actor; also backs the CRDT delta topic (goakt.crdt.deltas).

​

Cluster, remoting, multi-DC

• cluster_config.go: Cluster configuration (discovery, CRDT, roles, multi-DC).
• cluster_singleton.go / cluster_singleton_option.go: Cluster singleton: single instance across all nodes.
• remote_server.go: TCP server for remoting; handles RemoteTell, RemoteAsk, RemoteSpawn, ….
• relocator.go: Relocates actors/grains when a cluster node departs.
• data_center_controller.go: Multi-DC controller; registers DC with the control plane.
• spawn.go / spawn_option.go: Spawn logic (local, remote, cross-DC); spawn options (mailbox, supervisor, passivation, reentrancy, role).

​

Grains (virtual actors)

• grain.go: Grain interface.
• grain_of.go: GrainOf[T] generic, factory-free grain activation entry point.
• grain_engine.go: Grain activation, routing, passivation.
• grain_pid.go: grainPID: PID variant for virtual actors; implements schedulable.
• grain_context.go: GrainContext for OnReceive.
• grain_context_pool.go: Sharded lock-free pool for GrainContext, Tell ack channels and Ask reply channels. See the book’s chapter on the grain runtime.
• grain_identity.go: GrainIdentity with memoised validation (hot-path allocation fix).
• grain_mailbox.go: Standalone grain mailbox for bounded user mailboxes and the response queue.
• embedded_grain_mailbox.go: Default unbounded grain mailbox, run on two words inside grainPID with no separate object.
• grain_props.go: GrainProps passed to OnActivate / OnDeactivate.
• grain_option.go: Grain activation options.
• grain_activation_barrier.go: Barrier for grain activation during cluster events.

​

CRDT replicator

• replicator.go: CRDT Replicator system actor: local store, delta publish/merge, anti-entropy, cross-DC flush.

​

crdt/

• crdt.go, key.go: ReplicatedData, keys, DataType.
• config.go, consistency.go: Config, options, optional read/write coordination.
• messages.go: Replicator messages (Get, Update, Subscribe, Delete, Changed, Deleted, …).
• gcounter.go, pncounter.go, lww_register.go, mv_register.go, or_set.go, or_map.go, flag.go: CRDT implementations.

​

stream/

• stream.go, graph.go, graph_builder.go, pipeline.go, materializer.go: Graph construction and Run.
• source.go, flow.go, sink.go: Stream building blocks.
• handle.go, metrics.go, tracer.go: StreamHandle, metrics, per-stage tracing hooks.
• protocol.go, queue.go, overflow.go: Wire protocol, GC-safe FIFO queue, overflow strategies.
• config.go, errors.go: Stage configuration and sentinel errors.
• stage_source.go, stage_flow.go, stage_sink.go: Stage actor implementations.
• stage_balance.go, stage_broadcast.go, stage_parallel.go, stage_coordinator.go: Fan-in/fan-out, parallel map, stream coordinator.

​

remote/

• config.go, option.go: Remoting Config: host, port, TLS, compression, batching, ….
• serializer.go: Serializer interface and registry.
• proto_serializer.go: Default protobuf serializer.
• cbor_serializer.go: CBOR serializer for non-proto messages.
• compression.go: Message compression (gzip, brotli, zstd).
• context_propagator.go: Context metadata propagation across remote calls.
• peer.go: Remote peer addressing.
• spawn_request.go: Remote spawn request payload.
• grain_request.go: Remote grain request payload.
• actor_state.go: Actor state for relocation.

​

discovery/

• consul/: HashiCorp Consul.
• etcd/: etcd v3.
• kubernetes/: Kubernetes API (headless services, pod labels).
• nats/: NATS.
• mdns/: Multicast DNS (local network).
• dnssd/: DNS Service Discovery.
• selfmanaged/: Gossip-based peer discovery over the cluster memberlist.
• static/: Hard-coded peer list.

​

datacenter/

• data_center.go: DataCenter metadata; DataCenterRecord.
• config.go: Datacenter configuration.
• control_plane.go: ControlPlane interface.
• controlplane/nats/: NATS JetStream control plane.
• controlplane/etcd/: etcd control plane.

​

client/

• client.go: Client: Tell, Ask, Spawn, SendSync, ReSpawn, Stop.
• option.go: Option for NewClient (balancer strategy, refresh interval).
• node.go: Node: cluster-member endpoint; WithRemoteConfig, WithWeight.
• balancer.go: Balancer interface.
• round_robin.go: Round-robin node selection.
• random.go: Random node selection.
• least_load.go: Least-loaded node selection.

​

Internal packages

• internal/address/: Address type; parsing, formatting, path operations.
• internal/cluster/: Cluster membership, Olric, actor/grain registry, peer state store.
• internal/remoteclient/: TCP client for remoting; connection pooling, proto frames, send coalescing.
• internal/net/: TCP server, client, frame protocol, compression.
• internal/codec/: Protobuf marshal/unmarshal; CRDT key helpers for wire types.
• internal/ddata/: CRDT snapshots (BoltDB), crdt_codec, crdt_serializer.
• internal/commands/: Command types for lifecycle (AsyncRequest, AsyncResponse, etc.).
• internal/datacentercontroller/: DC controller; registers DC, heartbeats, cache refresh.
• internal/types/: Registry interface; type name → factory for remote spawn.
• internal/memberlist/: Hashicorp Memberlist wrapper (TLS transport).
• internal/chain/: Middleware-style chain execution.
• internal/future/: Future/promise for Ask async delivery.
• internal/timer/: Timer pool for timeouts.
• internal/ticker/: Ticker abstraction.
• internal/pause/: Cooperative pause primitive.
• internal/duration/: Duration helpers.
• internal/locker/: Keyed lock / named mutex helpers.
• internal/quorum/: Quorum computation for cluster writes/reads.
• internal/queue/: General-purpose queue primitives (distinct from stream/queue.go).
• internal/id/: Unique ID generation.
• internal/size/: Byte-size parsing and formatting.
• internal/strconvx/: Extended string-conversion helpers.
• internal/xsync/: Atomic maps, extended sync primitives.
• internal/validation/: Fluent validation helpers.
• internal/pointer/: Generic pointer utilities.
• internal/metric/: OpenTelemetry metrics (includes Replicator instruments).
• internal/chunk/: Chunking utilities (e.g. for relocation allocation).
• internal/slices/: Slice utilities (Filter, etc.).
• internal/internalpb/: Generated protobuf Go code (wire types).

​

protos/

protos/
├── internal/   ← Wire types (cluster, remoting, actor, grain, datacenter, crdt, …)
└── test/       ← Test fixture proto messages

​

Dependency summary

• actor: remote, internal/cluster, discovery/*, datacenter, crdt, supervisor, passivation, reentrancy, eventstream, extension, log, errors, internal/*.
• remote: internal/net, internal/codec.
• internal/cluster: discovery, internal/memberlist, hash.
• client: remote, internal/address.
• stream: actor.

​

See also

• Architecture Overview
• Design Decisions: rationale for architectural choices
• Streams: reactive pipelines on actors
• Distributed data: CRDTs and the Replicator
• The maintainers’ book in the repository, GoAkt from the Inside: implementation detail for dispatch, context pools, remoting, reliable delivery, distributed data and streams