# icewhaletech/casaos architecture

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

- Interactive diagram: https://gitdiagram.com/icewhaletech/casaos
- Repository: https://github.com/icewhaletech/casaos

## Overview

CasaOS is the backend for a personal-cloud system: clients call its local HTTP API, which exposes file and system operations and other cloud-management capabilities. The sampled startup code initializes the service repository and HTTP routers; a file route delegates directory operations to the system service. The README also describes app installation, widgets, and drive management, but their detailed implementation paths were not sampled, so those branches are represented only at the subsystem level. Edges are limited to relationships visible in excerpts, the source index, or README statements.

Main entry points: [`service/service.go`](https://github.com/icewhaletech/casaos/blob/main/service/service.go) (Service repository), [`main.go`](https://github.com/icewhaletech/casaos/blob/main/main.go) (CasaOS server), [`internal/op/driver.go`](https://github.com/icewhaletech/casaos/blob/main/internal/op/driver.go) (Drive registry), [`service/system.go`](https://github.com/icewhaletech/casaos/blob/main/service/system.go) (System operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and API"]
  node_server["CasaOS server<br/>[main.go]"]
  node_v1api["Version 1 API<br/>[v1.go]"]
  node_fileapi["File API<br/>[file.go]"]
  node_v2api["Version 2 API<br/>[v2.go]"]
end

subgraph group_domain["Cloud Services"]
  node_repository["Service repository<br/>[service.go]"]
  node_system["System operations<br/>[system.go]"]
  node_notifications["Notifications<br/>[notify.go]"]
  node_connections["Connections<br/>[connections.go]"]
  node_shares["Shares<br/>[shares.go]"]
  node_peer["Peer services<br/>[peer.go]"]
  node_health["Health checks<br/>[health.go]"]
  node_other["Other services<br/>[other.go]"]
  node_app_ecosystem["Docker apps<br/>[other.go]"]
  node_widgets["System widgets<br/>[system.go]"]
end

subgraph group_storage["Files and Storage"]
  node_file_service["File operations<br/>[file.go]"]
  node_upload["File uploads<br/>[file_upload.go]"]
  node_storage_service["Mounted storage<br/>[storage.go]"]
  node_sqlite[("SQLite database<br/>[db.go]")]
end

subgraph group_integrations["External Integrations"]
  node_driver_registry["Drive registry<br/>[driver.go]"]
  node_google_drive["Google Drive<br/>[drive.go]"]
  node_dropbox["Dropbox<br/>[drive.go]"]
  node_onedrive["OneDrive<br/>[drive.go]"]
end

node_user(("CasaOS client"))

node_user -->|"requests"| node_server
node_server -->|"serves"| node_v1api
node_server -->|"serves"| node_v2api
node_server -->|"initializes"| node_repository
node_fileapi -->|"calls"| node_system
node_repository -->|"constructs"| node_connections
node_repository -->|"constructs"| node_notifications
node_repository -->|"constructs"| node_shares
node_repository -->|"constructs"| node_peer
node_repository -->|"constructs"| node_health
node_repository -->|"constructs"| node_system
node_repository -->|"constructs"| node_storage_service
node_driver_registry -->|"registers"| node_google_drive
node_driver_registry -->|"registers"| node_dropbox
node_driver_registry -->|"registers"| node_onedrive
node_user -.->|"installs apps"| node_app_ecosystem
node_user -.->|"views status"| node_widgets

click node_server "https://github.com/icewhaletech/casaos/blob/main/main.go"
click node_v1api "https://github.com/icewhaletech/casaos/blob/main/route/v1.go"
click node_fileapi "https://github.com/icewhaletech/casaos/blob/main/route/v1/file.go"
click node_v2api "https://github.com/icewhaletech/casaos/blob/main/route/v2.go"
click node_repository "https://github.com/icewhaletech/casaos/blob/main/service/service.go"
click node_system "https://github.com/icewhaletech/casaos/blob/main/service/system.go"
click node_notifications "https://github.com/icewhaletech/casaos/blob/main/service/notify.go"
click node_connections "https://github.com/icewhaletech/casaos/blob/main/service/connections.go"
click node_shares "https://github.com/icewhaletech/casaos/blob/main/service/shares.go"
click node_peer "https://github.com/icewhaletech/casaos/blob/main/service/peer.go"
click node_health "https://github.com/icewhaletech/casaos/blob/main/service/health.go"
click node_other "https://github.com/icewhaletech/casaos/blob/main/service/other.go"
click node_file_service "https://github.com/icewhaletech/casaos/blob/main/service/file.go"
click node_upload "https://github.com/icewhaletech/casaos/blob/main/service/file_upload.go"
click node_storage_service "https://github.com/icewhaletech/casaos/blob/main/service/storage.go"
click node_sqlite "https://github.com/icewhaletech/casaos/blob/main/pkg/sqlite/db.go"
click node_driver_registry "https://github.com/icewhaletech/casaos/blob/main/internal/op/driver.go"
click node_google_drive "https://github.com/icewhaletech/casaos/blob/main/drivers/google_drive/drive.go"
click node_dropbox "https://github.com/icewhaletech/casaos/blob/main/drivers/dropbox/drive.go"
click node_onedrive "https://github.com/icewhaletech/casaos/blob/main/drivers/onedrive/drive.go"
click node_app_ecosystem "https://github.com/icewhaletech/casaos/blob/main/service/other.go"
click node_widgets "https://github.com/icewhaletech/casaos/blob/main/service/system.go"

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_server,node_v1api,node_fileapi,node_v2api,node_user toneBlue
class node_repository,node_system,node_notifications,node_connections,node_shares,node_peer,node_health,node_other,node_app_ecosystem,node_widgets toneAmber
class node_file_service,node_upload,node_storage_service,node_sqlite toneMint
class node_driver_registry,node_google_drive,node_dropbox,node_onedrive toneRose
```

## Components

### Runtime and API

- [CasaOS server](https://github.com/icewhaletech/casaos/blob/main/main.go): `main.go`
- [Version 1 API](https://github.com/icewhaletech/casaos/blob/main/route/v1.go): `route/v1.go`
- [File API](https://github.com/icewhaletech/casaos/blob/main/route/v1/file.go): `route/v1/file.go`
- [Version 2 API](https://github.com/icewhaletech/casaos/blob/main/route/v2.go): `route/v2.go`

### Cloud Services

- [Service repository](https://github.com/icewhaletech/casaos/blob/main/service/service.go): `service/service.go`
- [System operations](https://github.com/icewhaletech/casaos/blob/main/service/system.go): `service/system.go`
- [Notifications](https://github.com/icewhaletech/casaos/blob/main/service/notify.go): `service/notify.go`
- [Connections](https://github.com/icewhaletech/casaos/blob/main/service/connections.go): `service/connections.go`
- [Shares](https://github.com/icewhaletech/casaos/blob/main/service/shares.go): `service/shares.go`
- [Peer services](https://github.com/icewhaletech/casaos/blob/main/service/peer.go): `service/peer.go`
- [Health checks](https://github.com/icewhaletech/casaos/blob/main/service/health.go): `service/health.go`
- [Other services](https://github.com/icewhaletech/casaos/blob/main/service/other.go): `service/other.go`
- [Docker apps](https://github.com/icewhaletech/casaos/blob/main/service/other.go): `service/other.go`
- [System widgets](https://github.com/icewhaletech/casaos/blob/main/service/system.go): `service/system.go`

### Files and Storage

- [File operations](https://github.com/icewhaletech/casaos/blob/main/service/file.go): `service/file.go`
- [File uploads](https://github.com/icewhaletech/casaos/blob/main/service/file_upload.go): `service/file_upload.go`
- [Mounted storage](https://github.com/icewhaletech/casaos/blob/main/service/storage.go): `service/storage.go`
- [SQLite database](https://github.com/icewhaletech/casaos/blob/main/pkg/sqlite/db.go): `pkg/sqlite/db.go`

### External Integrations

- [Drive registry](https://github.com/icewhaletech/casaos/blob/main/internal/op/driver.go): `internal/op/driver.go`
- [Google Drive](https://github.com/icewhaletech/casaos/blob/main/drivers/google_drive/drive.go): `drivers/google_drive/drive.go`
- [Dropbox](https://github.com/icewhaletech/casaos/blob/main/drivers/dropbox/drive.go): `drivers/dropbox/drive.go`
- [OneDrive](https://github.com/icewhaletech/casaos/blob/main/drivers/onedrive/drive.go): `drivers/onedrive/drive.go`

### Other components

- **CasaOS client**

## Connections

- CasaOS client → CasaOS server: requests (evidence: `README.md`)
- CasaOS server → Version 1 API: serves (evidence: `main.go`)
- CasaOS server → Version 2 API: serves (evidence: `main.go`)
- CasaOS server → Service repository: initializes (evidence: `main.go`)
- File API → System operations: calls (evidence: `route/v1/file.go`)
- Service repository → Connections: constructs (evidence: `service/service.go`)
- Service repository → Notifications: constructs (evidence: `service/service.go`)
- Service repository → Shares: constructs (evidence: `service/service.go`)
- Service repository → Peer services: constructs (evidence: `service/service.go`)
- Service repository → Health checks: constructs (evidence: `service/service.go`)
- Service repository → System operations: constructs (evidence: `service/service.go`)
- Service repository → Mounted storage: constructs (evidence: `service/service.go`)
- Drive registry → Google Drive: registers
- Drive registry → Dropbox: registers
- Drive registry → OneDrive: registers
- CasaOS client → Docker apps: installs apps (evidence: `README.md`)
- CasaOS client → System widgets: views status (evidence: `README.md`)
