# apache/pekko architecture

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

- Interactive diagram: https://gitdiagram.com/apache/pekko
- Repository: https://github.com/apache/pekko

## Overview

Apache Pekko is a framework for concurrent, distributed, resilient applications built around the Actor Model, with persistence, streams, HTTP, and other libraries. A principal runtime path is application code defining actor behavior and using an actor system to run it, then exchanging messages through actor references; the typed-delivery branch adds consumer-driven flow control and optional durable producer storage. The graph also preserves major documented library areas and representative runtime infrastructure. Evidence is limited to the README and sampled excerpts; unsampled subsystem links are omitted rather than inferred.

Main entry points: [`actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/ProducerController.scala`](https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/ProducerController.scala) (Producer Controller), [`actor/src/main/scala/org/apache/pekko/actor/ActorSystem.scala`](https://github.com/apache/pekko/blob/main/actor/src/main/scala/org/apache/pekko/actor/ActorSystem.scala) (Classic Actor System), [`actor/src/main/scala/org/apache/pekko/actor/Actor.scala`](https://github.com/apache/pekko/blob/main/actor/src/main/scala/org/apache/pekko/actor/Actor.scala) (Classic Actors), [`actor-typed/src/main/scala/org/apache/pekko/actor/typed/ActorSystem.scala`](https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/ActorSystem.scala) (Typed Actor System)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_actor_runtime["Actor Runtime"]
  node_classic_system["Classic Actor System<br/>[ActorSystem.scala]"]
  node_classic_actor["Classic Actors<br/>[Actor.scala]"]
  node_typed_system["Typed Actor System<br/>[ActorSystem.scala]"]
  node_typed_behavior["Typed Behaviors<br/>[Behaviors.scala]"]
  node_typed_ref["Typed Actor Ref<br/>[ActorRef.scala]"]
  node_supervision["Supervision"]
  node_dispatch["Dispatching<br/>[Dispatcher.scala]"]
  node_logging["Logging<br/>[Logging.scala]"]
end

subgraph group_typed_delivery["Typed Delivery"]
  node_typed_producer["Producer Controller"]
  node_producer_impl["Producer Runtime"]
  node_consumer["Consumer Controller"]
  node_durable_queue["Durable Queue API"]
end

subgraph group_cluster["Cluster Coordination"]
  node_cluster_singleton["Cluster Singleton"]
end

subgraph group_libraries["Application Libraries"]
  node_persistence["Persistence"]
  node_streams["Streams"]
  node_http["HTTP"]
end

node_application(("Application"))

node_application -->|"starts actors"| node_classic_system
node_application -->|"uses actor model"| node_typed_system
node_application -->|"defines behavior"| node_typed_behavior
node_classic_system -->|"creates actors"| node_classic_actor
node_application -->|"sends messages"| node_typed_ref
node_application -->|"uses delivery"| node_typed_producer
node_typed_producer -->|"coordinates demand"| node_consumer
node_typed_producer -->|"stores unconfirmed"| node_durable_queue
node_typed_producer -->|"implemented by"| node_producer_impl
node_application -->|"uses coordination"| node_cluster_singleton
node_application -->|"uses persistence"| node_persistence
node_application -->|"uses streams"| node_streams
node_application -->|"uses HTTP"| node_http

click node_classic_system "https://github.com/apache/pekko/blob/main/actor/src/main/scala/org/apache/pekko/actor/ActorSystem.scala"
click node_classic_actor "https://github.com/apache/pekko/blob/main/actor/src/main/scala/org/apache/pekko/actor/Actor.scala"
click node_typed_system "https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/ActorSystem.scala"
click node_typed_behavior "https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/scaladsl/Behaviors.scala"
click node_typed_ref "https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/ActorRef.scala"
click node_supervision "https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/SupervisorStrategy.scala"
click node_dispatch "https://github.com/apache/pekko/blob/main/actor/src/main/scala/org/apache/pekko/dispatch/Dispatcher.scala"
click node_logging "https://github.com/apache/pekko/blob/main/actor/src/main/scala/org/apache/pekko/event/Logging.scala"
click node_typed_producer "https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/ProducerController.scala"
click node_producer_impl "https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/internal/ProducerControllerImpl.scala"
click node_consumer "https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/ConsumerController.scala"
click node_durable_queue "https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/DurableProducerQueue.scala"
click node_cluster_singleton "https://github.com/apache/pekko/blob/main/cluster-tools/src/main/scala/org/apache/pekko/cluster/singleton/ClusterSingletonManager.scala"
click node_persistence "https://github.com/apache/pekko/tree/main/persistence-typed/src/main/scala/org/apache/pekko/persistence/typed"
click node_streams "https://github.com/apache/pekko/tree/main/stream/src/main/scala/org/apache/pekko/stream"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_classic_system,node_classic_actor,node_typed_system,node_typed_behavior,node_typed_ref,node_supervision,node_dispatch,node_logging toneBlue
class node_typed_producer,node_producer_impl,node_consumer,node_durable_queue toneAmber
class node_cluster_singleton toneMint
class node_persistence,node_streams,node_http toneRose
class node_application toneIndigo
```

## Components

### Actor Runtime

- [Classic Actor System](https://github.com/apache/pekko/blob/main/actor/src/main/scala/org/apache/pekko/actor/ActorSystem.scala): `actor/src/main/scala/org/apache/pekko/actor/ActorSystem.scala`
- [Classic Actors](https://github.com/apache/pekko/blob/main/actor/src/main/scala/org/apache/pekko/actor/Actor.scala): `actor/src/main/scala/org/apache/pekko/actor/Actor.scala`
- [Typed Actor System](https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/ActorSystem.scala): `actor-typed/src/main/scala/org/apache/pekko/actor/typed/ActorSystem.scala`
- [Typed Behaviors](https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/scaladsl/Behaviors.scala): `actor-typed/src/main/scala/org/apache/pekko/actor/typed/scaladsl/Behaviors.scala`
- [Typed Actor Ref](https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/ActorRef.scala): `actor-typed/src/main/scala/org/apache/pekko/actor/typed/ActorRef.scala`
- [Supervision](https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/SupervisorStrategy.scala): `actor-typed/src/main/scala/org/apache/pekko/actor/typed/SupervisorStrategy.scala`
- [Dispatching](https://github.com/apache/pekko/blob/main/actor/src/main/scala/org/apache/pekko/dispatch/Dispatcher.scala): `actor/src/main/scala/org/apache/pekko/dispatch/Dispatcher.scala`
- [Logging](https://github.com/apache/pekko/blob/main/actor/src/main/scala/org/apache/pekko/event/Logging.scala): `actor/src/main/scala/org/apache/pekko/event/Logging.scala`

### Typed Delivery

- [Producer Controller](https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/ProducerController.scala): `actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/ProducerController.scala`
- [Producer Runtime](https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/internal/ProducerControllerImpl.scala): `actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/internal/ProducerControllerImpl.scala`
- [Consumer Controller](https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/ConsumerController.scala): `actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/ConsumerController.scala`
- [Durable Queue API](https://github.com/apache/pekko/blob/main/actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/DurableProducerQueue.scala): `actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/DurableProducerQueue.scala`

### Cluster Coordination

- [Cluster Singleton](https://github.com/apache/pekko/blob/main/cluster-tools/src/main/scala/org/apache/pekko/cluster/singleton/ClusterSingletonManager.scala): `cluster-tools/src/main/scala/org/apache/pekko/cluster/singleton/ClusterSingletonManager.scala`

### Application Libraries

- [Persistence](https://github.com/apache/pekko/tree/main/persistence-typed/src/main/scala/org/apache/pekko/persistence/typed): `persistence-typed/src/main/scala/org/apache/pekko/persistence/typed`
- [Streams](https://github.com/apache/pekko/tree/main/stream/src/main/scala/org/apache/pekko/stream): `stream/src/main/scala/org/apache/pekko/stream`
- **HTTP**

### Other components

- **Application**

## Connections

- Application → Classic Actor System: starts actors (evidence: `actor/src/main/scala/org/apache/pekko/actor/ActorSystem.scala`)
- Application → Typed Actor System: uses actor model
- Application → Typed Behaviors: defines behavior
- Classic Actor System → Classic Actors: creates actors (evidence: `actor/src/main/scala/org/apache/pekko/actor/ActorSystem.scala`)
- Application → Typed Actor Ref: sends messages (evidence: `actor-typed/src/main/scala/org/apache/pekko/actor/typed/ActorRef.scala`)
- Application → Producer Controller: uses delivery (evidence: `actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/ProducerController.scala`)
- Producer Controller → Consumer Controller: coordinates demand (evidence: `actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/ProducerController.scala`)
- Producer Controller → Durable Queue API: stores unconfirmed (evidence: `actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/ProducerController.scala`)
- Producer Controller → Producer Runtime: implemented by (evidence: `actor-typed/src/main/scala/org/apache/pekko/actor/typed/delivery/internal/ProducerControllerImpl.scala`)
- Application → Cluster Singleton: uses coordination
- Application → Persistence: uses persistence
- Application → Streams: uses streams
- Application → HTTP: uses HTTP
