# zkishere/telecrate architecture

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

- Interactive diagram: https://gitdiagram.com/zkishere/telecrate
- Repository: https://github.com/zkishere/telecrate

## Overview

TeleCrate is a self-hosted S3-compatible object-storage gateway that durably accepts object data into a local spool and SQLite/Postgres index, then uploads chunks asynchronously to Telegram. The principal path is S3 client → HTTP/S3 handling and SigV4 authorization → local durable storage and job record → background worker → Telegram. Separate capabilities include multipart/versioned objects, encryption and access controls, plus an authenticated administration dashboard for monitoring and maintenance. Unsampled handlers are represented only where README capabilities and the tree support them; uncertain internal call links are omitted.

Main entry points: [`src/app.rs`](https://github.com/zkishere/telecrate/blob/master/src/app.rs) (HTTP router), [`src/db/mod.rs`](https://github.com/zkishere/telecrate/blob/master/src/db/mod.rs) (Metadata and jobs), [`src/main.rs`](https://github.com/zkishere/telecrate/blob/master/src/main.rs) (Daemon entry), [`src/worker.rs`](https://github.com/zkishere/telecrate/blob/master/src/worker.rs) (Upload workers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Daemon runtime"]
  node_main["Daemon entry<br/>[main.rs]"]
  node_config["Configuration<br/>[config.rs]"]
end

subgraph group_gateway["S3 gateway"]
  node_app["HTTP router<br/>[app.rs]"]
  node_sigv4["SigV4 auth<br/>[sigv4.rs]"]
  node_s3["S3 operations<br/>[s3.rs]"]
  node_policy["Bucket policies<br/>[policy.rs]"]
  node_cors["CORS rules<br/>[cors.rs]"]
  node_crypto["Object encryption<br/>[crypto.rs]"]
  node_multipart["Multipart and versions<br/>[app.rs]"]
end

subgraph group_storage["Durable storage"]
  node_spool["Local spool<br/>[spool.rs]"]
  node_db[("Metadata and jobs<br/>[mod.rs]")]
  node_worker["Upload workers<br/>[worker.rs]"]
  node_telegram_transport["Telegram transport<br/>[telegram.rs]"]
end

subgraph group_admin["Administration"]
  node_admin["Admin API<br/>[admin.rs]"]
  node_dashboard["Web dashboard<br/>[app.js]"]
  node_gc["Garbage collection<br/>[gc.rs]"]
  node_doctor["Health and repair<br/>[doctor.rs]"]
  node_recovery["Recovery tools<br/>[recovery.rs]"]
end

node_s3client(("S3 clients"))
node_operator(("Admin operator"))
node_telegram(("Telegram Bot API"))

node_main -->|"loads settings"| node_config
node_main -->|"opens index"| node_db
node_main -->|"serves routes"| node_app
node_main -->|"starts workers"| node_worker
node_s3client -->|"sends S3 requests"| node_app
node_app -->|"authenticates requests"| node_sigv4
node_app -->|"dispatches S3 actions"| node_s3
node_app -->|"reads and writes"| node_db
node_app -->|"stores chunks"| node_spool
node_app -->|"encrypts content"| node_crypto
node_app -->|"checks access policy"| node_policy
node_app -->|"checks CORS"| node_cors
node_app -->|"handles multipart/versioning"| node_multipart
node_worker -->|"claims and commits jobs"| node_db
node_worker -->|"reads chunks"| node_spool
node_worker -->|"uploads chunks"| node_telegram_transport
node_telegram_transport -->|"calls Bot API"| node_telegram
node_app -->|"deletes remote chunks"| node_telegram_transport
node_operator -->|"uses dashboard"| node_dashboard
node_dashboard -->|"calls admin routes"| node_app
node_app -->|"dispatches admin routes"| node_admin
node_admin -->|"queries and updates"| node_db
node_admin -->|"runs cleanup"| node_gc
node_admin -->|"checks health"| node_doctor
node_db -.->|"supports recovery"| node_recovery

click node_main "https://github.com/zkishere/telecrate/blob/master/src/main.rs"
click node_config "https://github.com/zkishere/telecrate/blob/master/src/config.rs"
click node_app "https://github.com/zkishere/telecrate/blob/master/src/app.rs"
click node_sigv4 "https://github.com/zkishere/telecrate/blob/master/src/sigv4.rs"
click node_s3 "https://github.com/zkishere/telecrate/blob/master/src/s3.rs"
click node_policy "https://github.com/zkishere/telecrate/blob/master/src/policy.rs"
click node_cors "https://github.com/zkishere/telecrate/blob/master/src/cors.rs"
click node_crypto "https://github.com/zkishere/telecrate/blob/master/src/crypto.rs"
click node_multipart "https://github.com/zkishere/telecrate/blob/master/src/app.rs"
click node_spool "https://github.com/zkishere/telecrate/blob/master/src/spool.rs"
click node_db "https://github.com/zkishere/telecrate/blob/master/src/db/mod.rs"
click node_worker "https://github.com/zkishere/telecrate/blob/master/src/worker.rs"
click node_telegram_transport "https://github.com/zkishere/telecrate/blob/master/src/telegram.rs"
click node_admin "https://github.com/zkishere/telecrate/blob/master/src/admin.rs"
click node_dashboard "https://github.com/zkishere/telecrate/blob/master/src/dashboard/app.js"
click node_gc "https://github.com/zkishere/telecrate/blob/master/src/gc.rs"
click node_doctor "https://github.com/zkishere/telecrate/blob/master/src/doctor.rs"
click node_recovery "https://github.com/zkishere/telecrate/blob/master/src/recovery.rs"

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_config,node_s3client toneBlue
class node_app,node_sigv4,node_s3,node_policy,node_cors,node_crypto,node_multipart toneAmber
class node_spool,node_db,node_worker,node_telegram_transport,node_telegram toneMint
class node_admin,node_dashboard,node_gc,node_doctor,node_recovery toneRose
class node_operator toneIndigo
```

## Components

### Daemon runtime

- [Daemon entry](https://github.com/zkishere/telecrate/blob/master/src/main.rs): `src/main.rs`
- [Configuration](https://github.com/zkishere/telecrate/blob/master/src/config.rs): `src/config.rs`

### S3 gateway

- [HTTP router](https://github.com/zkishere/telecrate/blob/master/src/app.rs): `src/app.rs`
- [SigV4 auth](https://github.com/zkishere/telecrate/blob/master/src/sigv4.rs): `src/sigv4.rs`
- [S3 operations](https://github.com/zkishere/telecrate/blob/master/src/s3.rs): `src/s3.rs`
- [Bucket policies](https://github.com/zkishere/telecrate/blob/master/src/policy.rs): `src/policy.rs`
- [CORS rules](https://github.com/zkishere/telecrate/blob/master/src/cors.rs): `src/cors.rs`
- [Object encryption](https://github.com/zkishere/telecrate/blob/master/src/crypto.rs): `src/crypto.rs`
- [Multipart and versions](https://github.com/zkishere/telecrate/blob/master/src/app.rs): `src/app.rs`

### Durable storage

- [Local spool](https://github.com/zkishere/telecrate/blob/master/src/spool.rs): `src/spool.rs`
- [Metadata and jobs](https://github.com/zkishere/telecrate/blob/master/src/db/mod.rs): `src/db/mod.rs`
- [Upload workers](https://github.com/zkishere/telecrate/blob/master/src/worker.rs): `src/worker.rs`
- [Telegram transport](https://github.com/zkishere/telecrate/blob/master/src/telegram.rs): `src/telegram.rs`

### Administration

- [Admin API](https://github.com/zkishere/telecrate/blob/master/src/admin.rs): `src/admin.rs`
- [Web dashboard](https://github.com/zkishere/telecrate/blob/master/src/dashboard/app.js): `src/dashboard/app.js`
- [Garbage collection](https://github.com/zkishere/telecrate/blob/master/src/gc.rs): `src/gc.rs`
- [Health and repair](https://github.com/zkishere/telecrate/blob/master/src/doctor.rs): `src/doctor.rs`
- [Recovery tools](https://github.com/zkishere/telecrate/blob/master/src/recovery.rs): `src/recovery.rs`

### Other components

- **S3 clients**
- **Admin operator**
- **Telegram Bot API**

## Connections

- Daemon entry → Configuration: loads settings
- Daemon entry → Metadata and jobs: opens index
- Daemon entry → HTTP router: serves routes
- Daemon entry → Upload workers: starts workers
- S3 clients → HTTP router: sends S3 requests
- HTTP router → SigV4 auth: authenticates requests
- HTTP router → S3 operations: dispatches S3 actions
- HTTP router → Metadata and jobs: reads and writes
- HTTP router → Local spool: stores chunks
- HTTP router → Object encryption: encrypts content
- HTTP router → Bucket policies: checks access policy
- HTTP router → CORS rules: checks CORS
- HTTP router → Multipart and versions: handles multipart/versioning
- Upload workers → Metadata and jobs: claims and commits jobs
- Upload workers → Local spool: reads chunks
- Upload workers → Telegram transport: uploads chunks
- Telegram transport → Telegram Bot API: calls Bot API
- HTTP router → Telegram transport: deletes remote chunks
- Admin operator → Web dashboard: uses dashboard
- Web dashboard → HTTP router: calls admin routes
- HTTP router → Admin API: dispatches admin routes
- Admin API → Metadata and jobs: queries and updates
- Admin API → Garbage collection: runs cleanup
- Admin API → Health and repair: checks health
- Metadata and jobs → Recovery tools: supports recovery