# wxwmoe/mokyu architecture

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

## Overview

Mokyu is a Rust S3-compatible media-storage gateway. S3 clients submit object and multipart operations through the protocol and HTTP layers; the application processes streams into content-defined, deduplicated chunks, then stores encoded data through a local cache and S3-compatible backend while PostgreSQL tracks objects and chunk metadata. Reads resolve stored objects and return data, including range reads. The product also exposes a management UI/API and background integrity, lifecycle, packing, cleanup, and statistics capabilities. Some subsystem links reflect documented capabilities and module roles; unsampled source wiring is not asserted.

Main entry points: [`src/app.rs`](https://github.com/wxwmoe/mokyu/blob/main/src/app.rs) (Application core), [`src/tasks.rs`](https://github.com/wxwmoe/mokyu/blob/main/src/tasks.rs) (Task coordinator), [`src/http.rs`](https://github.com/wxwmoe/mokyu/blob/main/src/http.rs) (HTTP routing), [`src/main.rs`](https://github.com/wxwmoe/mokyu/blob/main/src/main.rs) (Service runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_main["Service runtime<br/>[main.rs]"]
  node_http["HTTP routing<br/>[http.rs]"]
  node_s3["S3 protocol<br/>[s3.rs]"]
end

subgraph group_objects["Object pipeline"]
  node_app["Application core<br/>[app.rs]"]
  node_upload["Object uploads<br/>[upload.rs]"]
  node_multipart["Multipart uploads<br/>[multipart.rs]"]
  node_codec["Chunk codec<br/>[codec.rs]"]
  node_compression["Compression<br/>[compression.rs]"]
  node_range["Range reads<br/>[range.rs]"]
  node_listing["Object listing<br/>[listing.rs]"]
end

subgraph group_persistence["Persistence"]
  node_storage["Chunk storage<br/>[storage.rs]"]
  node_backend["S3 backend<br/>[backend.rs]"]
  node_database[("PostgreSQL")]
  node_dbinit["Database setup<br/>[db.rs]"]
  node_config["Configuration<br/>[config.rs]"]
end

subgraph group_operations["Background operations"]
  node_tasks["Task coordinator<br/>[tasks.rs]"]
  node_packtasks["Pack maintenance<br/>[pack_tasks.rs]"]
  node_integrity["Integrity checks<br/>[integrity.rs]"]
  node_lifecycle["Lifecycle cleanup<br/>[lifecycle.rs]"]
  node_stats["Statistics<br/>[stats.rs]"]
end

subgraph group_management["Management"]
  node_admin["Management API<br/>[admin.rs]"]
  node_web["Management UI<br/>[app.js]"]
end

node_s3client(("S3 client"))
node_operator(("Operator"))
node_browser(("Admin browser"))

node_main -->|"initializes"| node_app
node_main -->|"serves"| node_http
node_main -->|"runs"| node_tasks
node_s3client -->|"requests"| node_http
node_http -->|"dispatches"| node_s3
node_s3 -->|"invokes"| node_app
node_s3 -->|"invokes"| node_multipart
node_app -->|"processes uploads"| node_upload
node_app -->|"encodes chunks"| node_codec
node_app -->|"stores and reads"| node_storage
node_app -->|"queries and updates"| node_database
node_multipart -->|"publishes objects"| node_app
node_app -->|"serves ranges"| node_range
node_app -->|"lists objects"| node_listing
node_storage -->|"reads and writes"| node_backend
node_backend -.->|"uses metadata"| node_database
node_dbinit -->|"initializes schema"| node_database
node_config -->|"configures"| node_app
node_tasks -->|"dispatches pack work"| node_packtasks
node_tasks -->|"dispatches checks"| node_integrity
node_tasks -->|"runs cleanup"| node_lifecycle
node_tasks -->|"claims task state"| node_database
node_main -->|"runs"| node_stats
node_http -->|"serves management"| node_admin
node_operator -->|"administers"| node_admin
node_browser -->|"uses"| node_web
node_web -->|"calls API"| node_http
node_admin -->|"requests tasks"| node_tasks

click node_main "https://github.com/wxwmoe/mokyu/blob/main/src/main.rs"
click node_http "https://github.com/wxwmoe/mokyu/blob/main/src/http.rs"
click node_s3 "https://github.com/wxwmoe/mokyu/blob/main/src/s3.rs"
click node_app "https://github.com/wxwmoe/mokyu/blob/main/src/app.rs"
click node_upload "https://github.com/wxwmoe/mokyu/blob/main/src/upload.rs"
click node_multipart "https://github.com/wxwmoe/mokyu/blob/main/src/multipart.rs"
click node_codec "https://github.com/wxwmoe/mokyu/blob/main/src/codec.rs"
click node_compression "https://github.com/wxwmoe/mokyu/blob/main/src/compression.rs"
click node_range "https://github.com/wxwmoe/mokyu/blob/main/src/range.rs"
click node_listing "https://github.com/wxwmoe/mokyu/blob/main/src/listing.rs"
click node_storage "https://github.com/wxwmoe/mokyu/blob/main/src/storage.rs"
click node_backend "https://github.com/wxwmoe/mokyu/blob/main/src/backend.rs"
click node_dbinit "https://github.com/wxwmoe/mokyu/blob/main/src/db.rs"
click node_config "https://github.com/wxwmoe/mokyu/blob/main/src/config.rs"
click node_tasks "https://github.com/wxwmoe/mokyu/blob/main/src/tasks.rs"
click node_packtasks "https://github.com/wxwmoe/mokyu/blob/main/src/pack_tasks.rs"
click node_integrity "https://github.com/wxwmoe/mokyu/blob/main/src/integrity.rs"
click node_lifecycle "https://github.com/wxwmoe/mokyu/blob/main/src/lifecycle.rs"
click node_stats "https://github.com/wxwmoe/mokyu/blob/main/src/stats.rs"
click node_admin "https://github.com/wxwmoe/mokyu/blob/main/src/admin.rs"
click node_web "https://github.com/wxwmoe/mokyu/blob/main/web/app.js"

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_main,node_http,node_s3,node_s3client,node_browser toneBlue
class node_app,node_upload,node_multipart,node_codec,node_compression,node_range,node_listing toneAmber
class node_storage,node_backend,node_database,node_dbinit,node_config toneMint
class node_tasks,node_packtasks,node_integrity,node_lifecycle,node_stats toneRose
class node_admin,node_web,node_operator toneIndigo
```

## Components

### Interfaces

- [Service runtime](https://github.com/wxwmoe/mokyu/blob/main/src/main.rs): `src/main.rs`
- [HTTP routing](https://github.com/wxwmoe/mokyu/blob/main/src/http.rs): `src/http.rs`
- [S3 protocol](https://github.com/wxwmoe/mokyu/blob/main/src/s3.rs): `src/s3.rs`

### Object pipeline

- [Application core](https://github.com/wxwmoe/mokyu/blob/main/src/app.rs): `src/app.rs`
- [Object uploads](https://github.com/wxwmoe/mokyu/blob/main/src/upload.rs): `src/upload.rs`
- [Multipart uploads](https://github.com/wxwmoe/mokyu/blob/main/src/multipart.rs): `src/multipart.rs`
- [Chunk codec](https://github.com/wxwmoe/mokyu/blob/main/src/codec.rs): `src/codec.rs`
- [Compression](https://github.com/wxwmoe/mokyu/blob/main/src/compression.rs): `src/compression.rs`
- [Range reads](https://github.com/wxwmoe/mokyu/blob/main/src/range.rs): `src/range.rs`
- [Object listing](https://github.com/wxwmoe/mokyu/blob/main/src/listing.rs): `src/listing.rs`

### Persistence

- [Chunk storage](https://github.com/wxwmoe/mokyu/blob/main/src/storage.rs): `src/storage.rs`
- [S3 backend](https://github.com/wxwmoe/mokyu/blob/main/src/backend.rs): `src/backend.rs`
- **PostgreSQL**
- [Database setup](https://github.com/wxwmoe/mokyu/blob/main/src/db.rs): `src/db.rs`
- [Configuration](https://github.com/wxwmoe/mokyu/blob/main/src/config.rs): `src/config.rs`

### Background operations

- [Task coordinator](https://github.com/wxwmoe/mokyu/blob/main/src/tasks.rs): `src/tasks.rs`
- [Pack maintenance](https://github.com/wxwmoe/mokyu/blob/main/src/pack_tasks.rs): `src/pack_tasks.rs`
- [Integrity checks](https://github.com/wxwmoe/mokyu/blob/main/src/integrity.rs): `src/integrity.rs`
- [Lifecycle cleanup](https://github.com/wxwmoe/mokyu/blob/main/src/lifecycle.rs): `src/lifecycle.rs`
- [Statistics](https://github.com/wxwmoe/mokyu/blob/main/src/stats.rs): `src/stats.rs`

### Management

- [Management API](https://github.com/wxwmoe/mokyu/blob/main/src/admin.rs): `src/admin.rs`
- [Management UI](https://github.com/wxwmoe/mokyu/blob/main/web/app.js): `web/app.js`

### Other components

- **S3 client**
- **Operator**
- **Admin browser**

## Connections

- Service runtime → Application core: initializes
- Service runtime → HTTP routing: serves
- Service runtime → Task coordinator: runs
- S3 client → HTTP routing: requests
- HTTP routing → S3 protocol: dispatches
- S3 protocol → Application core: invokes
- S3 protocol → Multipart uploads: invokes
- Application core → Object uploads: processes uploads
- Application core → Chunk codec: encodes chunks
- Application core → Chunk storage: stores and reads
- Application core → PostgreSQL: queries and updates
- Multipart uploads → Application core: publishes objects
- Application core → Range reads: serves ranges
- Application core → Object listing: lists objects
- Chunk storage → S3 backend: reads and writes
- S3 backend → PostgreSQL: uses metadata
- Database setup → PostgreSQL: initializes schema
- Configuration → Application core: configures
- Task coordinator → Pack maintenance: dispatches pack work
- Task coordinator → Integrity checks: dispatches checks
- Task coordinator → Lifecycle cleanup: runs cleanup
- Task coordinator → PostgreSQL: claims task state
- Service runtime → Statistics: runs
- HTTP routing → Management API: serves management
- Operator → Management API: administers
- Admin browser → Management UI: uses
- Management UI → HTTP routing: calls API
- Management API → Task coordinator: requests tasks