# zfile-dev/zfile architecture

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

- Interactive diagram: https://gitdiagram.com/zfile-dev/zfile
- Repository: https://github.com/zfile-dev/zfile

## Overview

ZFile is a personal and small-team web drive that unifies multiple storage backends. The main workflow is browsing or operating on files through storage-source endpoints, which resolve a configured source to its backend service and return file results; account-specific roots and permissions scope access. The repository also includes administration, previews, sharing, direct/short links, and authentication/configuration features. Relationships beyond the sampled storage implementation are shown as unverified where only the tree or README establishes the capability.

Main entry points: [`src/main/java/im/zhaojun/zfile/module/storage/context/StorageSourceContext.java`](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/context/StorageSourceContext.java) (Backend dispatch), [`src/main/java/im/zhaojun/zfile/module/storage/service/StorageSourceService.java`](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/service/StorageSourceService.java) (Source lifecycle), [`src/main/java/im/zhaojun/zfile/module/user/service/UserStorageSourceService.java`](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/user/service/UserStorageSourceService.java) (Source permissions), [`src/main/java/im/zhaojun/zfile/module/storage/controller/file/FileController.java`](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/controller/file/FileController.java) (File endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storage["Storage and files"]
  node_fileapi["File endpoints"]
  node_operatorapi["File operations"]
  node_sourcecontext["Backend dispatch"]
  node_backend["Storage adapters"]
  node_sourceadmin["Source management"]
  node_metadata["Source metadata"]
  node_sourceservice["Source lifecycle"]
  node_sourcestore[("Source records<br/>[StorageSource.java]")]
end

subgraph group_access["Accounts and access"]
  node_users["User accounts<br/>[UserService.java]"]
  node_usercontroller["User endpoints"]
  node_useraccess["Source permissions"]
  node_permission["Permission rules"]
  node_filter["File filters"]
end

subgraph group_sharing["Sharing and links"]
  node_share["Share links"]
  node_sharefiles["Shared file access"]
  node_direct["Direct and short links"]
  node_shortservice["Short-link service"]
end

subgraph group_admin["Administration"]
  node_settings["Site settings"]
  node_configservice["Configuration"]
  node_install["Initial setup"]
  node_sso["Single sign-on<br/>[SsoService.java]"]
end

subgraph group_integrations["Preview and integrations"]
  node_readme["Folder readmes"]
  node_office["Office preview"]
end

node_visitor(("Drive user"))
node_cloud{{"Configured storage"}}

node_visitor -.->|"browses files"| node_fileapi
node_fileapi -.->|"resolves backend"| node_sourcecontext
node_operatorapi -.->|"dispatches operations"| node_sourcecontext
node_sourcecontext -->|"selects service"| node_backend
node_backend -.->|"accesses files"| node_cloud
node_visitor -.->|"operates files"| node_operatorapi
node_sourceadmin -->|"manages sources"| node_sourceservice
node_metadata -->|"gets source fields"| node_sourcecontext
node_sourceservice -->|"initializes sources"| node_sourcecontext
node_sourceservice -.->|"persists sources"| node_sourcestore
node_usercontroller -.->|"manages accounts"| node_users
node_visitor -.->|"signs in"| node_usercontroller
node_useraccess -->|"scopes source access"| node_users
node_useraccess -->|"grants defaults"| node_sourceservice
node_permission -->|"configures permissions"| node_useraccess
node_filter -.->|"configures file limits"| node_visitor
node_visitor -.->|"creates share"| node_share
node_share -.->|"serves shared files"| node_sharefiles
node_visitor -.->|"requests file link"| node_direct
node_direct -.->|"resolves short links"| node_shortservice
node_visitor -.->|"updates site"| node_settings
node_settings -.->|"saves settings"| node_configservice
node_install -.->|"initializes setup"| node_configservice
node_visitor -.->|"authenticates"| node_sso
node_visitor -.->|"views folder notes"| node_readme
node_visitor -.->|"previews documents"| node_office

click node_fileapi "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/controller/file/FileController.java"
click node_operatorapi "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/controller/file/FileOperatorController.java"
click node_sourcecontext "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/context/StorageSourceContext.java"
click node_backend "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/service/base/AbstractBaseFileService.java"
click node_sourceadmin "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/controller/base/StorageSourceController.java"
click node_metadata "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/controller/base/StorageMetaDataController.java"
click node_sourceservice "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/service/StorageSourceService.java"
click node_sourcestore "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/model/entity/StorageSource.java"
click node_users "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/user/service/UserService.java"
click node_usercontroller "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/user/controller/UserController.java"
click node_useraccess "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/user/service/UserStorageSourceService.java"
click node_permission "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/permission/controller/StorageSourcePermissionController.java"
click node_filter "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/filter/controller/StorageSourceFilterController.java"
click node_share "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/share/service/ShareLinkService.java"
click node_sharefiles "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/share/service/ShareLinkFileService.java"
click node_direct "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/link/controller/DirectLinkController.java"
click node_shortservice "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/link/service/ShortLinkService.java"
click node_settings "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/config/controller/SettingController.java"
click node_configservice "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/config/service/SystemConfigService.java"
click node_install "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/install/controller/InstallController.java"
click node_sso "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/sso/service/SsoService.java"
click node_readme "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/readme/controller/StorageSourceReadmeController.java"
click node_office "https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/onlyoffice/controller/OnlyOfficeController.java"

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_fileapi,node_operatorapi,node_sourcecontext,node_backend,node_sourceadmin,node_metadata,node_sourceservice,node_sourcestore,node_visitor toneBlue
class node_users,node_usercontroller,node_useraccess,node_permission,node_filter,node_cloud toneAmber
class node_share,node_sharefiles,node_direct,node_shortservice toneMint
class node_settings,node_configservice,node_install,node_sso toneRose
class node_readme,node_office toneIndigo
```

## Components

### Storage and files

- [File endpoints](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/controller/file/FileController.java): `src/main/java/im/zhaojun/zfile/module/storage/controller/file/FileController.java`
- [File operations](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/controller/file/FileOperatorController.java): `src/main/java/im/zhaojun/zfile/module/storage/controller/file/FileOperatorController.java`
- [Backend dispatch](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/context/StorageSourceContext.java): `src/main/java/im/zhaojun/zfile/module/storage/context/StorageSourceContext.java`
- [Storage adapters](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/service/base/AbstractBaseFileService.java): `src/main/java/im/zhaojun/zfile/module/storage/service/base/AbstractBaseFileService.java`
- [Source management](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/controller/base/StorageSourceController.java): `src/main/java/im/zhaojun/zfile/module/storage/controller/base/StorageSourceController.java`
- [Source metadata](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/controller/base/StorageMetaDataController.java): `src/main/java/im/zhaojun/zfile/module/storage/controller/base/StorageMetaDataController.java`
- [Source lifecycle](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/service/StorageSourceService.java): `src/main/java/im/zhaojun/zfile/module/storage/service/StorageSourceService.java`
- [Source records](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/storage/model/entity/StorageSource.java): `src/main/java/im/zhaojun/zfile/module/storage/model/entity/StorageSource.java`

### Accounts and access

- [User accounts](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/user/service/UserService.java): `src/main/java/im/zhaojun/zfile/module/user/service/UserService.java`
- [User endpoints](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/user/controller/UserController.java): `src/main/java/im/zhaojun/zfile/module/user/controller/UserController.java`
- [Source permissions](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/user/service/UserStorageSourceService.java): `src/main/java/im/zhaojun/zfile/module/user/service/UserStorageSourceService.java`
- [Permission rules](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/permission/controller/StorageSourcePermissionController.java): `src/main/java/im/zhaojun/zfile/module/permission/controller/StorageSourcePermissionController.java`
- [File filters](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/filter/controller/StorageSourceFilterController.java): `src/main/java/im/zhaojun/zfile/module/filter/controller/StorageSourceFilterController.java`

### Sharing and links

- [Share links](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/share/service/ShareLinkService.java): `src/main/java/im/zhaojun/zfile/module/share/service/ShareLinkService.java`
- [Shared file access](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/share/service/ShareLinkFileService.java): `src/main/java/im/zhaojun/zfile/module/share/service/ShareLinkFileService.java`
- [Direct and short links](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/link/controller/DirectLinkController.java): `src/main/java/im/zhaojun/zfile/module/link/controller/DirectLinkController.java`
- [Short-link service](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/link/service/ShortLinkService.java): `src/main/java/im/zhaojun/zfile/module/link/service/ShortLinkService.java`

### Administration

- [Site settings](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/config/controller/SettingController.java): `src/main/java/im/zhaojun/zfile/module/config/controller/SettingController.java`
- [Configuration](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/config/service/SystemConfigService.java): `src/main/java/im/zhaojun/zfile/module/config/service/SystemConfigService.java`
- [Initial setup](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/install/controller/InstallController.java): `src/main/java/im/zhaojun/zfile/module/install/controller/InstallController.java`
- [Single sign-on](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/sso/service/SsoService.java): `src/main/java/im/zhaojun/zfile/module/sso/service/SsoService.java`

### Preview and integrations

- [Folder readmes](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/readme/controller/StorageSourceReadmeController.java): `src/main/java/im/zhaojun/zfile/module/readme/controller/StorageSourceReadmeController.java`
- [Office preview](https://github.com/zfile-dev/zfile/blob/main/src/main/java/im/zhaojun/zfile/module/onlyoffice/controller/OnlyOfficeController.java): `src/main/java/im/zhaojun/zfile/module/onlyoffice/controller/OnlyOfficeController.java`

### Other components

- **Drive user**
- **Configured storage**

## Connections

- Drive user → File endpoints: browses files (evidence: `README.md`)
- File endpoints → Backend dispatch: resolves backend
- File operations → Backend dispatch: dispatches operations
- Backend dispatch → Storage adapters: selects service (evidence: `src/main/java/im/zhaojun/zfile/module/storage/context/StorageSourceContext.java`)
- Storage adapters → Configured storage: accesses files (evidence: `README.md`)
- Drive user → File operations: operates files (evidence: `README.md`)
- Source management → Source lifecycle: manages sources (evidence: `src/main/java/im/zhaojun/zfile/module/storage/controller/base/StorageSourceController.java`)
- Source metadata → Backend dispatch: gets source fields (evidence: `src/main/java/im/zhaojun/zfile/module/storage/controller/base/StorageMetaDataController.java`)
- Source lifecycle → Backend dispatch: initializes sources (evidence: `src/main/java/im/zhaojun/zfile/module/storage/service/StorageSourceService.java`)
- Source lifecycle → Source records: persists sources (evidence: `src/main/java/im/zhaojun/zfile/module/storage/service/StorageSourceService.java`)
- User endpoints → User accounts: manages accounts
- Drive user → User endpoints: signs in
- Source permissions → User accounts: scopes source access (evidence: `src/main/java/im/zhaojun/zfile/module/user/service/UserStorageSourceService.java`)
- Source permissions → Source lifecycle: grants defaults (evidence: `src/main/java/im/zhaojun/zfile/module/storage/service/StorageSourceService.java`)
- Permission rules → Source permissions: configures permissions (evidence: `src/main/java/im/zhaojun/zfile/module/permission/controller/StorageSourcePermissionController.java`)
- File filters → Drive user: configures file limits (evidence: `README.md`)
- Drive user → Share links: creates share (evidence: `README.md`)
- Share links → Shared file access: serves shared files
- Drive user → Direct and short links: requests file link (evidence: `README.md`)
- Direct and short links → Short-link service: resolves short links
- Drive user → Site settings: updates site
- Site settings → Configuration: saves settings
- Initial setup → Configuration: initializes setup
- Drive user → Single sign-on: authenticates
- Drive user → Folder readmes: views folder notes
- Drive user → Office preview: previews documents (evidence: `README.md`)
