# erofs/erofs-utils architecture

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

- Interactive diagram: https://gitdiagram.com/erofs/erofs-utils
- Repository: https://github.com/erofs/erofs-utils

## Overview

erofs-utils provides tools to create, mount, analyze, and check EROFS filesystem images. The main workflow is to format source files into an image, then expose that image through a kernel mount or FUSE; dump and fsck provide inspection, verification, and extraction paths. Shared filesystem-reading and format logic is represented as an internal layer. The README documents the tools, while sampled excerpts are partial, so uncertain internal calls and optional backend wiring are omitted.

Main entry points: [`mount/main.c`](https://github.com/erofs/erofs-utils/blob/dev/mount/main.c) (mount.erofs), [`fuse/main.c`](https://github.com/erofs/erofs-utils/blob/dev/fuse/main.c) (FUSE daemon), [`fsck/main.c`](https://github.com/erofs/erofs-utils/blob/dev/fsck/main.c) (Checker and extractor), [`mkfs/main.c`](https://github.com/erofs/erofs-utils/blob/dev/mkfs/main.c) (mkfs.erofs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_format["Image creation"]
  node_mkfs["mkfs.erofs<br/>[main.c]"]
end

subgraph group_access["Image access"]
  node_mount["mount.erofs<br/>[main.c]"]
  node_fuse["FUSE daemon<br/>[main.c]"]
end

subgraph group_inspect["Inspection and recovery"]
  node_dump["Image analyzer<br/>[main.c]"]
  node_fsck["Checker and extractor<br/>[main.c]"]
end

subgraph group_core["Filesystem core"]
  node_importer["File importer<br/>[importer.c]"]
  node_compress["Compression<br/>[compress.c]"]
  node_fragments["Packed fragments<br/>[fragments.c]"]
  node_io["Image I/O<br/>[io.c]"]
  node_inode["Inode access<br/>[inode.c]"]
  node_directory["Directory access<br/>[dir.c]"]
  node_decompress["Decompression<br/>[decompress.c]"]
  node_xattr["Extended attributes<br/>[xattr.c]"]
end

subgraph group_remote["Remote backends"]
  node_oci["OCI remote images<br/>[oci.c]"]
  node_s3["S3 storage<br/>[s3.c]"]
  node_nbd["NBD backend<br/>[nbd.c]"]
  node_ublk["ublk backend<br/>[ublk.c]"]
end

node_source["Source files"]
node_image["EROFS image"]
node_kernel(("Kernel mount"))
node_fuseclient(("FUSE client"))

node_source -->|"formats"| node_mkfs
node_mkfs -->|"imports files"| node_importer
node_mkfs -->|"configures compression"| node_compress
node_importer -->|"packs fragments"| node_fragments
node_mkfs -->|"writes image"| node_image
node_image -->|"mounts"| node_mount
node_mount -->|"requests mount"| node_kernel
node_image -->|"serves image"| node_fuse
node_fuseclient -->|"requests files"| node_fuse
node_fuse -->|"reads image"| node_io
node_fuse -->|"looks up inodes"| node_inode
node_fuse -->|"reads directories"| node_directory
node_fuse -->|"serves attributes"| node_xattr
node_image -->|"analyzes"| node_dump
node_dump -->|"reads image"| node_io
node_dump -->|"reads metadata"| node_inode
node_image -->|"checks or extracts"| node_fsck
node_fsck -->|"reads image"| node_io
node_fsck -->|"checks inodes"| node_inode
node_fsck -->|"verifies data"| node_decompress
node_fsck -->|"checks attributes"| node_xattr
node_mount -.->|"uses OCI source"| node_oci
node_mount -.->|"serves NBD"| node_nbd
node_mount -.->|"uses S3 source"| node_s3
node_mount -.->|"uses ublk backend"| node_ublk
node_oci -.-> node_s3

click node_mkfs "https://github.com/erofs/erofs-utils/blob/dev/mkfs/main.c"
click node_importer "https://github.com/erofs/erofs-utils/blob/dev/lib/importer.c"
click node_compress "https://github.com/erofs/erofs-utils/blob/dev/lib/compress.c"
click node_fragments "https://github.com/erofs/erofs-utils/blob/dev/lib/fragments.c"
click node_mount "https://github.com/erofs/erofs-utils/blob/dev/mount/main.c"
click node_fuse "https://github.com/erofs/erofs-utils/blob/dev/fuse/main.c"
click node_dump "https://github.com/erofs/erofs-utils/blob/dev/dump/main.c"
click node_fsck "https://github.com/erofs/erofs-utils/blob/dev/fsck/main.c"
click node_io "https://github.com/erofs/erofs-utils/blob/dev/lib/io.c"
click node_inode "https://github.com/erofs/erofs-utils/blob/dev/lib/inode.c"
click node_directory "https://github.com/erofs/erofs-utils/blob/dev/lib/dir.c"
click node_decompress "https://github.com/erofs/erofs-utils/blob/dev/lib/decompress.c"
click node_xattr "https://github.com/erofs/erofs-utils/blob/dev/lib/xattr.c"
click node_oci "https://github.com/erofs/erofs-utils/blob/dev/lib/remotes/oci.c"
click node_s3 "https://github.com/erofs/erofs-utils/blob/dev/lib/remotes/s3.c"
click node_nbd "https://github.com/erofs/erofs-utils/blob/dev/lib/backends/nbd.c"
click node_ublk "https://github.com/erofs/erofs-utils/blob/dev/lib/backends/ublk.c"

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_mkfs,node_fuseclient toneBlue
class node_mount,node_fuse toneAmber
class node_dump,node_fsck toneMint
class node_importer,node_compress,node_fragments,node_io,node_inode,node_directory,node_decompress,node_xattr toneRose
class node_oci,node_s3,node_nbd,node_ublk,node_source,node_image,node_kernel toneIndigo
```

## Components

### Image creation

- [mkfs.erofs](https://github.com/erofs/erofs-utils/blob/dev/mkfs/main.c): `mkfs/main.c`

### Image access

- [mount.erofs](https://github.com/erofs/erofs-utils/blob/dev/mount/main.c): `mount/main.c`
- [FUSE daemon](https://github.com/erofs/erofs-utils/blob/dev/fuse/main.c): `fuse/main.c`

### Inspection and recovery

- [Image analyzer](https://github.com/erofs/erofs-utils/blob/dev/dump/main.c): `dump/main.c`
- [Checker and extractor](https://github.com/erofs/erofs-utils/blob/dev/fsck/main.c): `fsck/main.c`

### Filesystem core

- [File importer](https://github.com/erofs/erofs-utils/blob/dev/lib/importer.c): `lib/importer.c`
- [Compression](https://github.com/erofs/erofs-utils/blob/dev/lib/compress.c): `lib/compress.c`
- [Packed fragments](https://github.com/erofs/erofs-utils/blob/dev/lib/fragments.c): `lib/fragments.c`
- [Image I/O](https://github.com/erofs/erofs-utils/blob/dev/lib/io.c): `lib/io.c`
- [Inode access](https://github.com/erofs/erofs-utils/blob/dev/lib/inode.c): `lib/inode.c`
- [Directory access](https://github.com/erofs/erofs-utils/blob/dev/lib/dir.c): `lib/dir.c`
- [Decompression](https://github.com/erofs/erofs-utils/blob/dev/lib/decompress.c): `lib/decompress.c`
- [Extended attributes](https://github.com/erofs/erofs-utils/blob/dev/lib/xattr.c): `lib/xattr.c`

### Remote backends

- [OCI remote images](https://github.com/erofs/erofs-utils/blob/dev/lib/remotes/oci.c): `lib/remotes/oci.c`
- [S3 storage](https://github.com/erofs/erofs-utils/blob/dev/lib/remotes/s3.c): `lib/remotes/s3.c`
- [NBD backend](https://github.com/erofs/erofs-utils/blob/dev/lib/backends/nbd.c): `lib/backends/nbd.c`
- [ublk backend](https://github.com/erofs/erofs-utils/blob/dev/lib/backends/ublk.c): `lib/backends/ublk.c`

### Other components

- **Source files**
- **EROFS image**
- **Kernel mount**
- **FUSE client**

## Connections

- Source files → mkfs.erofs: formats
- mkfs.erofs → File importer: imports files
- mkfs.erofs → Compression: configures compression
- File importer → Packed fragments: packs fragments
- mkfs.erofs → EROFS image: writes image
- EROFS image → mount.erofs: mounts
- mount.erofs → Kernel mount: requests mount
- EROFS image → FUSE daemon: serves image
- FUSE client → FUSE daemon: requests files
- FUSE daemon → Image I/O: reads image
- FUSE daemon → Inode access: looks up inodes
- FUSE daemon → Directory access: reads directories
- FUSE daemon → Extended attributes: serves attributes
- EROFS image → Image analyzer: analyzes
- Image analyzer → Image I/O: reads image
- Image analyzer → Inode access: reads metadata
- EROFS image → Checker and extractor: checks or extracts
- Checker and extractor → Image I/O: reads image
- Checker and extractor → Inode access: checks inodes
- Checker and extractor → Decompression: verifies data
- Checker and extractor → Extended attributes: checks attributes
- mount.erofs → OCI remote images: uses OCI source
- mount.erofs → NBD backend: serves NBD
- mount.erofs → S3 storage: uses S3 source
- mount.erofs → ublk backend: uses ublk backend
- OCI remote images → S3 storage