# openlistteam/openlist architecture

> Architecture diagram of the GitHub repository openlistteam/openlist, 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/openlistteam/openlist
- Repository: https://github.com/openlistteam/openlist

## Overview

OpenList is a self-hosted, multi-storage file access and sharing server. A principal workflow starts with a client request, enters through the HTTP router, and reaches file handlers; the README also documents browsing, preview, downloads, file management, sharing, and integrations such as WebDAV and offline downloads. Storage administration persists configurations and loads enabled mounts through the storage operations layer. The graph includes documented capabilities whose detailed implementation was not sampled; those branches are not presented as verified call paths.

Main entry points: [`server/handles`](https://github.com/openlistteam/openlist/tree/main/server/handles) (File handlers), [`server/router.go`](https://github.com/openlistteam/openlist/blob/main/server/router.go) (HTTP router), [`internal/op/storage.go`](https://github.com/openlistteam/openlist/blob/main/internal/op/storage.go) (Storage lifecycle), [`server/handles/storage.go`](https://github.com/openlistteam/openlist/blob/main/server/handles/storage.go) (Storage admin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP access"]
  node_router["HTTP router<br/>[router.go]"]
  node_file_handlers["File handlers"]
  node_mcp["MCP interface<br/>[handler.go]"]
  node_webdav["WebDAV access<br/>[webdav.go]"]
  node_storage_handlers["Storage admin<br/>[storage.go]"]
end

subgraph group_files["File capabilities"]
  node_file_ops["File operations"]
  node_archive["Archive access"]
  node_sharing["Sharing"]
  node_multipart["Multipart uploads<br/>[session.go]"]
end

subgraph group_storage["Storage runtime"]
  node_storage_ops["Storage lifecycle<br/>[storage.go]"]
  node_storage_details["Mount details<br/>[storage_details.go]"]
  node_driver_adapters["Storage adapters"]
  node_storage_db[("Storage records<br/>[storage.go]")]
  node_bootstrap["Startup loading<br/>[storage.go]"]
end

subgraph group_services["Media and tasks"]
  node_search["Search<br/>[search.go]"]
  node_media["Media library<br/>[scanner.go]"]
  node_offline["Offline downloads"]
  node_transcode["Video transcoding<br/>[chunk_manager.go]"]
  node_task_manager["Task manager<br/>[manager.go]"]
end

node_client(("Client"))

node_client -->|"requests"| node_router
node_router -->|"routes to"| node_file_handlers
node_router -.->|"registers"| node_mcp
node_router -.->|"serves"| node_webdav
node_router -.->|"routes to"| node_storage_handlers
node_storage_handlers -->|"manages"| node_storage_ops
node_storage_ops -->|"persists"| node_storage_db
node_bootstrap -->|"loads enabled"| node_storage_db
node_bootstrap -->|"initializes mounts"| node_storage_ops
node_storage_ops -.->|"initializes"| node_driver_adapters
node_storage_handlers -->|"reads details"| node_storage_details
node_file_handlers -.->|"uses"| node_file_ops
node_file_handlers -.->|"supports packages"| node_archive
node_file_handlers -.->|"serves shares"| node_sharing
node_file_handlers -.->|"uploads chunks"| node_multipart
node_file_handlers -->|"searches"| node_search
node_client -.->|"requests downloads"| node_offline
node_client -.->|"previews media"| node_media
node_client -.->|"streams video"| node_transcode
node_offline -.->|"schedules tasks"| node_task_manager

click node_router "https://github.com/openlistteam/openlist/blob/main/server/router.go"
click node_file_handlers "https://github.com/openlistteam/openlist/tree/main/server/handles"
click node_mcp "https://github.com/openlistteam/openlist/blob/main/server/mcp/handler.go"
click node_webdav "https://github.com/openlistteam/openlist/blob/main/server/webdav/webdav.go"
click node_storage_handlers "https://github.com/openlistteam/openlist/blob/main/server/handles/storage.go"
click node_file_ops "https://github.com/openlistteam/openlist/tree/main/internal/fs"
click node_archive "https://github.com/openlistteam/openlist/tree/main/internal/archive"
click node_sharing "https://github.com/openlistteam/openlist/tree/main/internal/sharing"
click node_multipart "https://github.com/openlistteam/openlist/blob/main/internal/multipart/session.go"
click node_storage_ops "https://github.com/openlistteam/openlist/blob/main/internal/op/storage.go"
click node_storage_details "https://github.com/openlistteam/openlist/blob/main/internal/op/storage_details.go"
click node_driver_adapters "https://github.com/openlistteam/openlist/tree/main/drivers"
click node_storage_db "https://github.com/openlistteam/openlist/blob/main/internal/db/storage.go"
click node_bootstrap "https://github.com/openlistteam/openlist/blob/main/internal/bootstrap/storage.go"
click node_search "https://github.com/openlistteam/openlist/blob/main/internal/search/search.go"
click node_media "https://github.com/openlistteam/openlist/blob/main/internal/media/scanner.go"
click node_offline "https://github.com/openlistteam/openlist/tree/main/internal/offline_download"
click node_transcode "https://github.com/openlistteam/openlist/blob/main/internal/transcode/chunk_manager.go"
click node_task_manager "https://github.com/openlistteam/openlist/blob/main/internal/task/manager.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_router,node_file_handlers,node_mcp,node_webdav,node_storage_handlers,node_client toneBlue
class node_file_ops,node_archive,node_sharing,node_multipart toneAmber
class node_storage_ops,node_storage_details,node_driver_adapters,node_storage_db,node_bootstrap toneMint
class node_search,node_media,node_offline,node_transcode,node_task_manager toneRose
```

## Components

### HTTP access

- [HTTP router](https://github.com/openlistteam/openlist/blob/main/server/router.go): `server/router.go`
- [File handlers](https://github.com/openlistteam/openlist/tree/main/server/handles): `server/handles`
- [MCP interface](https://github.com/openlistteam/openlist/blob/main/server/mcp/handler.go): `server/mcp/handler.go`
- [WebDAV access](https://github.com/openlistteam/openlist/blob/main/server/webdav/webdav.go): `server/webdav/webdav.go`
- [Storage admin](https://github.com/openlistteam/openlist/blob/main/server/handles/storage.go): `server/handles/storage.go`

### File capabilities

- [File operations](https://github.com/openlistteam/openlist/tree/main/internal/fs): `internal/fs`
- [Archive access](https://github.com/openlistteam/openlist/tree/main/internal/archive): `internal/archive`
- [Sharing](https://github.com/openlistteam/openlist/tree/main/internal/sharing): `internal/sharing`
- [Multipart uploads](https://github.com/openlistteam/openlist/blob/main/internal/multipart/session.go): `internal/multipart/session.go`

### Storage runtime

- [Storage lifecycle](https://github.com/openlistteam/openlist/blob/main/internal/op/storage.go): `internal/op/storage.go`
- [Mount details](https://github.com/openlistteam/openlist/blob/main/internal/op/storage_details.go): `internal/op/storage_details.go`
- [Storage adapters](https://github.com/openlistteam/openlist/tree/main/drivers): `drivers`
- [Storage records](https://github.com/openlistteam/openlist/blob/main/internal/db/storage.go): `internal/db/storage.go`
- [Startup loading](https://github.com/openlistteam/openlist/blob/main/internal/bootstrap/storage.go): `internal/bootstrap/storage.go`

### Media and tasks

- [Search](https://github.com/openlistteam/openlist/blob/main/internal/search/search.go): `internal/search/search.go`
- [Media library](https://github.com/openlistteam/openlist/blob/main/internal/media/scanner.go): `internal/media/scanner.go`
- [Offline downloads](https://github.com/openlistteam/openlist/tree/main/internal/offline_download): `internal/offline_download`
- [Video transcoding](https://github.com/openlistteam/openlist/blob/main/internal/transcode/chunk_manager.go): `internal/transcode/chunk_manager.go`
- [Task manager](https://github.com/openlistteam/openlist/blob/main/internal/task/manager.go): `internal/task/manager.go`

### Other components

- **Client**

## Connections

- Client → HTTP router: requests (evidence: `server/router.go`)
- HTTP router → File handlers: routes to (evidence: `server/router.go`)
- HTTP router → MCP interface: registers
- HTTP router → WebDAV access: serves
- HTTP router → Storage admin: routes to
- Storage admin → Storage lifecycle: manages (evidence: `server/handles/storage.go`)
- Storage lifecycle → Storage records: persists (evidence: `internal/op/storage.go`)
- Startup loading → Storage records: loads enabled (evidence: `internal/bootstrap/storage.go`)
- Startup loading → Storage lifecycle: initializes mounts (evidence: `internal/bootstrap/storage.go`)
- Storage lifecycle → Storage adapters: initializes
- Storage admin → Mount details: reads details (evidence: `server/handles/storage.go`)
- File handlers → File operations: uses
- File handlers → Archive access: supports packages
- File handlers → Sharing: serves shares
- File handlers → Multipart uploads: uploads chunks
- File handlers → Search: searches (evidence: `server/handles/index.go`)
- Client → Offline downloads: requests downloads
- Client → Media library: previews media
- Client → Video transcoding: streams video
- Offline downloads → Task manager: schedules tasks
