# doctor-io/homeio architecture

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

- Interactive diagram: https://gitdiagram.com/doctor-io/homeio
- Repository: https://github.com/doctor-io/homeio

## Overview

Homeio is a self-hosted server manager whose desktop-style interface lets an administrator inspect and operate a server: manage Docker apps, files and storage, system resources, and settings. The main workflow crosses the UI, API routes, and server modules; major supporting capabilities include terminal access, scheduled tasks, backups, networking, and integrations. The README documents product capabilities, while sampled source and the SOURCE INDEX establish only selected internal calls, so other links are omitted or marked unverified rather than inferred from directory names.

Main entry points: [`modules/shell/components/desktop-shell.tsx`](https://github.com/doctor-io/homeio/blob/main/modules/shell/components/desktop-shell.tsx) (Desktop shell), [`modules/settings/components/settings.tsx`](https://github.com/doctor-io/homeio/blob/main/modules/settings/components/settings.tsx) (Settings panel), [`modules/files/components/manager/file-manager.tsx`](https://github.com/doctor-io/homeio/blob/main/modules/files/components/manager/file-manager.tsx) (File manager), [`modules/apps/components/app-grid-controller.ts`](https://github.com/doctor-io/homeio/blob/main/modules/apps/components/app-grid-controller.ts) (App management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_desktop["Desktop shell<br/>[desktop-shell.tsx]"]
  node_system_ui["System dashboard<br/>[monitor.tsx]"]
  node_settings_ui["Settings panel<br/>[settings.tsx]"]
  node_tasks_ui["Scheduled tasks UI"]
end

subgraph group_apps["Apps and Docker"]
  node_apps_ui["App management"]
  node_store_catalog["App catalog<br/>[catalog.ts]"]
  node_apps_service["App operations<br/>[service.ts]"]
  node_docker["Docker management<br/>[compose-runner.ts]"]
end

subgraph group_files["Files and storage"]
  node_files_ui["File manager<br/>[file-manager.tsx]"]
  node_files_service["File services<br/>[service.ts]"]
  node_network_storage["Network storage<br/>[network-storage.ts]"]
  node_usb_storage["USB storage<br/>[usb-storage.ts]"]
  node_google_drive["Google Drive<br/>[google-drive.ts]"]
end

subgraph group_system["System management"]
  node_system_service["System services<br/>[service.ts]"]
  node_disk_service["Disk management<br/>[disk-service.ts]"]
  node_network_service["Network manager<br/>[service.ts]"]
  node_backup_service["Backup and restore<br/>[backup-service.ts]"]
end

subgraph group_server["Server services"]
  node_auth_service["Authentication<br/>[service.ts]"]
  node_tasks_api["Scheduled task API<br/>[route.ts]"]
  node_tasks_service["Task scheduling<br/>[service.ts]"]
  node_terminal["Terminal service"]
  node_cloudflare["Cloudflare Tunnel"]
end

node_admin(("Administrator"))

node_admin -->|"uses"| node_desktop
node_desktop -->|"views"| node_system_ui
node_desktop -->|"manages"| node_apps_ui
node_desktop -->|"opens"| node_files_ui
node_desktop -.->|"configures"| node_settings_ui
node_apps_ui -.->|"browses"| node_store_catalog
node_apps_ui -.->|"operates"| node_apps_service
node_apps_service -.->|"runs apps"| node_docker
node_files_ui -.->|"manages files"| node_files_service
node_files_ui -.->|"mounts shares"| node_network_storage
node_files_ui -.->|"manages drives"| node_usb_storage
node_desktop -->|"shows metrics"| node_system_service
node_settings_ui -.->|"configures disks"| node_disk_service
node_settings_ui -->|"manages backups"| node_backup_service
node_admin -.->|"authenticates"| node_auth_service
node_tasks_ui -->|"requests tasks"| node_tasks_api
node_tasks_api -->|"delegates"| node_tasks_service
node_admin -->|"opens shell"| node_terminal
node_settings_ui -->|"manages network"| node_network_service
node_settings_ui -->|"publishes apps"| node_cloudflare
node_files_ui -.->|"browses drive"| node_google_drive

click node_desktop "https://github.com/doctor-io/homeio/blob/main/modules/shell/components/desktop-shell.tsx"
click node_system_ui "https://github.com/doctor-io/homeio/blob/main/modules/system/components/monitor.tsx"
click node_settings_ui "https://github.com/doctor-io/homeio/blob/main/modules/settings/components/settings.tsx"
click node_apps_ui "https://github.com/doctor-io/homeio/blob/main/modules/apps/components/app-grid-controller.ts"
click node_store_catalog "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/store/catalog.ts"
click node_apps_service "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/apps/service.ts"
click node_docker "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/docker/compose-runner.ts"
click node_files_ui "https://github.com/doctor-io/homeio/blob/main/modules/files/components/manager/file-manager.tsx"
click node_files_service "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/files/service.ts"
click node_network_storage "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/files/network-storage.ts"
click node_usb_storage "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/files/usb-storage.ts"
click node_system_service "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/system/service.ts"
click node_disk_service "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/system/disk-service.ts"
click node_network_service "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/network/service.ts"
click node_backup_service "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/system/backup-service.ts"
click node_auth_service "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/auth/service.ts"
click node_tasks_ui "https://github.com/doctor-io/homeio/blob/main/modules/settings/hooks/useScheduledTasks.ts"
click node_tasks_api "https://github.com/doctor-io/homeio/blob/main/app/api/v1/scheduled-tasks/route.ts"
click node_tasks_service "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/scheduled-tasks/service.ts"
click node_terminal "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/terminal/websocket-server.ts"
click node_cloudflare "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/integrations/cloudflare-tunnel-service.ts"
click node_google_drive "https://github.com/doctor-io/homeio/blob/main/lib/server/modules/files/google-drive.ts"

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_system_ui,node_settings_ui,node_tasks_ui toneBlue
class node_apps_ui,node_store_catalog,node_apps_service,node_docker toneAmber
class node_files_ui,node_files_service,node_network_storage,node_usb_storage,node_google_drive toneMint
class node_system_service,node_disk_service,node_network_service,node_backup_service toneRose
class node_auth_service,node_tasks_api,node_tasks_service,node_terminal,node_cloudflare,node_admin toneIndigo
```

## Components

### Desktop experience

- [Desktop shell](https://github.com/doctor-io/homeio/blob/main/modules/shell/components/desktop-shell.tsx): `modules/shell/components/desktop-shell.tsx`
- [System dashboard](https://github.com/doctor-io/homeio/blob/main/modules/system/components/monitor.tsx): `modules/system/components/monitor.tsx`
- [Settings panel](https://github.com/doctor-io/homeio/blob/main/modules/settings/components/settings.tsx): `modules/settings/components/settings.tsx`
- [Scheduled tasks UI](https://github.com/doctor-io/homeio/blob/main/modules/settings/hooks/useScheduledTasks.ts): `modules/settings/hooks/useScheduledTasks.ts`

### Apps and Docker

- [App management](https://github.com/doctor-io/homeio/blob/main/modules/apps/components/app-grid-controller.ts): `modules/apps/components/app-grid-controller.ts`
- [App catalog](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/store/catalog.ts): `lib/server/modules/store/catalog.ts`
- [App operations](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/apps/service.ts): `lib/server/modules/apps/service.ts`
- [Docker management](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/docker/compose-runner.ts): `lib/server/modules/docker/compose-runner.ts`

### Files and storage

- [File manager](https://github.com/doctor-io/homeio/blob/main/modules/files/components/manager/file-manager.tsx): `modules/files/components/manager/file-manager.tsx`
- [File services](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/files/service.ts): `lib/server/modules/files/service.ts`
- [Network storage](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/files/network-storage.ts): `lib/server/modules/files/network-storage.ts`
- [USB storage](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/files/usb-storage.ts): `lib/server/modules/files/usb-storage.ts`
- [Google Drive](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/files/google-drive.ts): `lib/server/modules/files/google-drive.ts`

### System management

- [System services](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/system/service.ts): `lib/server/modules/system/service.ts`
- [Disk management](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/system/disk-service.ts): `lib/server/modules/system/disk-service.ts`
- [Network manager](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/network/service.ts): `lib/server/modules/network/service.ts`
- [Backup and restore](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/system/backup-service.ts): `lib/server/modules/system/backup-service.ts`

### Server services

- [Authentication](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/auth/service.ts): `lib/server/modules/auth/service.ts`
- [Scheduled task API](https://github.com/doctor-io/homeio/blob/main/app/api/v1/scheduled-tasks/route.ts): `app/api/v1/scheduled-tasks/route.ts`
- [Task scheduling](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/scheduled-tasks/service.ts): `lib/server/modules/scheduled-tasks/service.ts`
- [Terminal service](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/terminal/websocket-server.ts): `lib/server/modules/terminal/websocket-server.ts`
- [Cloudflare Tunnel](https://github.com/doctor-io/homeio/blob/main/lib/server/modules/integrations/cloudflare-tunnel-service.ts): `lib/server/modules/integrations/cloudflare-tunnel-service.ts`

### Other components

- **Administrator**

## Connections

- Administrator → Desktop shell: uses (evidence: `README.md`)
- Desktop shell → System dashboard: views (evidence: `README.md`)
- Desktop shell → App management: manages (evidence: `README.md`)
- Desktop shell → File manager: opens (evidence: `README.md`)
- Desktop shell → Settings panel: configures
- App management → App catalog: browses
- App management → App operations: operates
- App operations → Docker management: runs apps
- File manager → File services: manages files
- File manager → Network storage: mounts shares
- File manager → USB storage: manages drives
- Desktop shell → System services: shows metrics (evidence: `README.md`)
- Settings panel → Disk management: configures disks
- Settings panel → Backup and restore: manages backups (evidence: `README.md`)
- Administrator → Authentication: authenticates
- Scheduled tasks UI → Scheduled task API: requests tasks (evidence: `modules/settings/hooks/useScheduledTasks.ts`)
- Scheduled task API → Task scheduling: delegates (evidence: `app/api/v1/scheduled-tasks/route.ts`)
- Administrator → Terminal service: opens shell (evidence: `README.md`)
- Settings panel → Network manager: manages network (evidence: `README.md`)
- Settings panel → Cloudflare Tunnel: publishes apps (evidence: `README.md`)
- File manager → Google Drive: browses drive