Skip to main content
A guided tour of the codebase. Start with actor/—everything flows from there.

​
Top-level layout

PackagePurpose
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
mocks/Generated mocks
protos/Protobuf source definitions (.proto files)

​
Key files in actor/

FilePurpose
actor.goActor interface: PreStart, Receive, PostStop
actor_system.goActorSystem implementation; wires cluster, remoting, scheduling
pid.goPID—live reference to an actor; mailbox dispatch loop, metrics
receive_context.goReceiveContext passed to Receive; messaging, stash, behaviors
context.goContext passed to PreStart/PostStop
spawn.goSpawn logic for local, remote, and cross-DC actors
spawn_option.goSpawnOption: mailbox, supervisor, passivation, reentrancy, role
option.goOption for NewActorSystem
cluster_config.goCluster configuration (optional WithCRDT / CRDT options)
cluster_singleton.goCluster singleton: single instance across all nodes
mailbox.goMailbox interface
unbounded_mailbox.goDefault FIFO mailbox
bounded_mailbox.goCapacity-capped mailbox; backpressure when full
unbounded_priority_mailbox.goPriority-ordered mailbox
unbounded_fair_mailbox.goFair-scheduled mailbox; prevents starvation
unbounded_segmented_mailbox.goSegmented mailbox for throughput partitioning
grain.goGrain interface and virtual actor machinery
grain_engine.goGrain activation, routing, passivation
grain_pid.goGrainPID—PID variant for virtual actors
grain_context.goGrainContext for grain OnReceive
router.goRouter actor; fans out to routees
routing_strategy.goRound-robin, random, fan-out strategies
scheduler.goScheduled / recurring message delivery
dead_letter.goCaptures messages to stopped/non-existent actors
death_watch.goCleans up terminated actors; removes from tree and cluster
relocator.goRelocates actors/grains when a cluster node departs
remote_server.goTCP server for remoting; handles RemoteTell, RemoteSpawn, etc.
root_guardian.goRoot of the actor hierarchy
system_guardian.goParent of system actors (dead letter, relocator, etc.)
user_guardian.goParent of user-spawned actors
passivation_manager.goTracks idle actors; triggers passivation
stash.goStash buffer for deferred messages
behavior_stack.goBecome/UnBecome stack for behavior switching
reentrancy.goRequestCall, RequestOption; async request handling
reflection.goRuntime type helpers; instantiate actor/grain from type name
data_center_controller.goMulti-DC controller; registers DC with control plane
grain_activation_barrier.goBarrier for grain activation during cluster events
metric.goOpenTelemetry actor metrics
func_actor.goFuncActor—create actor from a plain function
topic_actor.goPub/sub topic actor; EventStream and CRDT delta topic (goakt.crdt.deltas)
replicator.goCRDT Replicator system actor (local store, deltas, anti-entropy)
api.goTell, Ask, BatchTell, BatchAsk (top-level API)

​
crdt/

Pure CRDT data types and replication configuration—no import of actor. User and Replicator code interact via crdt messages and ReplicatedData values. See Distributed data and the repository architecture/CRDT_ADR.md.
FilePurpose
crdt.go, key.goReplicatedData, keys, DataType
config.go, consistency.goConfig, options, optional read/write coordination
messages.goReplicator messages (Get, Update, Subscribe, …)
gcounter.go, pncounter.go, lww_register.go, mv_register.go, or_set.go, or_map.go, flag.goCRDT implementations

​
stream/

Reactive pipelines (Source, Flow, Sink → RunnableGraph) materialized onto an ActorSystem with backpressure. See Streams and repository architecture/REACTIVE_STREAM_ADR.md.
FilePurpose
graph.go, graph_builder.go, materializer.goGraph construction and Run
source.go, flow.go, sink.goStream building blocks
handle.go, metrics.goStreamHandle, metrics
protocol.go, stage_*.goStage wiring and fan-in/fan-out

​
remote/

FilePurpose
remoting.goRemoting interface; RemoteTell, RemoteAsk, RemoteLookup, RemoteSpawn
config.goConfig for host, port, TLS, compression
spawn_request.goSpawnRequest for remote actor creation
compression.goMessage compression (gzip, brotli, zstd)
cbor_serializer.goCBOR serializer for non-proto messages

​
discovery/

Pluggable service discovery. Each sub-package implements discovery.Provider:
ProviderBackend
consul/HashiCorp Consul
etcd/etcd v3
kubernetes/Kubernetes API (headless services, pod labels)
nats/NATS
mdns/Multicast DNS (local network)
dnssd/DNS Service Discovery
static/Hard-coded peer list

​
datacenter/

FilePurpose
data_center.goDataCenter metadata; DataCenterRecord
config.goDatacenter configuration
control_plane.goControlPlane interface
controlplane/nats/NATS JetStream control plane
controlplane/etcd/etcd control plane

​
client/

Standalone cluster client for callers outside the actor system. See Client for full documentation.
FilePurpose
client.goClient: Tell, Ask, Spawn
balancer.goBalancer interface
round_robin.goRound-robin node selection
random.goRandom node selection
least_load.goLeast-loaded node selection

​
Internal packages

PackagePurpose
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
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/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

PackageDepends on
actorremote, internal/cluster, discovery/*, datacenter, crdt, supervisor, passivation, reentrancy, eventstream, extension, log, errors, internal/*
remoteinternal/net, internal/codec
internal/clusterdiscovery, internal/memberlist, hash
clientremote, internal/address
streamactor
log, errors, extension, eventstream, supervisor, passivation, reentrancy, hash, breaker, memory, tls, and crdt are leaf packages—they depend on nothing else in this repository.

​
See also