Why architecture matters here
The architecture matters because concurrency bugs are the most expensive class of bug to find, and the actor model's whole promise is to make them structurally impossible: each actor processes one message at a time from its mailbox, so its internal state is never touched concurrently and you write single-threaded logic that runs safely under massive parallelism. But untyped actors gave away half that guarantee at the boundary. You could send any object to any actor; whether it was handled was a runtime property. In a large system with hundreds of message types, refactoring a protocol meant grepping for senders and praying, because the compiler was blind to who sent what. Typed actors restore compile-time discipline exactly where distributed systems are most fragile — the messages crossing between components.
The functional behavior style matters for a subtler reason: it makes an actor's state machine legible. When state is a mutable field, understanding 'what happens next' means reading the whole class and tracking every assignment; when state is encoded as which Behavior[T] is currently active, the transitions are explicit — a connection actor is literally disconnected, connecting, or connected, each a named behavior returning the next. This maps directly onto how you reason about protocols and makes illegal transitions (handling a data message while disconnected) something you can simply not define.
There is also a real ergonomic gain in how the typed API forces you to confront the actor's full protocol at compile time. In untyped Akka you could handle three message cases in receive and quietly ignore a fourth that some caller was sending; the mismatch surfaced only as an unhandled log entry under production load. With a sealed command trait and an exhaustive match, the compiler enumerates every case the actor must consider, so adding a new command to the protocol produces compile errors at exactly the actors that now need to handle it — the type system turns a protocol change into a checklist. This is the same discipline algebraic data types bring to domain modeling, applied to the messages flowing between concurrent components, and it is precisely the discipline distributed systems most often lack. The cost is that you cannot casually broaden a protocol; the benefit is that you cannot silently narrow one either, and in a codebase where the message graph is the architecture, that trade is the difference between confident refactoring and archaeology.
The rigidity is a deliberate trade. You must define protocols up front as sealed types, you must thread reply-to addresses explicitly because there is no untyped sender(), and you must adapt between protocols when actors with different message types collaborate. In exchange you get a system where the type of every mailbox is documented and enforced, where the IDE can navigate the message graph, and where a whole category of 'message went to the wrong actor' incidents cannot compile. For systems that live for years and are refactored continuously, that trade pays for itself repeatedly.
The architecture: every piece explained
Top row: defining and running an actor. The protocol is a sealed trait (or Scala 3 enum) enumerating every message the actor accepts — sealing it lets the compiler check exhaustive matching. A Behavior[T] is the actor's logic: Behaviors.receive { (context, message) => ... } inspects the incoming T and returns the next Behavior[T] — Behaviors.same to keep the current one, or a new behavior to transition state. The ActorRef[T] is the typed handle other code holds; its ! (tell) operator accepts only T, so sending the wrong message is a compile error. The ActorContext[T], passed into the behavior, is the actor's window on the runtime: it spawns typed children (context.spawn(childBehavior, "name") returning a child ActorRef), watches them for termination, schedules timers, and exposes context.self.
Middle row: the runtime mechanics. A message — typed and, by discipline, immutable — is delivered into the actor's mailbox, a per-actor queue. The dispatcher pulls one message at a time and invokes the current behavior, which performs a behavior transition by returning either the same or a new behavior; because only one message is processed at a time, the behavior's captured state needs no locks. Supervision wraps a behavior to define what happens on failure — restart (rebuild the behavior fresh), resume (drop the failing message and continue), or stop — and lifecycle signals like PostStop and Terminated (a watched child died) are delivered to a receiveSignal handler so cleanup is explicit.
Bottom rows: cross-actor communication and operations. Because mailboxes are typed, an actor expecting a reply cannot just read sender(); instead the ask pattern and message adapters create a small typed reply-address (ActorRef[Response]) that translates the callee's response type into a message the caller understands — the explicit wiring that replaces untyped magic. The receptionist is typed service discovery: actors register under a ServiceKey[T] and others subscribe to find current ActorRef[T]s, which is how you locate actors without hardcoding references, especially across a cluster. The ops strip lists the production surface: choosing dispatchers (thread pools) per workload, using bounded mailboxes to bound memory and apply backpressure, layering event-sourced persistence for durable state, and using cluster sharding to distribute millions of entity actors across nodes.
End-to-end flow
Build a small ordering service to see the pieces cooperate. Define the protocol as a sealed trait OrderCommand with cases PlaceOrder(item, replyTo: ActorRef[OrderResponse]), ConfirmPayment(id), and CancelOrder(id). The order actor starts in an idle behavior. When it receives PlaceOrder, it validates, spawns a child PaymentActor via context.spawn, sends the payment request with a message adapter as the reply-to, and returns an awaitingPayment(order) behavior — the state transition is a value returned, not a field mutated. In awaitingPayment, a ConfirmPayment transitions to confirmed and replies to the original caller through the stored replyTo: ActorRef[OrderResponse]; a CancelOrder transitions back to idle. A PlaceOrder arriving while already awaitingPayment is simply not a legal transition — the behavior can stash it or reject it, and either way the intent is explicit in the code.
Now the typed reply plumbing, which is where newcomers stumble. The PaymentActor speaks its own protocol (PaymentCommand) and replies with PaymentResult, a type the order actor does not accept. So the order actor creates a message adapter: context.messageAdapter[PaymentResult](r => WrappedPaymentResult(r)) returns an ActorRef[PaymentResult] it passes as the payment request's reply-to. When the payment actor replies, the adapter wraps the foreign PaymentResult into the order actor's own WrappedPaymentResult message, which its behavior handles. This is the typed replacement for untyped sender() ! result: every reply channel is an explicit, type-checked ActorRef, so the compiler guarantees the payment actor cannot accidentally send the order actor a message it does not understand.
Watch failure handling next. The order actor context.watches its payment child; if the child crashes, the order actor receives a Terminated signal and can transition to a paymentFailed behavior that notifies the customer and releases the reserved inventory. Supervision on the payment actor itself is declared where it is spawned: Behaviors.supervise(paymentBehavior).onFailure[TimeoutException](SupervisorStrategy.restart) means a transient timeout restarts a clean payment actor rather than propagating the failure. The lifecycle is explicit end to end — spawn, watch, supervise, signal — with no hidden runtime callbacks.
Finally scale it. Wrap the order actor in event-sourced persistence (EventSourcedBehavior) so its state survives restarts by replaying events, and place it behind cluster sharding keyed by order id, so millions of order entities distribute across the cluster and each id resolves to exactly one active actor somewhere in the fleet. The same typed protocol you compiled against locally is now the wire contract for a sharded, persistent, distributed service — the type safety follows the message across nodes.
One more transition is worth tracing, because it shows how behaviors compose. Suppose the payment succeeds but the warehouse service reports the item is out of stock. The confirmed behavior receives an OutOfStock message and must unwind: it transitions to a refunding behavior that spawns a refund child, and while refunding it stashes any new commands (a late CancelOrder, a duplicate ConfirmPayment) rather than handling them mid-unwind. When the refund completes, the behavior un-stashes the buffered messages and returns to idle. Each of these is a named behavior with an explicit, compile-checked set of messages it accepts, so the tangle of edge cases that would be scattered if-branches in a mutable actor becomes a small, readable state machine. Crucially, none of this required a lock, a shared flag, or a callback — the actor processed one message at a time, and each message simply chose the next behavior. That is the payoff of modeling state as behavior transitions: concurrency correctness by construction, and a protocol the compiler and the next engineer can both read off the code.