# atalayalabs/oxicloud architecture

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

- Interactive diagram: https://gitdiagram.com/atalayalabs/oxicloud
- Repository: https://github.com/atalayalabs/oxicloud

## Overview

OxiCloud is a self-hosted cloud suite: users browse and upload files, then retrieve, preview, organize, or share them; it also serves calendars, contacts, and office editing. The README describes a hexagonal Rust backend with a web UI and standard DAV protocols. The graph reflects those documented layers and capabilities; detailed wiring is shown only where supported by the sampled source, so some subsystem connections remain intentionally broad.

Main entry points: [`src/interfaces/api/handlers`](https://github.com/atalayalabs/oxicloud/tree/main/src/interfaces/api/handlers) (File handlers), [`src/interfaces/api/routes.rs`](https://github.com/atalayalabs/oxicloud/blob/main/src/interfaces/api/routes.rs) (API routing), [`src/infrastructure/services`](https://github.com/atalayalabs/oxicloud/tree/main/src/infrastructure/services) (Blob backends), [`src/infrastructure/repositories/pg`](https://github.com/atalayalabs/oxicloud/tree/main/src/infrastructure/repositories/pg) (Postgres repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web and clients"]
  node_web_ui["Web application"]
  node_web_api["REST API client"]
end

subgraph group_api["Interfaces"]
  node_api_routes["API routing<br/>[routes.rs]"]
  node_file_api["File handlers"]
  node_dav_api["DAV handlers"]
  node_auth_api["Authentication<br/>[auth_handler.rs]"]
  node_wopi_api["WOPI handler<br/>[wopi_handler.rs]"]
end

subgraph group_application["Application services"]
  node_file_usecases["File workflows"]
  node_retrieval["File retrieval"]
  node_share_search["Sharing and search"]
  node_dav_services["Calendar and contacts"]
  node_auth_services["Identity and access"]
  node_collab_services["Live collaboration"]
  node_media_services["Media processing"]
end

subgraph group_infrastructure["Infrastructure"]
  node_blob_store["Blob backends"]
  node_pg_repos["Postgres repositories"]
  node_acl_engine["Authorization engine<br/>[pg_acl_engine.rs]"]
  node_scheduler["Background jobs"]
end

subgraph group_state["Persistent state"]
  node_postgres[("PostgreSQL")]
  node_blob_storage[("Blob storage")]
end

node_person(("Cloud user"))
node_dav_client(("DAV client"))
node_office_suite["Collabora / OnlyOffice"]
node_oidc_provider["OIDC provider"]

node_person -->|"uses"| node_web_ui
node_web_ui -->|"requests"| node_web_api
node_web_api -->|"calls"| node_api_routes
node_api_routes -->|"routes"| node_file_api
node_api_routes -->|"routes"| node_auth_api
node_file_api -->|"invokes"| node_file_usecases
node_file_api -->|"invokes"| node_retrieval
node_retrieval -->|"reads"| node_blob_store
node_file_usecases -->|"stores content"| node_blob_store
node_file_usecases -->|"persists metadata"| node_pg_repos
node_retrieval -->|"reads metadata"| node_pg_repos
node_pg_repos -->|"reads and writes"| node_postgres
node_blob_store -->|"reads and writes"| node_blob_storage
node_dav_client -->|"uses DAV"| node_dav_api
node_dav_api -->|"invokes"| node_dav_services
node_dav_services -->|"persists records"| node_pg_repos
node_file_api -->|"invokes"| node_share_search
node_share_search -->|"checks access"| node_acl_engine
node_acl_engine -->|"queries grants"| node_postgres
node_auth_api -->|"invokes"| node_auth_services
node_auth_services -.->|"authenticates"| node_oidc_provider
node_api_routes -->|"routes"| node_wopi_api
node_wopi_api -->|"serves editing"| node_office_suite
node_file_api -->|"requests previews"| node_media_services
node_media_services -->|"reads content"| node_blob_store
node_person -->|"edits together"| node_collab_services
node_collab_services -->|"stores sessions"| node_postgres
node_scheduler -->|"stores job state"| node_postgres

click node_web_ui "https://github.com/atalayalabs/oxicloud/tree/main/frontend/src/routes"
click node_web_api "https://github.com/atalayalabs/oxicloud/tree/main/frontend/src/lib/api"
click node_api_routes "https://github.com/atalayalabs/oxicloud/blob/main/src/interfaces/api/routes.rs"
click node_file_api "https://github.com/atalayalabs/oxicloud/tree/main/src/interfaces/api/handlers"
click node_dav_api "https://github.com/atalayalabs/oxicloud/tree/main/src/interfaces/api/handlers"
click node_auth_api "https://github.com/atalayalabs/oxicloud/blob/main/src/interfaces/api/handlers/auth_handler.rs"
click node_wopi_api "https://github.com/atalayalabs/oxicloud/blob/main/src/interfaces/api/handlers/wopi_handler.rs"
click node_file_usecases "https://github.com/atalayalabs/oxicloud/tree/main/src/application/services"
click node_retrieval "https://github.com/atalayalabs/oxicloud/blob/main/src/application/services/file_retrieval_service.rs"
click node_share_search "https://github.com/atalayalabs/oxicloud/tree/main/src/application/services"
click node_dav_services "https://github.com/atalayalabs/oxicloud/tree/main/src/application/services"
click node_auth_services "https://github.com/atalayalabs/oxicloud/tree/main/src/application/services"
click node_collab_services "https://github.com/atalayalabs/oxicloud/blob/main/src/application/services/collab_session_service.rs"
click node_media_services "https://github.com/atalayalabs/oxicloud/tree/main/src/infrastructure/services"
click node_blob_store "https://github.com/atalayalabs/oxicloud/tree/main/src/infrastructure/services"
click node_pg_repos "https://github.com/atalayalabs/oxicloud/tree/main/src/infrastructure/repositories/pg"
click node_acl_engine "https://github.com/atalayalabs/oxicloud/blob/main/src/infrastructure/services/pg_acl_engine.rs"
click node_scheduler "https://github.com/atalayalabs/oxicloud/tree/main/src/infrastructure/scheduler"

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_web_ui,node_web_api,node_person,node_dav_client toneBlue
class node_api_routes,node_file_api,node_dav_api,node_auth_api,node_wopi_api toneAmber
class node_file_usecases,node_retrieval,node_share_search,node_dav_services,node_auth_services,node_collab_services,node_media_services toneMint
class node_blob_store,node_pg_repos,node_acl_engine,node_scheduler toneRose
class node_postgres,node_blob_storage,node_office_suite,node_oidc_provider toneIndigo
```

## Components

### Web and clients

- [Web application](https://github.com/atalayalabs/oxicloud/tree/main/frontend/src/routes): `frontend/src/routes`
- [REST API client](https://github.com/atalayalabs/oxicloud/tree/main/frontend/src/lib/api): `frontend/src/lib/api`

### Interfaces

- [API routing](https://github.com/atalayalabs/oxicloud/blob/main/src/interfaces/api/routes.rs): `src/interfaces/api/routes.rs`
- [File handlers](https://github.com/atalayalabs/oxicloud/tree/main/src/interfaces/api/handlers): `src/interfaces/api/handlers`
- [DAV handlers](https://github.com/atalayalabs/oxicloud/tree/main/src/interfaces/api/handlers): `src/interfaces/api/handlers`
- [Authentication](https://github.com/atalayalabs/oxicloud/blob/main/src/interfaces/api/handlers/auth_handler.rs): `src/interfaces/api/handlers/auth_handler.rs`
- [WOPI handler](https://github.com/atalayalabs/oxicloud/blob/main/src/interfaces/api/handlers/wopi_handler.rs): `src/interfaces/api/handlers/wopi_handler.rs`

### Application services

- [File workflows](https://github.com/atalayalabs/oxicloud/tree/main/src/application/services): `src/application/services`
- [File retrieval](https://github.com/atalayalabs/oxicloud/blob/main/src/application/services/file_retrieval_service.rs): `src/application/services/file_retrieval_service.rs`
- [Sharing and search](https://github.com/atalayalabs/oxicloud/tree/main/src/application/services): `src/application/services`
- [Calendar and contacts](https://github.com/atalayalabs/oxicloud/tree/main/src/application/services): `src/application/services`
- [Identity and access](https://github.com/atalayalabs/oxicloud/tree/main/src/application/services): `src/application/services`
- [Live collaboration](https://github.com/atalayalabs/oxicloud/blob/main/src/application/services/collab_session_service.rs): `src/application/services/collab_session_service.rs`
- [Media processing](https://github.com/atalayalabs/oxicloud/tree/main/src/infrastructure/services): `src/infrastructure/services`

### Infrastructure

- [Blob backends](https://github.com/atalayalabs/oxicloud/tree/main/src/infrastructure/services): `src/infrastructure/services`
- [Postgres repositories](https://github.com/atalayalabs/oxicloud/tree/main/src/infrastructure/repositories/pg): `src/infrastructure/repositories/pg`
- [Authorization engine](https://github.com/atalayalabs/oxicloud/blob/main/src/infrastructure/services/pg_acl_engine.rs): `src/infrastructure/services/pg_acl_engine.rs`
- [Background jobs](https://github.com/atalayalabs/oxicloud/tree/main/src/infrastructure/scheduler): `src/infrastructure/scheduler`

### Persistent state

- **PostgreSQL**
- **Blob storage**

### Other components

- **Cloud user**
- **DAV client**
- **Collabora / OnlyOffice**
- **OIDC provider**

## Connections

- Cloud user → Web application: uses
- Web application → REST API client: requests
- REST API client → API routing: calls
- API routing → File handlers: routes
- API routing → Authentication: routes
- File handlers → File workflows: invokes
- File handlers → File retrieval: invokes
- File retrieval → Blob backends: reads
- File workflows → Blob backends: stores content
- File workflows → Postgres repositories: persists metadata
- File retrieval → Postgres repositories: reads metadata
- Postgres repositories → PostgreSQL: reads and writes
- Blob backends → Blob storage: reads and writes
- DAV client → DAV handlers: uses DAV
- DAV handlers → Calendar and contacts: invokes
- Calendar and contacts → Postgres repositories: persists records
- File handlers → Sharing and search: invokes
- Sharing and search → Authorization engine: checks access
- Authorization engine → PostgreSQL: queries grants
- Authentication → Identity and access: invokes
- Identity and access → OIDC provider: authenticates
- API routing → WOPI handler: routes
- WOPI handler → Collabora / OnlyOffice: serves editing
- File handlers → Media processing: requests previews
- Media processing → Blob backends: reads content
- Cloud user → Live collaboration: edits together
- Live collaboration → PostgreSQL: stores sessions
- Background jobs → PostgreSQL: stores job state