# luthfihakim2004/leichfs architecture

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

- Interactive diagram: https://gitdiagram.com/luthfihakim2004/leichfs
- Repository: https://github.com/luthfihakim2004/leichfs

## Overview

leichfs is a Linux FUSE filesystem that transparently stores files encrypted with per-file AES-256-GCM keys. Users initialize a backing directory or change its passphrase, then mount it; FUSE operations dispatch to filesystem handlers that serve plaintext reads and writes while maintaining encrypted backing files. The README also documents partial and full backup, enabled by independently encrypted files and a config-held wrapped master key. Edges reflect the shown entry-point calls, indexed imports, and excerpts; unsampled callback details are not inferred.

Main entry points: [`lib/leichfs/dispatch.cpp`](https://github.com/luthfihakim2004/leichfs/blob/main/lib/leichfs/dispatch.cpp) (FUSE dispatch), [`src/main.cpp`](https://github.com/luthfihakim2004/leichfs/blob/main/src/main.cpp) (CLI entry), [`lib/leichfs/init.cpp`](https://github.com/luthfihakim2004/leichfs/blob/main/lib/leichfs/init.cpp) (Init and passphrase), [`lib/fs/io.cpp`](https://github.com/luthfihakim2004/leichfs/blob/main/lib/fs/io.cpp) (Encrypted file I/O)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and FUSE"]
  node_main["CLI entry<br/>[main.cpp]"]
  node_dispatch["FUSE dispatch<br/>[dispatch.cpp]"]
end

subgraph group_keys["Keys and Encryption"]
  node_init["Init and passphrase<br/>[init.cpp]"]
  node_crypto["Crypto primitives<br/>[crypto.cpp]"]
  node_header["File headers<br/>[header.cpp]"]
  node_config["Wrapped-key config<br/>[init.cpp]"]
end

subgraph group_operations["Filesystem Operations"]
  node_fileio["Encrypted file I/O<br/>[io.cpp]"]
  node_metadata["Metadata operations<br/>[meta.cpp]"]
  node_directories["Directory operations<br/>[dir.cpp]"]
  node_xattrs["Extended attributes<br/>[xattr.cpp]"]
  node_lifecycle["Lifecycle operations<br/>[lc.cpp]"]
  node_backup["Backup capability<br/>[README.md]"]
end

subgraph group_support["Filesystem State"]
  node_context["Filesystem context<br/>[core.hpp]"]
  node_helpers["Secure filesystem helpers<br/>[util.cpp]"]
end

node_user(("User"))
node_fuse(("FUSE runtime"))
node_backing[("Backing directory")]

node_user -->|"runs commands"| node_main
node_main -->|"initializes or rewraps"| node_init
node_main -->|"loads key"| node_helpers
node_main -->|"starts FUSE"| node_dispatch
node_main -->|"creates context"| node_context
node_fuse -.->|"invokes callbacks"| node_dispatch
node_dispatch -->|"routes I/O"| node_fileio
node_dispatch -->|"routes metadata"| node_metadata
node_dispatch -->|"routes directories"| node_directories
node_dispatch -->|"routes attributes"| node_xattrs
node_dispatch -->|"routes lifecycle"| node_lifecycle
node_fileio -->|"uses chunk helpers"| node_helpers
node_fileio -->|"encrypts and decrypts"| node_crypto
node_fileio -.->|"reads and writes"| node_header
node_metadata -->|"uses filesystem helpers"| node_helpers
node_metadata -->|"uses crypto"| node_crypto
node_init -->|"wraps master key"| node_crypto
node_init -->|"uses key utilities"| node_helpers
node_init -->|"reads and writes"| node_config
node_helpers -.->|"reads and writes files"| node_backing
node_fileio -.->|"stores ciphertext"| node_backing
node_init -->|"stores config"| node_backing
node_backup -->|"backs up files"| node_backing

click node_main "https://github.com/luthfihakim2004/leichfs/blob/main/src/main.cpp"
click node_dispatch "https://github.com/luthfihakim2004/leichfs/blob/main/lib/leichfs/dispatch.cpp"
click node_init "https://github.com/luthfihakim2004/leichfs/blob/main/lib/leichfs/init.cpp"
click node_crypto "https://github.com/luthfihakim2004/leichfs/blob/main/lib/enc/crypto.cpp"
click node_header "https://github.com/luthfihakim2004/leichfs/blob/main/lib/enc/header.cpp"
click node_fileio "https://github.com/luthfihakim2004/leichfs/blob/main/lib/fs/io.cpp"
click node_metadata "https://github.com/luthfihakim2004/leichfs/blob/main/lib/fs/meta.cpp"
click node_directories "https://github.com/luthfihakim2004/leichfs/blob/main/lib/fs/dir.cpp"
click node_xattrs "https://github.com/luthfihakim2004/leichfs/blob/main/lib/fs/xattr.cpp"
click node_lifecycle "https://github.com/luthfihakim2004/leichfs/blob/main/lib/fs/lc.cpp"
click node_context "https://github.com/luthfihakim2004/leichfs/blob/main/include/fs/core.hpp"
click node_helpers "https://github.com/luthfihakim2004/leichfs/blob/main/lib/util.cpp"
click node_config "https://github.com/luthfihakim2004/leichfs/blob/main/lib/leichfs/init.cpp"
click node_backup "https://github.com/luthfihakim2004/leichfs/blob/main/README.md"

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_main,node_dispatch,node_user toneBlue
class node_init,node_crypto,node_header,node_config,node_backing toneAmber
class node_fileio,node_metadata,node_directories,node_xattrs,node_lifecycle,node_backup toneMint
class node_context,node_helpers toneRose
class node_fuse toneIndigo
```

## Components

### CLI and FUSE

- [CLI entry](https://github.com/luthfihakim2004/leichfs/blob/main/src/main.cpp): `src/main.cpp`
- [FUSE dispatch](https://github.com/luthfihakim2004/leichfs/blob/main/lib/leichfs/dispatch.cpp): `lib/leichfs/dispatch.cpp`

### Keys and Encryption

- [Init and passphrase](https://github.com/luthfihakim2004/leichfs/blob/main/lib/leichfs/init.cpp): `lib/leichfs/init.cpp`
- [Crypto primitives](https://github.com/luthfihakim2004/leichfs/blob/main/lib/enc/crypto.cpp): `lib/enc/crypto.cpp`
- [File headers](https://github.com/luthfihakim2004/leichfs/blob/main/lib/enc/header.cpp): `lib/enc/header.cpp`
- [Wrapped-key config](https://github.com/luthfihakim2004/leichfs/blob/main/lib/leichfs/init.cpp): `lib/leichfs/init.cpp`

### Filesystem Operations

- [Encrypted file I/O](https://github.com/luthfihakim2004/leichfs/blob/main/lib/fs/io.cpp): `lib/fs/io.cpp`
- [Metadata operations](https://github.com/luthfihakim2004/leichfs/blob/main/lib/fs/meta.cpp): `lib/fs/meta.cpp`
- [Directory operations](https://github.com/luthfihakim2004/leichfs/blob/main/lib/fs/dir.cpp): `lib/fs/dir.cpp`
- [Extended attributes](https://github.com/luthfihakim2004/leichfs/blob/main/lib/fs/xattr.cpp): `lib/fs/xattr.cpp`
- [Lifecycle operations](https://github.com/luthfihakim2004/leichfs/blob/main/lib/fs/lc.cpp): `lib/fs/lc.cpp`
- [Backup capability](https://github.com/luthfihakim2004/leichfs/blob/main/README.md): `README.md`

### Filesystem State

- [Filesystem context](https://github.com/luthfihakim2004/leichfs/blob/main/include/fs/core.hpp): `include/fs/core.hpp`
- [Secure filesystem helpers](https://github.com/luthfihakim2004/leichfs/blob/main/lib/util.cpp): `lib/util.cpp`

### Other components

- **User**
- **FUSE runtime**
- **Backing directory**

## Connections

- User → CLI entry: runs commands (evidence: `src/main.cpp`)
- CLI entry → Init and passphrase: initializes or rewraps (evidence: `src/main.cpp`)
- CLI entry → Secure filesystem helpers: loads key (evidence: `src/main.cpp`)
- CLI entry → FUSE dispatch: starts FUSE (evidence: `src/main.cpp`)
- CLI entry → Filesystem context: creates context (evidence: `src/main.cpp`)
- FUSE runtime → FUSE dispatch: invokes callbacks
- FUSE dispatch → Encrypted file I/O: routes I/O (evidence: `lib/leichfs/dispatch.cpp`)
- FUSE dispatch → Metadata operations: routes metadata (evidence: `lib/leichfs/dispatch.cpp`)
- FUSE dispatch → Directory operations: routes directories (evidence: `lib/leichfs/dispatch.cpp`)
- FUSE dispatch → Extended attributes: routes attributes (evidence: `lib/leichfs/dispatch.cpp`)
- FUSE dispatch → Lifecycle operations: routes lifecycle (evidence: `lib/leichfs/dispatch.cpp`)
- Encrypted file I/O → Secure filesystem helpers: uses chunk helpers (evidence: `lib/fs/io.cpp`)
- Encrypted file I/O → Crypto primitives: encrypts and decrypts (evidence: `lib/fs/io.cpp`)
- Encrypted file I/O → File headers: reads and writes
- Metadata operations → Secure filesystem helpers: uses filesystem helpers (evidence: `lib/fs/meta.cpp`)
- Metadata operations → Crypto primitives: uses crypto (evidence: `lib/fs/meta.cpp`)
- Init and passphrase → Crypto primitives: wraps master key (evidence: `lib/leichfs/init.cpp`)
- Init and passphrase → Secure filesystem helpers: uses key utilities (evidence: `lib/leichfs/init.cpp`)
- Init and passphrase → Wrapped-key config: reads and writes (evidence: `lib/leichfs/init.cpp`)
- Secure filesystem helpers → Backing directory: reads and writes files
- Encrypted file I/O → Backing directory: stores ciphertext
- Init and passphrase → Backing directory: stores config (evidence: `lib/leichfs/init.cpp`)
- Backup capability → Backing directory: backs up files (evidence: `README.md`)
