# typelevel/fs2 architecture

> Architecture diagram of the GitHub repository typelevel/fs2, 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/typelevel/fs2
- Repository: https://github.com/typelevel/fs2

## Overview

FS2 is a Scala library for effectful, compositional stream processing. Its primary workflow is that application code constructs a Stream, uses Pull for lower-level stream transformations, then compiles or runs the stream; internal scopes support resource safety. The repository also provides concurrency primitives, platform-specific I/O, compression and hashing, protocol codecs, and integrations with stream-processing APIs. The README establishes the product and supported platforms; the source index and excerpts support the cited internal relationships. Unsampled subsystems are represented without asserting unverified call paths.

Main entry points: [`core/shared/src/main/scala/fs2/Stream.scala`](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/Stream.scala) (Stream API), [`io/shared/src/main/scala/fs2/io/net/Socket.scala`](https://github.com/typelevel/fs2/blob/main/io/shared/src/main/scala/fs2/io/net/Socket.scala) (Socket API), [`io/shared/src/main/scala/fs2/io/net/tls/TLSContext.scala`](https://github.com/typelevel/fs2/blob/main/io/shared/src/main/scala/fs2/io/net/tls/TLSContext.scala) (TLS context), [`io/shared/src/main/scala/fs2/io/file/Files.scala`](https://github.com/typelevel/fs2/blob/main/io/shared/src/main/scala/fs2/io/file/Files.scala) (File operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Stream core"]
  node_stream["Stream API<br/>[Stream.scala]"]
  node_pull["Pull operations<br/>[Pull.scala]"]
  node_compiler["Stream compiler<br/>[Compiler.scala]"]
  node_scope["Resource scopes<br/>[Scope.scala]"]
  node_failure["Stream errors<br/>[Fallible.scala]"]
  node_raise["Error capability"]
end

subgraph group_concurrency["Concurrency"]
  node_channel["Channel<br/>[Channel.scala]"]
  node_signal["Signal<br/>[Signal.scala]"]
  node_topic["Topic<br/>[Topic.scala]"]
end

subgraph group_io["I/O"]
  node_files["File operations<br/>[Files.scala]"]
  node_filehandle["File handles<br/>[FileHandle.scala]"]
  node_watcher["File watching<br/>[Watcher.scala]"]
  node_socket["Socket API<br/>[Socket.scala]"]
  node_tls["TLS context<br/>[TLSContext.scala]"]
  node_tlsjvm["JVM TLS engine<br/>[TLSEngine.scala]"]
  node_tlsjs["JS TLS platform"]
end

subgraph group_data["Data processing"]
  node_compression["Compression<br/>[Compression.scala]"]
  node_hashing["Hashing<br/>[Hashing.scala]"]
  node_protocols["Protocol codecs"]
end

subgraph group_interop["Interoperability"]
  node_flow["Java Flow interop"]
  node_reactive["Reactive Streams"]
  node_scodec["scodec interop"]
end

node_app(("Application code"))
node_external(("External byte source"))

node_app -->|"constructs streams"| node_stream
node_stream -->|"uses pulls"| node_pull
node_stream -->|"compiles streams"| node_compiler
node_pull -->|"manages scopes"| node_scope
node_stream -->|"uses scopes"| node_scope
node_failure -->|"requires capability"| node_raise
node_stream -->|"uses channel"| node_channel
node_stream -->|"uses signal"| node_signal
node_stream -->|"uses topic"| node_topic
node_files -->|"returns streams"| node_stream
node_files -->|"opens handles"| node_filehandle
node_watcher -->|"uses file API"| node_files
node_socket -->|"exposes byte streams"| node_stream
node_tls -->|"wraps sockets"| node_socket
node_tls -.->|"platform implementation"| node_tlsjvm
node_tlsjs -->|"builds TLS sockets"| node_socket
node_tls -.->|"platform implementation"| node_tlsjs
node_compression -.->|"transforms streams"| node_stream
node_hashing -.->|"hashes streams"| node_stream
node_protocols -.->|"processes stream data"| node_stream
node_flow -->|"publishes streams"| node_stream
node_reactive -->|"adapts streams"| node_stream
node_scodec -->|"decodes streams"| node_stream
node_external -.->|"supplies bytes"| node_socket

click node_stream "https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/Stream.scala"
click node_pull "https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/Pull.scala"
click node_compiler "https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/Compiler.scala"
click node_scope "https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/internal/Scope.scala"
click node_failure "https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/Fallible.scala"
click node_raise "https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/RaiseThrowable.scala"
click node_channel "https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/concurrent/Channel.scala"
click node_signal "https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/concurrent/Signal.scala"
click node_topic "https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/concurrent/Topic.scala"
click node_files "https://github.com/typelevel/fs2/blob/main/io/shared/src/main/scala/fs2/io/file/Files.scala"
click node_filehandle "https://github.com/typelevel/fs2/blob/main/io/shared/src/main/scala/fs2/io/file/FileHandle.scala"
click node_watcher "https://github.com/typelevel/fs2/blob/main/io/jvm-native/src/main/scala/fs2/io/file/Watcher.scala"
click node_socket "https://github.com/typelevel/fs2/blob/main/io/shared/src/main/scala/fs2/io/net/Socket.scala"
click node_tls "https://github.com/typelevel/fs2/blob/main/io/shared/src/main/scala/fs2/io/net/tls/TLSContext.scala"
click node_tlsjvm "https://github.com/typelevel/fs2/blob/main/io/jvm/src/main/scala/fs2/io/net/tls/TLSEngine.scala"
click node_tlsjs "https://github.com/typelevel/fs2/blob/main/io/js/src/main/scala/fs2/io/net/tls/TLSContextPlatform.scala"
click node_compression "https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/compression/Compression.scala"
click node_hashing "https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/hashing/Hashing.scala"
click node_protocols "https://github.com/typelevel/fs2/tree/main/protocols/shared/src/main/scala/fs2/protocols"
click node_flow "https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/interop/flow/StreamPublisher.scala"
click node_reactive "https://github.com/typelevel/fs2/blob/main/reactive-streams/src/main/scala/fs2/interop/reactivestreams/StreamSubscriber.scala"
click node_scodec "https://github.com/typelevel/fs2/blob/main/scodec/shared/src/main/scala/fs2/interop/scodec/StreamDecoder.scala"

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_stream,node_pull,node_compiler,node_scope,node_failure,node_raise toneBlue
class node_channel,node_signal,node_topic toneAmber
class node_files,node_filehandle,node_watcher,node_socket,node_tls,node_tlsjvm,node_tlsjs toneMint
class node_compression,node_hashing,node_protocols toneRose
class node_flow,node_reactive,node_scodec,node_app,node_external toneIndigo
```

## Components

### Stream core

- [Stream API](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/Stream.scala): `core/shared/src/main/scala/fs2/Stream.scala`
- [Pull operations](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/Pull.scala): `core/shared/src/main/scala/fs2/Pull.scala`
- [Stream compiler](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/Compiler.scala): `core/shared/src/main/scala/fs2/Compiler.scala`
- [Resource scopes](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/internal/Scope.scala): `core/shared/src/main/scala/fs2/internal/Scope.scala`
- [Stream errors](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/Fallible.scala): `core/shared/src/main/scala/fs2/Fallible.scala`
- [Error capability](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/RaiseThrowable.scala): `core/shared/src/main/scala/fs2/RaiseThrowable.scala`

### Concurrency

- [Channel](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/concurrent/Channel.scala): `core/shared/src/main/scala/fs2/concurrent/Channel.scala`
- [Signal](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/concurrent/Signal.scala): `core/shared/src/main/scala/fs2/concurrent/Signal.scala`
- [Topic](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/concurrent/Topic.scala): `core/shared/src/main/scala/fs2/concurrent/Topic.scala`

### I/O

- [File operations](https://github.com/typelevel/fs2/blob/main/io/shared/src/main/scala/fs2/io/file/Files.scala): `io/shared/src/main/scala/fs2/io/file/Files.scala`
- [File handles](https://github.com/typelevel/fs2/blob/main/io/shared/src/main/scala/fs2/io/file/FileHandle.scala): `io/shared/src/main/scala/fs2/io/file/FileHandle.scala`
- [File watching](https://github.com/typelevel/fs2/blob/main/io/jvm-native/src/main/scala/fs2/io/file/Watcher.scala): `io/jvm-native/src/main/scala/fs2/io/file/Watcher.scala`
- [Socket API](https://github.com/typelevel/fs2/blob/main/io/shared/src/main/scala/fs2/io/net/Socket.scala): `io/shared/src/main/scala/fs2/io/net/Socket.scala`
- [TLS context](https://github.com/typelevel/fs2/blob/main/io/shared/src/main/scala/fs2/io/net/tls/TLSContext.scala): `io/shared/src/main/scala/fs2/io/net/tls/TLSContext.scala`
- [JVM TLS engine](https://github.com/typelevel/fs2/blob/main/io/jvm/src/main/scala/fs2/io/net/tls/TLSEngine.scala): `io/jvm/src/main/scala/fs2/io/net/tls/TLSEngine.scala`
- [JS TLS platform](https://github.com/typelevel/fs2/blob/main/io/js/src/main/scala/fs2/io/net/tls/TLSContextPlatform.scala): `io/js/src/main/scala/fs2/io/net/tls/TLSContextPlatform.scala`

### Data processing

- [Compression](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/compression/Compression.scala): `core/shared/src/main/scala/fs2/compression/Compression.scala`
- [Hashing](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/hashing/Hashing.scala): `core/shared/src/main/scala/fs2/hashing/Hashing.scala`
- [Protocol codecs](https://github.com/typelevel/fs2/tree/main/protocols/shared/src/main/scala/fs2/protocols): `protocols/shared/src/main/scala/fs2/protocols`

### Interoperability

- [Java Flow interop](https://github.com/typelevel/fs2/blob/main/core/shared/src/main/scala/fs2/interop/flow/StreamPublisher.scala): `core/shared/src/main/scala/fs2/interop/flow/StreamPublisher.scala`
- [Reactive Streams](https://github.com/typelevel/fs2/blob/main/reactive-streams/src/main/scala/fs2/interop/reactivestreams/StreamSubscriber.scala): `reactive-streams/src/main/scala/fs2/interop/reactivestreams/StreamSubscriber.scala`
- [scodec interop](https://github.com/typelevel/fs2/blob/main/scodec/shared/src/main/scala/fs2/interop/scodec/StreamDecoder.scala): `scodec/shared/src/main/scala/fs2/interop/scodec/StreamDecoder.scala`

### Other components

- **Application code**
- **External byte source**

## Connections

- Application code → Stream API: constructs streams
- Stream API → Pull operations: uses pulls (evidence: `core/shared/src/main/scala/fs2/Stream.scala`)
- Stream API → Stream compiler: compiles streams (evidence: `core/shared/src/main/scala/fs2/Stream.scala`)
- Pull operations → Resource scopes: manages scopes (evidence: `core/shared/src/main/scala/fs2/Pull.scala`)
- Stream API → Resource scopes: uses scopes (evidence: `core/shared/src/main/scala/fs2/Stream.scala`)
- Stream errors → Error capability: requires capability (evidence: `core/shared/src/main/scala/fs2/Fallible.scala`)
- Stream API → Channel: uses channel (evidence: `core/shared/src/main/scala/fs2/Stream.scala`)
- Stream API → Signal: uses signal (evidence: `core/shared/src/main/scala/fs2/Stream.scala`)
- Stream API → Topic: uses topic (evidence: `core/shared/src/main/scala/fs2/Stream.scala`)
- File operations → Stream API: returns streams (evidence: `io/shared/src/main/scala/fs2/io/file/Files.scala`)
- File operations → File handles: opens handles (evidence: `io/shared/src/main/scala/fs2/io/file/Files.scala`)
- File watching → File operations: uses file API (evidence: `io/jvm-native/src/main/scala/fs2/io/DeprecatedWatcher.scala`)
- Socket API → Stream API: exposes byte streams (evidence: `io/shared/src/main/scala/fs2/io/net/Socket.scala`)
- TLS context → Socket API: wraps sockets (evidence: `io/shared/src/main/scala/fs2/io/net/tls/TLSContext.scala`)
- TLS context → JVM TLS engine: platform implementation
- JS TLS platform → Socket API: builds TLS sockets (evidence: `io/js/src/main/scala/fs2/io/net/tls/TLSContextPlatform.scala`)
- TLS context → JS TLS platform: platform implementation (evidence: `io/js/src/main/scala/fs2/io/net/tls/TLSContextPlatform.scala`)
- Compression → Stream API: transforms streams
- Hashing → Stream API: hashes streams
- Protocol codecs → Stream API: processes stream data
- Java Flow interop → Stream API: publishes streams (evidence: `core/shared/src/main/scala/fs2/Stream.scala`)
- Reactive Streams → Stream API: adapts streams (evidence: `reactive-streams/src/main/scala/fs2/interop/reactivestreams/StreamSubscriber.scala`)
- scodec interop → Stream API: decodes streams (evidence: `scodec/shared/src/main/scala/fs2/interop/scodec/StreamDecoder.scala`)
- External byte source → Socket API: supplies bytes
