# cloudflare/artifact-fs architecture

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

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

## Overview

ArtifactFS is a Git-backed FUSE daemon that makes a repository tree available before downloading all file contents. The main workflow is CLI registration and daemon startup, repository preparation and snapshot publication, then filesystem access that hydrates requested blobs on demand; file changes are stored in an overlay. The README also documents async preparation, status/refresh operations, prioritized hydration, and any-Git-repository support. The graph reflects sampled wiring and documented capabilities; several internal preparation and FUSE details are represented at subsystem level because the excerpts are partial.

Main entry points: [`internal/daemon/daemon.go`](https://github.com/cloudflare/artifact-fs/blob/main/internal/daemon/daemon.go) (Daemon service), [`internal/fusefs/ops.go`](https://github.com/cloudflare/artifact-fs/blob/main/internal/fusefs/ops.go) (FUSE filesystem), [`internal/cli/cli.go`](https://github.com/cloudflare/artifact-fs/blob/main/internal/cli/cli.go) (CLI commands), [`internal/gitstore/gitstore.go`](https://github.com/cloudflare/artifact-fs/blob/main/internal/gitstore/gitstore.go) (Git operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI commands<br/>[cli.go]"]
  node_main["CLI entry<br/>[main.go]"]
end

subgraph group_control["Daemon and acquisition"]
  node_daemon["Daemon service<br/>[daemon.go]"]
  node_git["Git operations<br/>[gitstore.go]"]
  node_watcher["HEAD watcher<br/>[watcher.go]"]
  node_auth["Credential redaction<br/>[redact.go]"]
  node_logging["Structured logging<br/>[logging.go]"]
end

subgraph group_mounted["Mounted filesystem"]
  node_fuse["FUSE filesystem<br/>[ops.go]"]
  node_hydrator["Blob hydration<br/>[hydrator.go]"]
  node_overlay["Write overlay<br/>[store.go]"]
  node_model["Repository model<br/>[types.go]"]
end

subgraph group_state["Persistent state"]
  node_registry[("Repo registry<br/>[registry.go]")]
  node_snapshot[("Base snapshots<br/>[store.go]")]
  node_metadata["SQLite metadata<br/>[sqlite.go]"]
end

node_user(("CLI user"))
node_os(("Operating system"))
node_remote["Git repository"]

node_user -->|"runs commands"| node_main
node_main -->|"dispatches"| node_cli
node_cli -->|"invokes service"| node_daemon
node_cli -->|"redacts remotes"| node_auth
node_daemon -->|"loads configuration"| node_registry
node_daemon -->|"prepares and fetches"| node_git
node_git -->|"clones and fetches"| node_remote
node_daemon -->|"publishes generations"| node_snapshot
node_daemon -->|"mounts filesystem"| node_fuse
node_os -->|"filesystem operations"| node_fuse
node_fuse -->|"looks up base tree"| node_snapshot
node_fuse -->|"requests blob reads"| node_hydrator
node_hydrator -->|"fetches blob content"| node_git
node_fuse -->|"stores file changes"| node_overlay
node_daemon -->|"manages mounted overlay"| node_overlay
node_daemon -->|"starts polling"| node_watcher
node_watcher -->|"signals ref changes"| node_daemon
node_registry -->|"opens SQLite"| node_metadata
node_snapshot -->|"opens SQLite"| node_metadata
node_overlay -->|"opens SQLite"| node_metadata
node_daemon -->|"records operations"| node_logging

click node_cli "https://github.com/cloudflare/artifact-fs/blob/main/internal/cli/cli.go"
click node_main "https://github.com/cloudflare/artifact-fs/blob/main/cmd/artifact-fs/main.go"
click node_daemon "https://github.com/cloudflare/artifact-fs/blob/main/internal/daemon/daemon.go"
click node_git "https://github.com/cloudflare/artifact-fs/blob/main/internal/gitstore/gitstore.go"
click node_watcher "https://github.com/cloudflare/artifact-fs/blob/main/internal/watcher/watcher.go"
click node_fuse "https://github.com/cloudflare/artifact-fs/blob/main/internal/fusefs/ops.go"
click node_hydrator "https://github.com/cloudflare/artifact-fs/blob/main/internal/hydrator/hydrator.go"
click node_overlay "https://github.com/cloudflare/artifact-fs/blob/main/internal/overlay/store.go"
click node_model "https://github.com/cloudflare/artifact-fs/blob/main/internal/model/types.go"
click node_registry "https://github.com/cloudflare/artifact-fs/blob/main/internal/registry/registry.go"
click node_snapshot "https://github.com/cloudflare/artifact-fs/blob/main/internal/snapshot/store.go"
click node_metadata "https://github.com/cloudflare/artifact-fs/blob/main/internal/meta/sqlite.go"
click node_auth "https://github.com/cloudflare/artifact-fs/blob/main/internal/auth/redact.go"
click node_logging "https://github.com/cloudflare/artifact-fs/blob/main/internal/logging/logging.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_cli,node_main,node_user toneBlue
class node_daemon,node_git,node_watcher,node_auth,node_logging toneAmber
class node_fuse,node_hydrator,node_overlay,node_model toneMint
class node_registry,node_snapshot,node_metadata toneRose
class node_os,node_remote toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/cloudflare/artifact-fs/blob/main/internal/cli/cli.go): `internal/cli/cli.go`
- [CLI entry](https://github.com/cloudflare/artifact-fs/blob/main/cmd/artifact-fs/main.go): `cmd/artifact-fs/main.go`

### Daemon and acquisition

- [Daemon service](https://github.com/cloudflare/artifact-fs/blob/main/internal/daemon/daemon.go): `internal/daemon/daemon.go`
- [Git operations](https://github.com/cloudflare/artifact-fs/blob/main/internal/gitstore/gitstore.go): `internal/gitstore/gitstore.go`
- [HEAD watcher](https://github.com/cloudflare/artifact-fs/blob/main/internal/watcher/watcher.go): `internal/watcher/watcher.go`
- [Credential redaction](https://github.com/cloudflare/artifact-fs/blob/main/internal/auth/redact.go): `internal/auth/redact.go`
- [Structured logging](https://github.com/cloudflare/artifact-fs/blob/main/internal/logging/logging.go): `internal/logging/logging.go`

### Mounted filesystem

- [FUSE filesystem](https://github.com/cloudflare/artifact-fs/blob/main/internal/fusefs/ops.go): `internal/fusefs/ops.go`
- [Blob hydration](https://github.com/cloudflare/artifact-fs/blob/main/internal/hydrator/hydrator.go): `internal/hydrator/hydrator.go`
- [Write overlay](https://github.com/cloudflare/artifact-fs/blob/main/internal/overlay/store.go): `internal/overlay/store.go`
- [Repository model](https://github.com/cloudflare/artifact-fs/blob/main/internal/model/types.go): `internal/model/types.go`

### Persistent state

- [Repo registry](https://github.com/cloudflare/artifact-fs/blob/main/internal/registry/registry.go): `internal/registry/registry.go`
- [Base snapshots](https://github.com/cloudflare/artifact-fs/blob/main/internal/snapshot/store.go): `internal/snapshot/store.go`
- [SQLite metadata](https://github.com/cloudflare/artifact-fs/blob/main/internal/meta/sqlite.go): `internal/meta/sqlite.go`

### Other components

- **CLI user**
- **Operating system**
- **Git repository**

## Connections

- CLI user → CLI entry: runs commands
- CLI entry → CLI commands: dispatches
- CLI commands → Daemon service: invokes service
- CLI commands → Credential redaction: redacts remotes
- Daemon service → Repo registry: loads configuration
- Daemon service → Git operations: prepares and fetches
- Git operations → Git repository: clones and fetches
- Daemon service → Base snapshots: publishes generations
- Daemon service → FUSE filesystem: mounts filesystem
- Operating system → FUSE filesystem: filesystem operations
- FUSE filesystem → Base snapshots: looks up base tree
- FUSE filesystem → Blob hydration: requests blob reads
- Blob hydration → Git operations: fetches blob content
- FUSE filesystem → Write overlay: stores file changes
- Daemon service → Write overlay: manages mounted overlay
- Daemon service → HEAD watcher: starts polling
- HEAD watcher → Daemon service: signals ref changes
- Repo registry → SQLite metadata: opens SQLite
- Base snapshots → SQLite metadata: opens SQLite
- Write overlay → SQLite metadata: opens SQLite
- Daemon service → Structured logging: records operations