# legspcpd/cloudreve-worker architecture

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

- Interactive diagram: https://gitdiagram.com/legspcpd/cloudreve-worker
- Repository: https://github.com/legspcpd/cloudreve-worker

## Overview

Cloudreve-Worker is a Cloudreve v4 backend on Cloudflare Workers, shipped with the official patched frontend. The main workflow is a user request through the Worker and request context into domain routes, file services, storage policies, and database/KV state, with a response back to the client. Separate branches cover authentication, sharing, WebDAV, administration, search, workflows, payments, and audit. The index and excerpts support the runtime wiring shown; broader feature links are documented in the README, while unsampled route internals are represented at their exact paths.

Main entry points: [`src/routes`](https://github.com/legspcpd/cloudreve-worker/tree/main/src/routes) (API route handlers), [`src/middleware/app.ts`](https://github.com/legspcpd/cloudreve-worker/blob/main/src/middleware/app.ts) (Request context), [`src/services/fs.ts`](https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/fs.ts) (File operations), [`frontend-patches/src/App.tsx`](https://github.com/legspcpd/cloudreve-worker/blob/main/frontend-patches/src/App.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_user(("User / client"))
end

subgraph group_runtime["Worker runtime"]
  node_worker["Worker entry<br/>[index.ts]"]
  node_middleware["Request context<br/>[app.ts]"]
  node_config["Settings provider<br/>[provider.ts]"]
  node_routes["API route handlers"]
end

subgraph group_domain["Cloudreve domains"]
  node_auth["Sessions and identity<br/>[session.ts]"]
  node_fileops["File operations<br/>[fs.ts]"]
  node_upload["Upload and download<br/>[upload.ts]"]
  node_share["Sharing and links<br/>[share.ts]"]
  node_webdav["WebDAV access<br/>[dav.ts]"]
  node_search["Full-text search<br/>[search.ts]"]
  node_workflow["Offline workflows<br/>[workflow.ts]"]
  node_payments["Payments and gifts<br/>[payment.ts]"]
  node_admin["Administration<br/>[admin.ts]"]
  node_audit["Audit events<br/>[audit.ts]"]
end

subgraph group_state["State and storage"]
  node_storagefactory["Storage driver factory<br/>[index.ts]"]
  node_drivers["Storage providers"]
  node_repositories["Data repositories<br/>[repo.ts]"]
  node_postgres[("Neon Postgres<br/>[index.ts]")]
  node_dbrouter["Database routing<br/>[shard.ts]"]
  node_kv["KV role router<br/>[kvRouter.ts]"]
end

subgraph group_frontend["Web frontend"]
  node_frontendapp["Web application<br/>[App.tsx]"]
  node_frontendapi["Frontend API client<br/>[api.ts]"]
  node_explorer["File explorer UI<br/>[explorer.ts]"]
  node_dashboard["Admin dashboard UI<br/>[dashboard.ts]"]
end

node_user -->|"uses"| node_frontendapp
node_frontendapp -->|"calls"| node_frontendapi
node_frontendapi -.->|"requests"| node_worker
node_user -->|"requests"| node_worker
node_worker -->|"builds context"| node_middleware
node_worker -->|"dispatches"| node_routes
node_middleware -->|"loads"| node_config
node_middleware -->|"resolves database"| node_dbrouter
node_routes -->|"routes requests"| node_auth
node_routes -->|"routes requests"| node_fileops
node_routes -->|"routes requests"| node_share
node_routes -->|"routes requests"| node_webdav
node_routes -->|"routes requests"| node_search
node_routes -->|"routes requests"| node_workflow
node_routes -->|"routes requests"| node_payments
node_routes -->|"routes requests"| node_admin
node_fileops -->|"uses"| node_upload
node_fileops -->|"selects driver"| node_storagefactory
node_storagefactory -->|"creates driver"| node_drivers
node_fileops -->|"reads and writes"| node_repositories
node_repositories -->|"executes SQL"| node_postgres
node_dbrouter -->|"selects connection"| node_postgres
node_middleware -->|"uses role bindings"| node_kv
node_repositories -->|"uses cached records"| node_kv
node_admin -->|"records events"| node_audit
node_explorer -->|"uses API"| node_frontendapi
node_dashboard -->|"uses API"| node_frontendapi
node_frontendapp -.->|"presents files"| node_explorer
node_frontendapp -.->|"presents administration"| node_dashboard

click node_worker "https://github.com/legspcpd/cloudreve-worker/blob/main/src/index.ts"
click node_middleware "https://github.com/legspcpd/cloudreve-worker/blob/main/src/middleware/app.ts"
click node_config "https://github.com/legspcpd/cloudreve-worker/blob/main/src/settings/provider.ts"
click node_routes "https://github.com/legspcpd/cloudreve-worker/tree/main/src/routes"
click node_auth "https://github.com/legspcpd/cloudreve-worker/blob/main/src/routes/session.ts"
click node_fileops "https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/fs.ts"
click node_upload "https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/upload.ts"
click node_share "https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/share.ts"
click node_webdav "https://github.com/legspcpd/cloudreve-worker/blob/main/src/routes/dav.ts"
click node_search "https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/search.ts"
click node_workflow "https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/workflow.ts"
click node_payments "https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/payment.ts"
click node_admin "https://github.com/legspcpd/cloudreve-worker/blob/main/src/routes/admin.ts"
click node_audit "https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/audit.ts"
click node_storagefactory "https://github.com/legspcpd/cloudreve-worker/blob/main/src/storage/index.ts"
click node_drivers "https://github.com/legspcpd/cloudreve-worker/tree/main/src/storage"
click node_repositories "https://github.com/legspcpd/cloudreve-worker/blob/main/src/db/repo.ts"
click node_postgres "https://github.com/legspcpd/cloudreve-worker/blob/main/src/db/index.ts"
click node_dbrouter "https://github.com/legspcpd/cloudreve-worker/blob/main/src/db/shard.ts"
click node_kv "https://github.com/legspcpd/cloudreve-worker/blob/main/src/lib/kvRouter.ts"
click node_frontendapp "https://github.com/legspcpd/cloudreve-worker/blob/main/frontend-patches/src/App.tsx"
click node_frontendapi "https://github.com/legspcpd/cloudreve-worker/blob/main/frontend-patches/src/api/api.ts"
click node_explorer "https://github.com/legspcpd/cloudreve-worker/blob/main/frontend-patches/src/api/explorer.ts"
click node_dashboard "https://github.com/legspcpd/cloudreve-worker/blob/main/frontend-patches/src/api/dashboard.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_user toneBlue
class node_worker,node_middleware,node_config,node_routes toneAmber
class node_auth,node_fileops,node_upload,node_share,node_webdav,node_search,node_workflow,node_payments,node_admin,node_audit toneMint
class node_storagefactory,node_drivers,node_repositories,node_postgres,node_dbrouter,node_kv toneRose
class node_frontendapp,node_frontendapi,node_explorer,node_dashboard toneIndigo
```

## Components

### Client

- **User / client**

### Worker runtime

- [Worker entry](https://github.com/legspcpd/cloudreve-worker/blob/main/src/index.ts): `src/index.ts`
- [Request context](https://github.com/legspcpd/cloudreve-worker/blob/main/src/middleware/app.ts): `src/middleware/app.ts`
- [Settings provider](https://github.com/legspcpd/cloudreve-worker/blob/main/src/settings/provider.ts): `src/settings/provider.ts`
- [API route handlers](https://github.com/legspcpd/cloudreve-worker/tree/main/src/routes): `src/routes`

### Cloudreve domains

- [Sessions and identity](https://github.com/legspcpd/cloudreve-worker/blob/main/src/routes/session.ts): `src/routes/session.ts`
- [File operations](https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/fs.ts): `src/services/fs.ts`
- [Upload and download](https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/upload.ts): `src/services/upload.ts`
- [Sharing and links](https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/share.ts): `src/services/share.ts`
- [WebDAV access](https://github.com/legspcpd/cloudreve-worker/blob/main/src/routes/dav.ts): `src/routes/dav.ts`
- [Full-text search](https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/search.ts): `src/services/search.ts`
- [Offline workflows](https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/workflow.ts): `src/services/workflow.ts`
- [Payments and gifts](https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/payment.ts): `src/services/payment.ts`
- [Administration](https://github.com/legspcpd/cloudreve-worker/blob/main/src/routes/admin.ts): `src/routes/admin.ts`
- [Audit events](https://github.com/legspcpd/cloudreve-worker/blob/main/src/services/audit.ts): `src/services/audit.ts`

### State and storage

- [Storage driver factory](https://github.com/legspcpd/cloudreve-worker/blob/main/src/storage/index.ts): `src/storage/index.ts`
- [Storage providers](https://github.com/legspcpd/cloudreve-worker/tree/main/src/storage): `src/storage`
- [Data repositories](https://github.com/legspcpd/cloudreve-worker/blob/main/src/db/repo.ts): `src/db/repo.ts`
- [Neon Postgres](https://github.com/legspcpd/cloudreve-worker/blob/main/src/db/index.ts): `src/db/index.ts`
- [Database routing](https://github.com/legspcpd/cloudreve-worker/blob/main/src/db/shard.ts): `src/db/shard.ts`
- [KV role router](https://github.com/legspcpd/cloudreve-worker/blob/main/src/lib/kvRouter.ts): `src/lib/kvRouter.ts`

### Web frontend

- [Web application](https://github.com/legspcpd/cloudreve-worker/blob/main/frontend-patches/src/App.tsx): `frontend-patches/src/App.tsx`
- [Frontend API client](https://github.com/legspcpd/cloudreve-worker/blob/main/frontend-patches/src/api/api.ts): `frontend-patches/src/api/api.ts`
- [File explorer UI](https://github.com/legspcpd/cloudreve-worker/blob/main/frontend-patches/src/api/explorer.ts): `frontend-patches/src/api/explorer.ts`
- [Admin dashboard UI](https://github.com/legspcpd/cloudreve-worker/blob/main/frontend-patches/src/api/dashboard.ts): `frontend-patches/src/api/dashboard.ts`

## Connections

- User / client → Web application: uses
- Web application → Frontend API client: calls (evidence: `frontend-patches/src/api/api.ts`)
- Frontend API client → Worker entry: requests
- User / client → Worker entry: requests
- Worker entry → Request context: builds context (evidence: `src/index.ts`)
- Worker entry → API route handlers: dispatches (evidence: `src/index.ts`)
- Request context → Settings provider: loads (evidence: `src/middleware/app.ts`)
- Request context → Database routing: resolves database (evidence: `src/middleware/app.ts`)
- API route handlers → Sessions and identity: routes requests (evidence: `src/index.ts`)
- API route handlers → File operations: routes requests (evidence: `src/index.ts`)
- API route handlers → Sharing and links: routes requests
- API route handlers → WebDAV access: routes requests
- API route handlers → Full-text search: routes requests
- API route handlers → Offline workflows: routes requests
- API route handlers → Payments and gifts: routes requests
- API route handlers → Administration: routes requests
- File operations → Upload and download: uses (evidence: `src/services/fs.ts`)
- File operations → Storage driver factory: selects driver (evidence: `src/services/fs.ts`)
- Storage driver factory → Storage providers: creates driver (evidence: `src/storage/index.ts`)
- File operations → Data repositories: reads and writes (evidence: `src/services/fs.ts`)
- Data repositories → Neon Postgres: executes SQL (evidence: `src/db/repo.ts`)
- Database routing → Neon Postgres: selects connection (evidence: `src/db/shard.ts`)
- Request context → KV role router: uses role bindings (evidence: `src/middleware/app.ts`)
- Data repositories → KV role router: uses cached records (evidence: `src/db/repo.ts`)
- Administration → Audit events: records events
- File explorer UI → Frontend API client: uses API (evidence: `frontend-patches/src/api/api.ts`)
- Admin dashboard UI → Frontend API client: uses API (evidence: `frontend-patches/src/api/api.ts`)
- Web application → File explorer UI: presents files
- Web application → Admin dashboard UI: presents administration