Code Map

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

Top-level layout

Package	Purpose
`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/`

Grouped by subsystem.

Core API and runtime

File	Purpose
`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.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`	`sync.Pool`s for hot-path allocations (ReceiveContext, etc.)
`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

See Dispatcher Pool for the full design.

File	Purpose
`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

File	Purpose
`mailbox.go`	`Mailbox` interface
`unbounded_mailbox.go`	Default MPSC FIFO mailbox
`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

File	Purpose
`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

File	Purpose
`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

File	Purpose
`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)

File	Purpose
`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_identity.go`	`GrainIdentity` with memoised validation (hot-path allocation fix)
`grain_mailbox.go`	Grain-specific mailbox with system-message priorities
`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

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

`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/CRDTs.md.

File	Purpose
`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`, …)
`gcounter.go`, `pncounter.go`, `lww_register.go`, `mv_register.go`, `or_set.go`, `or_map.go`, `flag.go`	CRDT implementations

`stream/`

Reactive pipelines (Source, Flow, Sink → RunnableGraph) materialized onto an ActorSystem with backpressure. See Streams and the repository architecture/REACTIVE_STREAMS.md.

File	Purpose
`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/`

Configuration, serializers, and wire helpers for the remoting layer. The remoting server lives at actor/remote_server.go; the remoting client lives at internal/remoteclient/.

File	Purpose
`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/`

Pluggable service discovery. Each sub-package implements discovery.Provider:

Provider	Backend
`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/`

File	Purpose
`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/`

Standalone cluster client for callers outside the actor system. See Client for full documentation.

File	Purpose
`client.go`	`Client`: Tell, Ask, Spawn, SendSync, ReSpawn, Stop
`option.go`	`Option` for `NewClient` (TLS, balancer, refresh, reentrancy, …)
`node.go`	`Node` — cluster-member endpoint metadata
`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

Package	Purpose
`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

Package	Depends on
`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`

log, errors, extension, eventstream, supervisor, passivation, reentrancy, hash, breaker, memory, tls, and crdt are leaf packages—they depend on nothing else in this repository.

Getting Started

Actor

Grains

Remoting

Cluster

Observability

Advanced

Architecture

Contribution

Reference

Meta Framework

Top-level layout

Key files in `actor/`

Core API and runtime

Scheduler — the dispatcher pool

Mailboxes

Behaviour, supervision, lifecycle

Guardians, routing, scheduling, scheduled delivery

Cluster, remoting, multi-DC

Grains (virtual actors)

CRDT replicator

`crdt/`

`stream/`

`remote/`

`discovery/`

`datacenter/`

`client/`

Internal packages

`protos/`

Dependency summary

See also

​Top-level layout

​Key files in actor/

​Core API and runtime

​Scheduler — the dispatcher pool

​Mailboxes

​Behaviour, supervision, lifecycle

​Guardians, routing, scheduling, scheduled delivery

​Cluster, remoting, multi-DC

​Grains (virtual actors)

​CRDT replicator

​crdt/

​stream/

​remote/

​discovery/

​datacenter/

​client/

​Internal packages

​protos/

​Dependency summary

​See also

Top-level layout

Key files in `actor/`

Core API and runtime

Scheduler — the dispatcher pool

Mailboxes

Behaviour, supervision, lifecycle

Guardians, routing, scheduling, scheduled delivery

Cluster, remoting, multi-DC

Grains (virtual actors)

CRDT replicator

`crdt/`

`stream/`

`remote/`

`discovery/`

`datacenter/`

`client/`

Internal packages

`protos/`

Dependency summary

See also