# devlok1/self-hosted-cloud architecture

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

- Interactive diagram: https://gitdiagram.com/devlok1/self-hosted-cloud
- Repository: https://github.com/devlok1/self-hosted-cloud

## Overview

HomeCloud is a self-hosted cloud file manager. Users authenticate in the React UI, browse folders and files, and perform storage actions through an API client; the backend applies ownership-aware services and persists metadata while storing file bytes on disk. A separate resumable-transfer path stages and verifies chunks before finalizing files. The README documents major features and controller responsibilities; some controller and frontend modules were not sampled, so only documented or indexed relationships are shown.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/devlok1/self-hosted-cloud/blob/main/frontend/src/api/client.ts) (HTTP API client), [`backend/src/main/java/com/homecloud/backend/service/TransferService.java`](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/TransferService.java) (Transfer orchestration), [`backend/src/main/java/com/homecloud/backend/service/FileService.java`](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/FileService.java) (File management), [`frontend/src/App.tsx`](https://github.com/devlok1/self-hosted-cloud/blob/main/frontend/src/App.tsx) (Cloud dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["Cloud dashboard<br/>[App.tsx]"]
  node_authview["Sign-in view<br/>[AuthView.tsx]"]
  node_api_client["HTTP API client<br/>[client.ts]"]
  node_file_ui["File workspace UI"]
end

subgraph group_api["API and security"]
  node_auth_controller["Authentication API"]
  node_file_controller["File API"]
  node_folder_controller["Folder API"]
  node_storage_controller["Storage stats API"]
  node_transfer_controller["Transfer API"]
  node_security["JWT security"]
end

subgraph group_domain["Storage domain"]
  node_auth_service["Account service<br/>[AuthService.java]"]
  node_file_service["File management<br/>[FileService.java]"]
  node_folder_service["Folder hierarchy<br/>[FolderService.java]"]
  node_file_storage[("Physical file store")]
  node_metadata[("JPA metadata")]
end

subgraph group_transfer["Resumable transfers"]
  node_transfer_service["Transfer orchestration"]
  node_transfer_storage[("Chunk staging")]
  node_transfer_metadata[("Transfer records")]
  node_cleanup["Transfer cleanup"]
end

node_person(("HomeCloud user"))

node_person -->|"uses"| node_app
node_app -->|"renders"| node_authview
node_app -->|"renders"| node_file_ui
node_app -->|"calls"| node_api_client
node_authview -->|"calls"| node_api_client
node_api_client -->|"HTTP requests"| node_auth_controller
node_api_client -->|"HTTP requests"| node_file_controller
node_api_client -->|"HTTP requests"| node_folder_controller
node_api_client -->|"HTTP requests"| node_storage_controller
node_api_client -->|"HTTP requests"| node_transfer_controller
node_auth_controller -.->|"delegates to"| node_auth_service
node_file_controller -->|"delegates to"| node_file_service
node_folder_controller -.->|"delegates to"| node_folder_service
node_storage_controller -->|"gets statistics"| node_file_service
node_transfer_controller -->|"delegates to"| node_transfer_service
node_auth_service -->|"uses user repository"| node_metadata
node_auth_service -->|"uses JWT service"| node_security
node_file_service -->|"reads and writes"| node_metadata
node_file_service -->|"stores file bytes"| node_file_storage
node_file_service -->|"resolves folders"| node_folder_service
node_folder_service -.->|"reads and writes"| node_metadata
node_transfer_service -->|"tracks sessions"| node_transfer_metadata
node_transfer_service -->|"stages and assembles"| node_transfer_storage
node_transfer_service -->|"finalizes files"| node_file_storage
node_transfer_service -->|"resolves folders"| node_folder_service
node_cleanup -.->|"purges transfers"| node_transfer_service

click node_app "https://github.com/devlok1/self-hosted-cloud/blob/main/frontend/src/App.tsx"
click node_authview "https://github.com/devlok1/self-hosted-cloud/blob/main/frontend/src/components/AuthView.tsx"
click node_api_client "https://github.com/devlok1/self-hosted-cloud/blob/main/frontend/src/api/client.ts"
click node_file_ui "https://github.com/devlok1/self-hosted-cloud/tree/main/frontend/src/components"
click node_auth_controller "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/controller/AuthController.java"
click node_file_controller "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/controller/FileController.java"
click node_folder_controller "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/controller/FolderController.java"
click node_storage_controller "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/controller/StorageController.java"
click node_transfer_controller "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/controller/TransferController.java"
click node_security "https://github.com/devlok1/self-hosted-cloud/tree/main/backend/src/main/java/com/homecloud/backend/security"
click node_auth_service "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/AuthService.java"
click node_file_service "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/FileService.java"
click node_folder_service "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/FolderService.java"
click node_file_storage "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/FileStorageService.java"
click node_metadata "https://github.com/devlok1/self-hosted-cloud/tree/main/backend/src/main/java/com/homecloud/backend/repository"
click node_transfer_service "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/TransferService.java"
click node_transfer_storage "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/TransferStorageService.java"
click node_transfer_metadata "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/repository/UploadSessionRepository.java"
click node_cleanup "https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/TransferCleanupScheduler.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_app,node_authview,node_api_client,node_file_ui,node_person toneBlue
class node_auth_controller,node_file_controller,node_folder_controller,node_storage_controller,node_transfer_controller,node_security toneAmber
class node_auth_service,node_file_service,node_folder_service,node_file_storage,node_metadata toneMint
class node_transfer_service,node_transfer_storage,node_transfer_metadata,node_cleanup toneRose
```

## Components

### Web application

- [Cloud dashboard](https://github.com/devlok1/self-hosted-cloud/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign-in view](https://github.com/devlok1/self-hosted-cloud/blob/main/frontend/src/components/AuthView.tsx): `frontend/src/components/AuthView.tsx`
- [HTTP API client](https://github.com/devlok1/self-hosted-cloud/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [File workspace UI](https://github.com/devlok1/self-hosted-cloud/tree/main/frontend/src/components): `frontend/src/components`

### API and security

- [Authentication API](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/controller/AuthController.java): `backend/src/main/java/com/homecloud/backend/controller/AuthController.java`
- [File API](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/controller/FileController.java): `backend/src/main/java/com/homecloud/backend/controller/FileController.java`
- [Folder API](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/controller/FolderController.java): `backend/src/main/java/com/homecloud/backend/controller/FolderController.java`
- [Storage stats API](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/controller/StorageController.java): `backend/src/main/java/com/homecloud/backend/controller/StorageController.java`
- [Transfer API](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/controller/TransferController.java): `backend/src/main/java/com/homecloud/backend/controller/TransferController.java`
- [JWT security](https://github.com/devlok1/self-hosted-cloud/tree/main/backend/src/main/java/com/homecloud/backend/security): `backend/src/main/java/com/homecloud/backend/security`

### Storage domain

- [Account service](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/AuthService.java): `backend/src/main/java/com/homecloud/backend/service/AuthService.java`
- [File management](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/FileService.java): `backend/src/main/java/com/homecloud/backend/service/FileService.java`
- [Folder hierarchy](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/FolderService.java): `backend/src/main/java/com/homecloud/backend/service/FolderService.java`
- [Physical file store](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/FileStorageService.java): `backend/src/main/java/com/homecloud/backend/service/FileStorageService.java`
- [JPA metadata](https://github.com/devlok1/self-hosted-cloud/tree/main/backend/src/main/java/com/homecloud/backend/repository): `backend/src/main/java/com/homecloud/backend/repository`

### Resumable transfers

- [Transfer orchestration](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/TransferService.java): `backend/src/main/java/com/homecloud/backend/service/TransferService.java`
- [Chunk staging](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/TransferStorageService.java): `backend/src/main/java/com/homecloud/backend/service/TransferStorageService.java`
- [Transfer records](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/repository/UploadSessionRepository.java): `backend/src/main/java/com/homecloud/backend/repository/UploadSessionRepository.java`
- [Transfer cleanup](https://github.com/devlok1/self-hosted-cloud/blob/main/backend/src/main/java/com/homecloud/backend/service/TransferCleanupScheduler.java): `backend/src/main/java/com/homecloud/backend/service/TransferCleanupScheduler.java`

### Other components

- **HomeCloud user**

## Connections

- HomeCloud user → Cloud dashboard: uses
- Cloud dashboard → Sign-in view: renders (evidence: `frontend/src/App.tsx`)
- Cloud dashboard → File workspace UI: renders (evidence: `frontend/src/App.tsx`)
- Cloud dashboard → HTTP API client: calls (evidence: `frontend/src/App.tsx`)
- Sign-in view → HTTP API client: calls (evidence: `frontend/src/components/AuthView.tsx`)
- HTTP API client → Authentication API: HTTP requests (evidence: `frontend/src/api/client.ts`)
- HTTP API client → File API: HTTP requests (evidence: `frontend/src/api/client.ts`)
- HTTP API client → Folder API: HTTP requests (evidence: `frontend/src/api/client.ts`)
- HTTP API client → Storage stats API: HTTP requests (evidence: `frontend/src/api/client.ts`)
- HTTP API client → Transfer API: HTTP requests (evidence: `frontend/src/api/client.ts`)
- Authentication API → Account service: delegates to
- File API → File management: delegates to (evidence: `backend/src/main/java/com/homecloud/backend/controller/FileController.java`)
- Folder API → Folder hierarchy: delegates to (evidence: `backend/src/main/java/com/homecloud/backend/controller/FolderController.java`)
- Storage stats API → File management: gets statistics (evidence: `backend/src/main/java/com/homecloud/backend/controller/StorageController.java`)
- Transfer API → Transfer orchestration: delegates to (evidence: `backend/src/main/java/com/homecloud/backend/controller/TransferController.java`)
- Account service → JPA metadata: uses user repository (evidence: `backend/src/main/java/com/homecloud/backend/service/AuthService.java`)
- Account service → JWT security: uses JWT service (evidence: `backend/src/main/java/com/homecloud/backend/service/AuthService.java`)
- File management → JPA metadata: reads and writes (evidence: `backend/src/main/java/com/homecloud/backend/service/FileService.java`)
- File management → Physical file store: stores file bytes (evidence: `backend/src/main/java/com/homecloud/backend/service/FileService.java`)
- File management → Folder hierarchy: resolves folders (evidence: `backend/src/main/java/com/homecloud/backend/service/FileService.java`)
- Folder hierarchy → JPA metadata: reads and writes (evidence: `backend/src/main/java/com/homecloud/backend/service/FolderService.java`)
- Transfer orchestration → Transfer records: tracks sessions (evidence: `backend/src/main/java/com/homecloud/backend/service/TransferService.java`)
- Transfer orchestration → Chunk staging: stages and assembles (evidence: `backend/src/main/java/com/homecloud/backend/service/TransferService.java`)
- Transfer orchestration → Physical file store: finalizes files (evidence: `backend/src/main/java/com/homecloud/backend/service/TransferService.java`)
- Transfer orchestration → Folder hierarchy: resolves folders (evidence: `backend/src/main/java/com/homecloud/backend/service/TransferService.java`)
- Transfer cleanup → Transfer orchestration: purges transfers