# cloudflare/utahfs architecture

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

- Interactive diagram: https://gitdiagram.com/cloudflare/utahfs
- Repository: https://github.com/cloudflare/utahfs

## Overview

UtahFS presents encrypted cloud-backed files as a local drive: a user mounts it, interacts with files through FUSE, and the client persists block data through configurable storage layers. The README also describes archive protection, a LAN coordination/cache server, a web UI, and optional ORAM. The graph shows the sampled client setup and storage construction; source excerpts do not establish every internal call between filesystem layers or the server and remote client, so those links are omitted or marked unverified.

Main entry points: [`cmd/internal/config/config.go`](https://github.com/cloudflare/utahfs/blob/master/cmd/internal/config/config.go) (Storage configuration), [`cmd/utahfs-client/main.go`](https://github.com/cloudflare/utahfs/blob/master/cmd/utahfs-client/main.go) (FUSE client), [`cmd/utahfs-web/main.go`](https://github.com/cloudflare/utahfs/blob/master/cmd/utahfs-web/main.go) (Web UI), [`blockfs.go`](https://github.com/cloudflare/utahfs/blob/master/blockfs.go) (Block filesystem)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_client["FUSE client<br/>[main.go]"]
  node_web["Web UI<br/>[main.go]"]
  node_webfs["HTTP filesystem adapter<br/>[filesystem.go]"]
end

subgraph group_filesystem["Filesystem runtime"]
  node_archive["Archive mode<br/>[archive.go]"]
  node_filesystem_api["Filesystem operations<br/>[filesystem.go]"]
  node_nodes["File node manager<br/>[node_manager.go]"]
  node_blockfs["Block filesystem<br/>[blockfs.go]"]
end

subgraph group_storage["Storage pipeline"]
  node_config["Storage configuration<br/>[config.go]"]
  node_appstorage["Application storage<br/>[app_storage.go]"]
  node_encryption["Encryption<br/>[encryption.go]"]
  node_integrity["Integrity protection<br/>[integrity.go]"]
  node_oram["Oblivious access<br/>[oblivious.go]"]
  node_wal["Write-ahead log<br/>[local_wal.go]"]
  node_cache["Storage caches"]
end

subgraph group_backends["Storage backends"]
  node_providers["Object storage providers"]
  node_disk["Local disk storage<br/>[disk.go]"]
  node_remote["Remote storage client<br/>[remote.go]"]
end

subgraph group_services["Coordination services"]
  node_server["LAN coordination server<br/>[main.go]"]
end

node_user(("Drive user"))
node_cloud[("Cloud object storage")]

node_user -->|"mounts drive"| node_client
node_client -->|"loads configuration"| node_config
node_client -->|"selects filesystem"| node_filesystem_api
node_client -->|"selects archive mode"| node_archive
node_web -->|"loads configuration"| node_config
node_web -->|"creates archive view"| node_archive
node_web -->|"serves through"| node_webfs
node_webfs -.->|"exposes over HTTP"| node_filesystem_api
node_nodes -->|"reads and writes blocks"| node_blockfs
node_config -->|"selects provider"| node_providers
node_config -->|"configures local WAL"| node_wal
node_config -->|"configures caching"| node_cache
node_config -->|"wraps with integrity"| node_integrity
node_config -->|"wraps with encryption"| node_encryption
node_config -->|"optionally enables ORAM"| node_oram
node_config -->|"creates application storage"| node_appstorage
node_config -->|"creates block filesystem"| node_blockfs
node_blockfs -->|"reads and writes blocks"| node_appstorage
node_providers -.->|"stores encrypted objects"| node_cloud
node_config -->|"can select local disk"| node_disk
node_config -.->|"can use remote server"| node_remote
node_server -.->|"coordinates clients"| node_remote

click node_client "https://github.com/cloudflare/utahfs/blob/master/cmd/utahfs-client/main.go"
click node_web "https://github.com/cloudflare/utahfs/blob/master/cmd/utahfs-web/main.go"
click node_webfs "https://github.com/cloudflare/utahfs/blob/master/cmd/utahfs-web/filesystem.go"
click node_archive "https://github.com/cloudflare/utahfs/blob/master/archive.go"
click node_filesystem_api "https://github.com/cloudflare/utahfs/blob/master/filesystem.go"
click node_nodes "https://github.com/cloudflare/utahfs/blob/master/node_manager.go"
click node_blockfs "https://github.com/cloudflare/utahfs/blob/master/blockfs.go"
click node_config "https://github.com/cloudflare/utahfs/blob/master/cmd/internal/config/config.go"
click node_appstorage "https://github.com/cloudflare/utahfs/blob/master/persistent/app_storage.go"
click node_encryption "https://github.com/cloudflare/utahfs/blob/master/persistent/encryption.go"
click node_integrity "https://github.com/cloudflare/utahfs/blob/master/persistent/integrity.go"
click node_oram "https://github.com/cloudflare/utahfs/blob/master/persistent/oblivious.go"
click node_wal "https://github.com/cloudflare/utahfs/blob/master/persistent/local_wal.go"
click node_cache "https://github.com/cloudflare/utahfs/tree/master/persistent"
click node_providers "https://github.com/cloudflare/utahfs/tree/master/persistent"
click node_disk "https://github.com/cloudflare/utahfs/blob/master/persistent/disk.go"
click node_remote "https://github.com/cloudflare/utahfs/blob/master/persistent/remote.go"
click node_server "https://github.com/cloudflare/utahfs/blob/master/cmd/utahfs-server/main.go"

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_client,node_web,node_webfs,node_user toneBlue
class node_archive,node_filesystem_api,node_nodes,node_blockfs,node_cloud toneAmber
class node_config,node_appstorage,node_encryption,node_integrity,node_oram,node_wal,node_cache toneMint
class node_providers,node_disk,node_remote toneRose
class node_server toneIndigo
```

## Components

### User interfaces

- [FUSE client](https://github.com/cloudflare/utahfs/blob/master/cmd/utahfs-client/main.go): `cmd/utahfs-client/main.go`
- [Web UI](https://github.com/cloudflare/utahfs/blob/master/cmd/utahfs-web/main.go): `cmd/utahfs-web/main.go`
- [HTTP filesystem adapter](https://github.com/cloudflare/utahfs/blob/master/cmd/utahfs-web/filesystem.go): `cmd/utahfs-web/filesystem.go`

### Filesystem runtime

- [Archive mode](https://github.com/cloudflare/utahfs/blob/master/archive.go): `archive.go`
- [Filesystem operations](https://github.com/cloudflare/utahfs/blob/master/filesystem.go): `filesystem.go`
- [File node manager](https://github.com/cloudflare/utahfs/blob/master/node_manager.go): `node_manager.go`
- [Block filesystem](https://github.com/cloudflare/utahfs/blob/master/blockfs.go): `blockfs.go`

### Storage pipeline

- [Storage configuration](https://github.com/cloudflare/utahfs/blob/master/cmd/internal/config/config.go): `cmd/internal/config/config.go`
- [Application storage](https://github.com/cloudflare/utahfs/blob/master/persistent/app_storage.go): `persistent/app_storage.go`
- [Encryption](https://github.com/cloudflare/utahfs/blob/master/persistent/encryption.go): `persistent/encryption.go`
- [Integrity protection](https://github.com/cloudflare/utahfs/blob/master/persistent/integrity.go): `persistent/integrity.go`
- [Oblivious access](https://github.com/cloudflare/utahfs/blob/master/persistent/oblivious.go): `persistent/oblivious.go`
- [Write-ahead log](https://github.com/cloudflare/utahfs/blob/master/persistent/local_wal.go): `persistent/local_wal.go`
- [Storage caches](https://github.com/cloudflare/utahfs/tree/master/persistent): `persistent`

### Storage backends

- [Object storage providers](https://github.com/cloudflare/utahfs/tree/master/persistent): `persistent`
- [Local disk storage](https://github.com/cloudflare/utahfs/blob/master/persistent/disk.go): `persistent/disk.go`
- [Remote storage client](https://github.com/cloudflare/utahfs/blob/master/persistent/remote.go): `persistent/remote.go`

### Coordination services

- [LAN coordination server](https://github.com/cloudflare/utahfs/blob/master/cmd/utahfs-server/main.go): `cmd/utahfs-server/main.go`

### Other components

- **Drive user**
- **Cloud object storage**

## Connections

- Drive user → FUSE client: mounts drive (evidence: `README.md`)
- FUSE client → Storage configuration: loads configuration (evidence: `cmd/utahfs-client/main.go`)
- FUSE client → Filesystem operations: selects filesystem (evidence: `cmd/utahfs-client/main.go`)
- FUSE client → Archive mode: selects archive mode (evidence: `cmd/utahfs-client/main.go`)
- Web UI → Storage configuration: loads configuration (evidence: `cmd/utahfs-web/main.go`)
- Web UI → Archive mode: creates archive view (evidence: `cmd/utahfs-web/main.go`)
- Web UI → HTTP filesystem adapter: serves through (evidence: `cmd/utahfs-web/main.go`)
- HTTP filesystem adapter → Filesystem operations: exposes over HTTP
- File node manager → Block filesystem: reads and writes blocks (evidence: `node_manager.go`)
- Storage configuration → Object storage providers: selects provider (evidence: `cmd/internal/config/config.go`)
- Storage configuration → Write-ahead log: configures local WAL (evidence: `cmd/internal/config/config.go`)
- Storage configuration → Storage caches: configures caching (evidence: `cmd/internal/config/config.go`)
- Storage configuration → Integrity protection: wraps with integrity (evidence: `cmd/internal/config/config.go`)
- Storage configuration → Encryption: wraps with encryption (evidence: `cmd/internal/config/config.go`)
- Storage configuration → Oblivious access: optionally enables ORAM (evidence: `cmd/internal/config/config.go`)
- Storage configuration → Application storage: creates application storage (evidence: `cmd/internal/config/config.go`)
- Storage configuration → Block filesystem: creates block filesystem (evidence: `cmd/internal/config/config.go`)
- Block filesystem → Application storage: reads and writes blocks (evidence: `blockfs.go`)
- Object storage providers → Cloud object storage: stores encrypted objects (evidence: `README.md`)
- Storage configuration → Local disk storage: can select local disk (evidence: `cmd/internal/config/config.go`)
- Storage configuration → Remote storage client: can use remote server
- LAN coordination server → Remote storage client: coordinates clients
