# thinkparq/beegfs architecture

> Architecture diagram of the GitHub repository thinkparq/beegfs, 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/thinkparq/beegfs
- Repository: https://github.com/thinkparq/beegfs

## Overview

BeeGFS is a parallel cluster file system. A client mounts it and issues filesystem operations; the kernel client handles VFS requests and communicates with metadata and storage services to resolve namespace operations and transfer file data. The repository also contains monitoring, event-listening, BeeOND, and filesystem-checking components. The tree and README identify these product areas, but sampled implementation excerpts are sparse, so the graph omits uncertain internal call wiring and treats the separately maintained management service as external.

Main entry points: [`storage`](https://github.com/thinkparq/beegfs/tree/master/storage) (Storage service), [`client_module/source/net/filesystem`](https://github.com/thinkparq/beegfs/tree/master/client_module/source/net/filesystem) (Client remoting), [`client_module/source/filesystem`](https://github.com/thinkparq/beegfs/tree/master/client_module/source/filesystem) (Kernel client), [`storage/source/storage/StorageTargets.cpp`](https://github.com/thinkparq/beegfs/blob/master/storage/source/storage/StorageTargets.cpp) (Storage targets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client access"]
  node_clientmod["Kernel client"]
  node_clientnet["Client remoting"]
end

subgraph group_servers["Cluster services"]
  node_meta["Metadata service"]
  node_storage["Storage service"]
  node_targets["Storage targets<br/>[StorageTargets.cpp]"]
  node_storagetk["Storage toolkit<br/>[StorageTk.cpp]"]
  node_localstorage[("Local storage paths")]
end

subgraph group_operations["Operations"]
  node_monitor["Monitoring service"]
  node_event["Event listener"]
  node_beeond["BeeOND"]
  node_fsck["Filesystem checker"]
end

subgraph group_shared["Shared runtime"]
  node_nodes["Node and target maps"]
  node_protocol["Message protocol"]
  node_pools["Storage pool state"]
end

node_user(("Application"))
node_vfs(("Linux VFS"))
node_mgmt["Management service"]

node_user -->|"issues filesystem calls"| node_vfs
node_vfs -->|"dispatches operations"| node_clientmod
node_clientmod -->|"requests remote work"| node_clientnet
node_clientnet -->|"metadata operations"| node_meta
node_clientnet -->|"file I/O"| node_storage
node_storage -->|"manages targets"| node_targets
node_targets -->|"reads and writes"| node_localstorage
node_targets -->|"reports target state"| node_mgmt
node_meta -.->|"cluster coordination"| node_mgmt
node_storage -.->|"cluster coordination"| node_mgmt
node_monitor -->|"collects node status"| node_storage
node_fsck -->|"checks metadata"| node_meta
node_fsck -->|"checks storage"| node_storage
node_beeond -->|"uses mounted filesystem"| node_clientmod
node_clientnet -->|"encodes messages"| node_protocol
node_clientmod -->|"uses node mappings"| node_nodes
node_storage -->|"tracks target pools"| node_pools
node_storage -->|"uses storage utilities"| node_storagetk

click node_clientmod "https://github.com/thinkparq/beegfs/tree/master/client_module/source/filesystem"
click node_clientnet "https://github.com/thinkparq/beegfs/tree/master/client_module/source/net/filesystem"
click node_meta "https://github.com/thinkparq/beegfs/tree/master/meta"
click node_storage "https://github.com/thinkparq/beegfs/tree/master/storage"
click node_targets "https://github.com/thinkparq/beegfs/blob/master/storage/source/storage/StorageTargets.cpp"
click node_storagetk "https://github.com/thinkparq/beegfs/blob/master/common/source/common/toolkit/StorageTk.cpp"
click node_monitor "https://github.com/thinkparq/beegfs/tree/master/mon"
click node_event "https://github.com/thinkparq/beegfs/tree/master/event_listener"
click node_beeond "https://github.com/thinkparq/beegfs/tree/master/beeond"
click node_fsck "https://github.com/thinkparq/beegfs/tree/master/fsck"
click node_nodes "https://github.com/thinkparq/beegfs/tree/master/client_module/source/common/nodes"
click node_protocol "https://github.com/thinkparq/beegfs/tree/master/client_module/source/common/net/message"
click node_pools "https://github.com/thinkparq/beegfs/blob/master/common/source/common/nodes/StoragePoolStore.cpp"

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_clientmod,node_clientnet toneBlue
class node_meta,node_storage,node_targets,node_storagetk,node_localstorage toneAmber
class node_monitor,node_event,node_beeond,node_fsck toneMint
class node_nodes,node_protocol,node_pools toneRose
class node_user,node_vfs,node_mgmt toneIndigo
```

## Components

### Client access

- [Kernel client](https://github.com/thinkparq/beegfs/tree/master/client_module/source/filesystem): `client_module/source/filesystem`
- [Client remoting](https://github.com/thinkparq/beegfs/tree/master/client_module/source/net/filesystem): `client_module/source/net/filesystem`

### Cluster services

- [Metadata service](https://github.com/thinkparq/beegfs/tree/master/meta): `meta`
- [Storage service](https://github.com/thinkparq/beegfs/tree/master/storage): `storage`
- [Storage targets](https://github.com/thinkparq/beegfs/blob/master/storage/source/storage/StorageTargets.cpp): `storage/source/storage/StorageTargets.cpp`
- [Storage toolkit](https://github.com/thinkparq/beegfs/blob/master/common/source/common/toolkit/StorageTk.cpp): `common/source/common/toolkit/StorageTk.cpp`
- **Local storage paths**

### Operations

- [Monitoring service](https://github.com/thinkparq/beegfs/tree/master/mon): `mon`
- [Event listener](https://github.com/thinkparq/beegfs/tree/master/event_listener): `event_listener`
- [BeeOND](https://github.com/thinkparq/beegfs/tree/master/beeond): `beeond`
- [Filesystem checker](https://github.com/thinkparq/beegfs/tree/master/fsck): `fsck`

### Shared runtime

- [Node and target maps](https://github.com/thinkparq/beegfs/tree/master/client_module/source/common/nodes): `client_module/source/common/nodes`
- [Message protocol](https://github.com/thinkparq/beegfs/tree/master/client_module/source/common/net/message): `client_module/source/common/net/message`
- [Storage pool state](https://github.com/thinkparq/beegfs/blob/master/common/source/common/nodes/StoragePoolStore.cpp): `common/source/common/nodes/StoragePoolStore.cpp`

### Other components

- **Application**
- **Linux VFS**
- **Management service**

## Connections

- Application → Linux VFS: issues filesystem calls
- Linux VFS → Kernel client: dispatches operations
- Kernel client → Client remoting: requests remote work
- Client remoting → Metadata service: metadata operations
- Client remoting → Storage service: file I/O
- Storage service → Storage targets: manages targets
- Storage targets → Local storage paths: reads and writes
- Storage targets → Management service: reports target state
- Metadata service → Management service: cluster coordination
- Storage service → Management service: cluster coordination
- Monitoring service → Storage service: collects node status
- Filesystem checker → Metadata service: checks metadata
- Filesystem checker → Storage service: checks storage
- BeeOND → Kernel client: uses mounted filesystem
- Client remoting → Message protocol: encodes messages
- Kernel client → Node and target maps: uses node mappings
- Storage service → Storage pool state: tracks target pools
- Storage service → Storage toolkit: uses storage utilities