# angusrausch/simple-zfs-manager architecture

> Architecture diagram of the GitHub repository angusrausch/simple-zfs-manager, 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/angusrausch/simple-zfs-manager
- Repository: https://github.com/angusrausch/simple-zfs-manager

## Overview

Simple ZFS Manager is a lightweight NAS web management application. The principal evidenced workflow is a user signing in through PAM-backed authentication and receiving a session cookie; the app also exposes a dashboard and has core modules for ZFS pools, datasets, snapshots/replication, and SMB shares. The README documents NFS exports as a goal, but the tree shows no NFS implementation. Sampled code supports core-to-command execution; wiring from UI routes to storage operations is not established by the excerpts.

Main entry points: [`app/main.py`](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/main.py) (FastAPI app), [`app/routers/auth.py`](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/routers/auth.py) (Login routes), [`app/core/system/runner.py`](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/system/runner.py) (Command runner), [`app/core/zfs/utils.py`](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/zfs/utils.py) (ZFS command utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth_routes["Login routes<br/>[auth.py]"]
  node_dashboard["Dashboard route<br/>[dashboard.py]"]
  node_health["Health route<br/>[health.py]"]
  node_templates["Page templates"]
end

subgraph group_auth["Authentication"]
  node_session["Token security<br/>[security.py]"]
  node_pam_auth["PAM authentication<br/>[pam_auth.py]"]
end

subgraph group_storage["Storage management"]
  node_zfs["Dataset operations<br/>[zfs.py]"]
  node_zpool["Pool operations<br/>[zpool.py]"]
  node_zfs_models["ZFS state models<br/>[models.py]"]
  node_smb["SMB share operations<br/>[smb.py]"]
  node_smb_models["Share models<br/>[models.py]"]
  node_nfs["NFS exports &#40;planned&#41;"]
end

subgraph group_system["System integration"]
  node_runner["Command runner<br/>[runner.py]"]
  node_zfs_utils["ZFS command utilities<br/>[utils.py]"]
  node_config["App configuration<br/>[config.py]"]
  node_file_mod["Safe file changes<br/>[file_mod.py]"]
end

node_user(("Web user"))
node_pam["Linux PAM"]
node_samba["Samba utilities"]
node_zfs_cli["ZFS utilities"]

node_user -->|"sends requests"| node_app
node_app -->|"registers routes"| node_auth_routes
node_app -->|"registers routes"| node_dashboard
node_app -->|"registers routes"| node_health
node_auth_routes -->|"checks or creates token"| node_session
node_session -->|"authenticates login"| node_pam_auth
node_pam_auth -->|"checks credentials"| node_pam
node_auth_routes -->|"renders login"| node_templates
node_dashboard -->|"renders dashboard"| node_templates
node_zfs -->|"executes commands"| node_zfs_utils
node_zpool -->|"executes commands"| node_zfs_utils
node_zfs_utils -->|"runs processes"| node_runner
node_runner -->|"invokes"| node_zfs_cli
node_smb -->|"runs commands"| node_runner
node_smb -->|"invokes"| node_samba

click node_app "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/main.py"
click node_auth_routes "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/routers/auth.py"
click node_dashboard "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/routers/dashboard.py"
click node_health "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/routers/health.py"
click node_templates "https://github.com/angusrausch/simple-zfs-manager/tree/main/app/templates"
click node_session "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/security.py"
click node_pam_auth "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/system/pam_auth.py"
click node_zfs "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/zfs/zfs.py"
click node_zpool "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/zfs/zpool.py"
click node_zfs_models "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/zfs/models.py"
click node_smb "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/smb/smb.py"
click node_smb_models "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/smb/models.py"
click node_runner "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/system/runner.py"
click node_zfs_utils "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/zfs/utils.py"
click node_config "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/config.py"
click node_file_mod "https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/system/file_mod.py"
click node_nfs "https://github.com/angusrausch/simple-zfs-manager/tree/main/app/core"

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_app,node_auth_routes,node_dashboard,node_health,node_templates,node_user toneBlue
class node_session,node_pam_auth toneAmber
class node_zfs,node_zpool,node_zfs_models,node_smb,node_smb_models,node_nfs toneMint
class node_runner,node_zfs_utils,node_config,node_file_mod toneRose
class node_pam,node_samba,node_zfs_cli toneIndigo
```

## Components

### Web application

- [FastAPI app](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/main.py): `app/main.py`
- [Login routes](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/routers/auth.py): `app/routers/auth.py`
- [Dashboard route](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/routers/dashboard.py): `app/routers/dashboard.py`
- [Health route](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/routers/health.py): `app/routers/health.py`
- [Page templates](https://github.com/angusrausch/simple-zfs-manager/tree/main/app/templates): `app/templates`

### Authentication

- [Token security](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/security.py): `app/core/security.py`
- [PAM authentication](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/system/pam_auth.py): `app/core/system/pam_auth.py`

### Storage management

- [Dataset operations](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/zfs/zfs.py): `app/core/zfs/zfs.py`
- [Pool operations](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/zfs/zpool.py): `app/core/zfs/zpool.py`
- [ZFS state models](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/zfs/models.py): `app/core/zfs/models.py`
- [SMB share operations](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/smb/smb.py): `app/core/smb/smb.py`
- [Share models](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/smb/models.py): `app/core/smb/models.py`
- [NFS exports (planned)](https://github.com/angusrausch/simple-zfs-manager/tree/main/app/core): `app/core`

### System integration

- [Command runner](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/system/runner.py): `app/core/system/runner.py`
- [ZFS command utilities](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/zfs/utils.py): `app/core/zfs/utils.py`
- [App configuration](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/config.py): `app/core/config.py`
- [Safe file changes](https://github.com/angusrausch/simple-zfs-manager/blob/main/app/core/system/file_mod.py): `app/core/system/file_mod.py`

### Other components

- **Web user**
- **Linux PAM**
- **Samba utilities**
- **ZFS utilities**

## Connections

- Web user → FastAPI app: sends requests
- FastAPI app → Login routes: registers routes
- FastAPI app → Dashboard route: registers routes
- FastAPI app → Health route: registers routes
- Login routes → Token security: checks or creates token
- Token security → PAM authentication: authenticates login
- PAM authentication → Linux PAM: checks credentials
- Login routes → Page templates: renders login
- Dashboard route → Page templates: renders dashboard
- Dataset operations → ZFS command utilities: executes commands
- Pool operations → ZFS command utilities: executes commands
- ZFS command utilities → Command runner: runs processes
- Command runner → ZFS utilities: invokes
- SMB share operations → Command runner: runs commands
- SMB share operations → Samba utilities: invokes