# distributedfilesystem/centralized-distributed-file-systems architecture

> Architecture diagram of the GitHub repository distributedfilesystem/centralized-distributed-file-systems, 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/distributedfilesystem/centralized-distributed-file-systems
- Repository: https://github.com/distributedfilesystem/centralized-distributed-file-systems

## Overview

This is a centralized-metadata distributed file system: users sign in through the desktop client, browse and administer a namespace, and upload or download file chunks transferred directly between the client and data servers. The metadata server handles namespace, transfer planning, authorization, sessions, and persisted metadata; data servers store chunks and report availability by heartbeat. Shared TCP framing and message contracts support these interactions. The README also describes a later Raft/replication HA stage, but the supplied source tree shows stage-one implementations, so that future capability is documented rather than represented as implemented components.

Main entry points: [`src/Dfs.Client.Core/DfsClient.cs`](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Client.Core/DfsClient.cs) (DFS client), [`src/Dfs.MetadataServer/Hosting/MetadataServerHost.cs`](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Hosting/MetadataServerHost.cs) (Metadata server), [`src/Dfs.MetadataServer/Store/SqliteMetadataState.cs`](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Store/SqliteMetadataState.cs) (Metadata state), [`src/Dfs.Client.Desktop/ViewModels/MainViewModel.cs`](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Client.Desktop/ViewModels/MainViewModel.cs) (Desktop UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop client"]
  node_desktop["Desktop UI<br/>[MainViewModel.cs]"]
  node_browser["File browser"]
  node_transfers["Transfer manager"]
  node_adminui["Admin panel"]
end

subgraph group_client["Client runtime"]
  node_clientlib["DFS client<br/>[DfsClient.cs]"]
end

subgraph group_metadata["Metadata service"]
  node_meta["Metadata server"]
  node_namespace["Namespace operations"]
  node_path["Path resolution<br/>[NamespacePath.cs]"]
  node_transfer["Transfer planning<br/>[TransferHandler.cs]"]
  node_sessions["Sessions and login<br/>[SessionService.cs]"]
  node_authorization["RBAC authorization<br/>[RbacAuthorizer.cs]"]
  node_state[("Metadata state")]
  node_oplog[("Operation log<br/>[OpLog.cs]")]
end

subgraph group_data["Data service"]
  node_dataserver["Data server host<br/>[DataServerHost.cs]"]
  node_heartbeat["Heartbeat client<br/>[HeartbeatClient.cs]"]
  node_chunks[("Chunk storage<br/>[ChunkStorage.cs]")]
end

subgraph group_shared["Shared protocol and contracts"]
  node_framing["TCP frame codec<br/>[FrameCodec.cs]"]
  node_serialization["JSON serialization"]
  node_handshake["Protocol handshake"]
  node_messages["Wire messages<br/>[MessageType.cs]"]
  node_metadata_contract["Metadata contract<br/>[IMetadataStore.cs]"]
  node_commands["Metadata commands"]
  node_permissions["Permission model<br/>[Permission.cs]"]
end

node_user(("User"))
node_external_data(("Data servers"))

node_user -->|"uses"| node_desktop
node_desktop -.->|"opens"| node_browser
node_desktop -.->|"opens"| node_transfers
node_desktop -.->|"opens"| node_adminui
node_browser -->|"calls"| node_clientlib
node_transfers -->|"calls"| node_clientlib
node_adminui -.->|"calls"| node_clientlib
node_clientlib -.->|"metadata requests"| node_meta
node_clientlib -->|"chunk transfers"| node_external_data
node_meta -.->|"dispatches"| node_namespace
node_meta -.->|"dispatches"| node_transfer
node_meta -.->|"dispatches"| node_sessions
node_namespace -->|"resolves paths"| node_path
node_namespace -->|"reads and writes"| node_state
node_transfer -->|"reads and writes"| node_state
node_transfer -->|"checks access"| node_authorization
node_transfer -.->|"plans chunk access"| node_external_data
node_sessions -->|"loads and updates"| node_state
node_authorization -->|"reads permissions"| node_state
node_state -.->|"persists operations"| node_oplog
node_heartbeat -->|"registers and reports"| node_meta
node_heartbeat -->|"reads capacity"| node_chunks
node_dataserver -.->|"stores chunks"| node_chunks
node_clientlib -->|"encodes TCP"| node_framing
node_framing -->|"serializes payloads"| node_serialization
node_framing -->|"uses message types"| node_messages
node_handshake -->|"exchanges frames"| node_framing
node_namespace -->|"uses store contract"| node_metadata_contract
node_metadata_contract -->|"submits commands"| node_commands
node_authorization -->|"evaluates permissions"| node_permissions

click node_desktop "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Client.Desktop/ViewModels/MainViewModel.cs"
click node_browser "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Client.Desktop/ViewModels/FileBrowserViewModel.cs"
click node_transfers "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Client.Desktop/ViewModels/TransferManagerViewModel.cs"
click node_adminui "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Client.Desktop/ViewModels/AdminPanelViewModel.cs"
click node_clientlib "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Client.Core/DfsClient.cs"
click node_meta "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Hosting/MetadataServerHost.cs"
click node_namespace "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Handlers/NamespaceHandler.cs"
click node_path "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Handlers/NamespacePath.cs"
click node_transfer "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Handlers/TransferHandler.cs"
click node_sessions "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Security/SessionService.cs"
click node_authorization "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Security/RbacAuthorizer.cs"
click node_state "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Store/SqliteMetadataState.cs"
click node_oplog "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Store/OpLog.cs"
click node_dataserver "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.DataServer/Hosting/DataServerHost.cs"
click node_heartbeat "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.DataServer/Hosting/HeartbeatClient.cs"
click node_chunks "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.DataServer/Storage/ChunkStorage.cs"
click node_framing "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Framing/FrameCodec.cs"
click node_serialization "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Framing/FrameSerialization.cs"
click node_handshake "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Framing/HandshakeHandler.cs"
click node_messages "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Messages/MessageType.cs"
click node_metadata_contract "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Metadata/IMetadataStore.cs"
click node_commands "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Commands/IMetadataCommand.cs"
click node_permissions "https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Security/Permission.cs"

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_desktop,node_browser,node_transfers,node_adminui,node_user toneBlue
class node_clientlib toneAmber
class node_meta,node_namespace,node_path,node_transfer,node_sessions,node_authorization,node_state,node_oplog,node_external_data toneMint
class node_dataserver,node_heartbeat,node_chunks toneRose
class node_framing,node_serialization,node_handshake,node_messages,node_metadata_contract,node_commands,node_permissions toneIndigo
```

## Components

### Desktop client

- [Desktop UI](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Client.Desktop/ViewModels/MainViewModel.cs): `src/Dfs.Client.Desktop/ViewModels/MainViewModel.cs`
- [File browser](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Client.Desktop/ViewModels/FileBrowserViewModel.cs): `src/Dfs.Client.Desktop/ViewModels/FileBrowserViewModel.cs`
- [Transfer manager](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Client.Desktop/ViewModels/TransferManagerViewModel.cs): `src/Dfs.Client.Desktop/ViewModels/TransferManagerViewModel.cs`
- [Admin panel](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Client.Desktop/ViewModels/AdminPanelViewModel.cs): `src/Dfs.Client.Desktop/ViewModels/AdminPanelViewModel.cs`

### Client runtime

- [DFS client](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Client.Core/DfsClient.cs): `src/Dfs.Client.Core/DfsClient.cs`

### Metadata service

- [Metadata server](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Hosting/MetadataServerHost.cs): `src/Dfs.MetadataServer/Hosting/MetadataServerHost.cs`
- [Namespace operations](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Handlers/NamespaceHandler.cs): `src/Dfs.MetadataServer/Handlers/NamespaceHandler.cs`
- [Path resolution](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Handlers/NamespacePath.cs): `src/Dfs.MetadataServer/Handlers/NamespacePath.cs`
- [Transfer planning](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Handlers/TransferHandler.cs): `src/Dfs.MetadataServer/Handlers/TransferHandler.cs`
- [Sessions and login](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Security/SessionService.cs): `src/Dfs.MetadataServer/Security/SessionService.cs`
- [RBAC authorization](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Security/RbacAuthorizer.cs): `src/Dfs.MetadataServer/Security/RbacAuthorizer.cs`
- [Metadata state](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Store/SqliteMetadataState.cs): `src/Dfs.MetadataServer/Store/SqliteMetadataState.cs`
- [Operation log](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.MetadataServer/Store/OpLog.cs): `src/Dfs.MetadataServer/Store/OpLog.cs`

### Data service

- [Data server host](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.DataServer/Hosting/DataServerHost.cs): `src/Dfs.DataServer/Hosting/DataServerHost.cs`
- [Heartbeat client](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.DataServer/Hosting/HeartbeatClient.cs): `src/Dfs.DataServer/Hosting/HeartbeatClient.cs`
- [Chunk storage](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.DataServer/Storage/ChunkStorage.cs): `src/Dfs.DataServer/Storage/ChunkStorage.cs`

### Shared protocol and contracts

- [TCP frame codec](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Framing/FrameCodec.cs): `src/Dfs.Shared/Framing/FrameCodec.cs`
- [JSON serialization](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Framing/FrameSerialization.cs): `src/Dfs.Shared/Framing/FrameSerialization.cs`
- [Protocol handshake](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Framing/HandshakeHandler.cs): `src/Dfs.Shared/Framing/HandshakeHandler.cs`
- [Wire messages](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Messages/MessageType.cs): `src/Dfs.Shared/Messages/MessageType.cs`
- [Metadata contract](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Metadata/IMetadataStore.cs): `src/Dfs.Shared/Metadata/IMetadataStore.cs`
- [Metadata commands](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Commands/IMetadataCommand.cs): `src/Dfs.Shared/Commands/IMetadataCommand.cs`
- [Permission model](https://github.com/distributedfilesystem/centralized-distributed-file-systems/blob/develop/src/Dfs.Shared/Security/Permission.cs): `src/Dfs.Shared/Security/Permission.cs`

### Other components

- **User**
- **Data servers**

## Connections

- User → Desktop UI: uses (evidence: `README.md`)
- Desktop UI → File browser: opens
- Desktop UI → Transfer manager: opens
- Desktop UI → Admin panel: opens
- File browser → DFS client: calls (evidence: `src/Dfs.Client.Desktop/ViewModels/FileBrowserViewModel.cs`)
- Transfer manager → DFS client: calls (evidence: `src/Dfs.Client.Desktop/ViewModels/TransferManagerViewModel.cs`)
- Admin panel → DFS client: calls
- DFS client → Metadata server: metadata requests
- DFS client → Data servers: chunk transfers
- Metadata server → Namespace operations: dispatches
- Metadata server → Transfer planning: dispatches
- Metadata server → Sessions and login: dispatches
- Namespace operations → Path resolution: resolves paths (evidence: `src/Dfs.MetadataServer/Handlers/NamespaceHandler.cs`)
- Namespace operations → Metadata state: reads and writes (evidence: `src/Dfs.MetadataServer/Handlers/NamespaceHandler.cs`)
- Transfer planning → Metadata state: reads and writes (evidence: `src/Dfs.MetadataServer/Handlers/TransferHandler.cs`)
- Transfer planning → RBAC authorization: checks access (evidence: `src/Dfs.MetadataServer/Handlers/TransferHandler.cs`)
- Transfer planning → Data servers: plans chunk access
- Sessions and login → Metadata state: loads and updates (evidence: `src/Dfs.MetadataServer/Security/SessionService.cs`)
- RBAC authorization → Metadata state: reads permissions (evidence: `src/Dfs.MetadataServer/Security/RbacAuthorizer.cs`)
- Metadata state → Operation log: persists operations
- Heartbeat client → Metadata server: registers and reports (evidence: `src/Dfs.DataServer/Hosting/HeartbeatClient.cs`)
- Heartbeat client → Chunk storage: reads capacity (evidence: `src/Dfs.DataServer/Hosting/HeartbeatClient.cs`)
- Data server host → Chunk storage: stores chunks
- DFS client → TCP frame codec: encodes TCP (evidence: `src/Dfs.Client.Core/DfsClient.cs`)
- TCP frame codec → JSON serialization: serializes payloads (evidence: `src/Dfs.Shared/Framing/FrameCodec.cs`)
- TCP frame codec → Wire messages: uses message types (evidence: `src/Dfs.Shared/Framing/FrameCodec.cs`)
- Protocol handshake → TCP frame codec: exchanges frames (evidence: `src/Dfs.Shared/Framing/HandshakeHandler.cs`)
- Namespace operations → Metadata contract: uses store contract (evidence: `src/Dfs.MetadataServer/Handlers/NamespaceHandler.cs`)
- Metadata contract → Metadata commands: submits commands (evidence: `src/Dfs.Shared/Metadata/IMetadataStore.cs`)
- RBAC authorization → Permission model: evaluates permissions (evidence: `src/Dfs.MetadataServer/Security/RbacAuthorizer.cs`)
