GraphDSL

GraphDSL is a domain-specific language embedded in Akka Streams that provides a structured way to compose processing graphs from sources, flows, and sinks. It extends the basic linear API by allowing arbitrary graph shapes, including fan-out and fan-in patterns, to be built and manipulated as a single RunnableGraph. The DSL is available in both Scala and Java APIs and is widely used for modular, reusable stream topologies.

Core concept is a builder that exposes a small set of wiring primitives. The builder.add method incorporates a stage into the graph, and ports on stages are connected with the ~> operator (Scala) or a similar API in Java. This wiring is performed inside a GraphDSL.create block, which returns a RunnableGraph or another Graph when materialized. GraphDSL also provides standard junctions such as Broadcast, Merge, Zip, and Balance that enable branching, merging, and load balancing within the graph.

Typical uses include assembling complex processing pipelines that cannot be expressed with a single Flow or simple Source–Sink chain, such as parallel processing paths, coordinated merges, or custom fan-in/fan-out topologies. GraphDSL promotes modularity by letting developers build small reusable components and connect them in different configurations. Because the GraphDSL preserves the materialized values from its components, it is possible to wire graphs so that resources or results are materialized at the right stage.

References to GraphDSL appear in the Akka Streams documentation under GraphDSL and the Scala DSL (akka.stream.scaladsl.GraphDSL) or Java DSL (akka.stream.javadsl.GraphDSL). It remains a core tool for constructing complex, non-linear stream graphs in a type-safe, declarative style.