# awsl-project/awsl-telegram-storage architecture

> Architecture diagram of the GitHub repository awsl-project/awsl-telegram-storage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/awsl-project/awsl-telegram-storage
- Repository: https://github.com/awsl-project/awsl-telegram-storage

## Overview

AWSL Telegram Storage is a Cloudflare Workers API for storing files through Telegram, with uploads returning Telegram file IDs and download or video-stream endpoints retrieving them. The main workflow is client → routed endpoint → Telegram Bot API → client; uploads may use permanent or temporary upload-scoped JWT authentication. The graph also preserves media-group uploads, token generation, OpenAPI/CORS, and range-aware chunk streaming. Evidence for route wiring and upload helpers is excerpted; download and stream rely on documented behavior and shown endpoint code, without claiming a shared Telegram helper.

Main entry points: [`src/index.ts`](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/index.ts) (HTTP router), [`src/api_upload.ts`](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_upload.ts) (Single upload), [`src/api_upload_group.ts`](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_upload_group.ts) (Media-group upload), [`src/api_stream.ts`](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_stream.ts) (Video streaming)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surface"]
  node_router["HTTP router<br/>[index.ts]"]
  node_api_docs["OpenAPI docs<br/>[index.ts]"]
  node_cors["CORS handling<br/>[index.ts]"]
end

subgraph group_upload["Upload and auth"]
  node_single_upload["Single upload<br/>[api_upload.ts]"]
  node_group_upload["Media-group upload"]
  node_token_generation["JWT generation"]
  node_auth_validation["Token validation<br/>[auth.ts]"]
  node_telegram_helpers["Upload helpers<br/>[telegram.ts]"]
end

subgraph group_retrieve["File retrieval"]
  node_file_download["File download<br/>[api_download.ts]"]
  node_video_stream["Video streaming<br/>[api_stream.ts]"]
end

subgraph group_telegram["Telegram service"]
  node_telegram_bot{{"Telegram Bot API"}}
  node_telegram_storage[("Telegram file storage")]
end

node_client(("Client"))

node_client -->|"sends requests"| node_router
node_router -->|"routes uploads"| node_single_upload
node_router -->|"routes groups"| node_group_upload
node_router -->|"routes token requests"| node_token_generation
node_router -->|"routes downloads"| node_file_download
node_router -->|"routes streams"| node_video_stream
node_router -->|"serves docs"| node_api_docs
node_router -->|"applies CORS"| node_cors
node_single_upload -->|"validates token"| node_auth_validation
node_group_upload -->|"validates token"| node_auth_validation
node_single_upload -->|"uses upload helpers"| node_telegram_helpers
node_group_upload -->|"uses upload helpers"| node_telegram_helpers
node_single_upload -->|"sends file"| node_telegram_bot
node_group_upload -->|"sends media group"| node_telegram_bot
node_token_generation -.->|"includes chat ID"| node_telegram_bot
node_telegram_bot -->|"stores files"| node_telegram_storage
node_telegram_bot -->|"returns file data"| node_file_download
node_video_stream -->|"fetches chunks"| node_telegram_bot
node_file_download -->|"returns file stream"| node_client
node_video_stream -->|"returns ranged stream"| node_client

click node_router "https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/index.ts"
click node_api_docs "https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/index.ts"
click node_cors "https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/index.ts"
click node_single_upload "https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_upload.ts"
click node_group_upload "https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_upload_group.ts"
click node_token_generation "https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_token_generate.ts"
click node_auth_validation "https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/auth.ts"
click node_telegram_helpers "https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/telegram.ts"
click node_file_download "https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_download.ts"
click node_video_stream "https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_stream.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_router,node_api_docs,node_cors,node_client toneBlue
class node_single_upload,node_group_upload,node_token_generation,node_auth_validation,node_telegram_helpers toneAmber
class node_file_download,node_video_stream toneMint
class node_telegram_bot,node_telegram_storage toneRose
```

## Components

### API surface

- [HTTP router](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/index.ts): `src/index.ts`
- [OpenAPI docs](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/index.ts): `src/index.ts`
- [CORS handling](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/index.ts): `src/index.ts`

### Upload and auth

- [Single upload](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_upload.ts): `src/api_upload.ts`
- [Media-group upload](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_upload_group.ts): `src/api_upload_group.ts`
- [JWT generation](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_token_generate.ts): `src/api_token_generate.ts`
- [Token validation](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/auth.ts): `src/auth.ts`
- [Upload helpers](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/telegram.ts): `src/telegram.ts`

### File retrieval

- [File download](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_download.ts): `src/api_download.ts`
- [Video streaming](https://github.com/awsl-project/awsl-telegram-storage/blob/main/src/api_stream.ts): `src/api_stream.ts`

### Telegram service

- **Telegram Bot API**
- **Telegram file storage**

### Other components

- **Client**

## Connections

- Client → HTTP router: sends requests (evidence: `README.md`)
- HTTP router → Single upload: routes uploads (evidence: `src/index.ts`)
- HTTP router → Media-group upload: routes groups (evidence: `src/index.ts`)
- HTTP router → JWT generation: routes token requests (evidence: `src/index.ts`)
- HTTP router → File download: routes downloads (evidence: `src/index.ts`)
- HTTP router → Video streaming: routes streams (evidence: `src/index.ts`)
- HTTP router → OpenAPI docs: serves docs (evidence: `src/index.ts`)
- HTTP router → CORS handling: applies CORS (evidence: `src/index.ts`)
- Single upload → Token validation: validates token (evidence: `src/api_upload.ts`)
- Media-group upload → Token validation: validates token (evidence: `src/api_upload_group.ts`)
- Single upload → Upload helpers: uses upload helpers (evidence: `src/api_upload.ts`)
- Media-group upload → Upload helpers: uses upload helpers (evidence: `src/api_upload_group.ts`)
- Single upload → Telegram Bot API: sends file (evidence: `src/api_upload.ts`)
- Media-group upload → Telegram Bot API: sends media group (evidence: `src/api_upload_group.ts`)
- JWT generation → Telegram Bot API: includes chat ID
- Telegram Bot API → Telegram file storage: stores files (evidence: `README.md`)
- Telegram Bot API → File download: returns file data (evidence: `src/api_download.ts`)
- Video streaming → Telegram Bot API: fetches chunks (evidence: `src/api_stream.ts`)
- File download → Client: returns file stream (evidence: `README.md`)
- Video streaming → Client: returns ranged stream (evidence: `README.md`)