TDrive

Distributed personal cloud storage powered by Telegram file transport, Supabase metadata, and a React web interface.

Project Overview

TDrive is a full-stack file storage platform that chunks large files, streams chunk uploads through Telegram, and tracks file metadata in Supabase. The application provides a modern dashboard for upload, search, starring, trash/restore, and download workflows, while offloading edge-sensitive operations to dedicated Cloudflare Workers.

Why this architecture?

• 🚀 Large files are split into chunks for resilient, incremental uploads.
• 🔐 User-level access is enforced via Supabase Auth tokens validated by the backend.
• 🌍 Cloudflare Workers handle edge upload/download tasks close to users.
• 🧩 Frontend, backend, and edge runtimes are cleanly separated for independent scaling.

Repository Structure

TDrive/
|- frontend/      # React + Vite client application (UI, auth session, upload orchestration)
|- backend/       # Express API (auth guard, file metadata lifecycle, business rules)
|- cloudflare/
|  - tdrive-uploader/   # Worker: receives chunks, forwards to Telegram, writes chunk metadata
|  - tdrive-worker/     # Worker: fetches Telegram file binaries for downloads
|- README.md

Directory	Responsibility	Key Runtime
frontend	User interface, Supabase session handling, chunk upload coordination	Browser (React + Vite)
backend	Authenticated API, metadata CRUD, file lifecycle, search, download link assembly	Node.js + Express
cloudflare	Edge upload and download workers for Telegram/Supabase integration	Cloudflare Workers

Tech Stack

Frontend

• React 19
• Vite 7
• React Router
• Axios
• Supabase JS client
• Tailwind CSS 4 + Radix UI primitives
• Vitest + Testing Library

Backend

• Node.js (ES modules)
• Express 5
• Grammy (Telegram Bot API)
• Supabase JS client
• Express Rate Limit + CORS + dotenv

Cloudflare

• Cloudflare Workers (Wrangler)
• Worker A: upload proxy + chunk metadata persistence
• Worker B: Telegram file stream proxy for downloads
• Vitest for Worker tests

Getting Started (Local Development)

1) Prerequisites

• Node.js 18+
• npm 9+
• A Supabase project with tables from backend/database/schema.sql
• Telegram bot token and chat ID
• Cloudflare account for Worker deployment/testing

2) Clone the repository

git clone https://github.com/your-org/tdrive.git
cd tdrive

3) Frontend setup (frontend)

Install dependencies:

cd frontend
npm install

Create environment template and local env file:

# macOS/Linux
cp .env.example .env

# Windows (PowerShell)
Copy-Item .env.example .env

Suggested frontend .env.example:

VITE_API_URL=http://localhost:8080
VITE_UPLOAD_WORKER_URL=http://127.0.0.1:8787
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

Run frontend dev server:

npm run dev

4) Backend setup (backend)

Install dependencies:

cd ../backend
npm install

Create environment template and local env file:

# macOS/Linux
cp .env.example .env

# Windows (PowerShell)
Copy-Item .env.example .env

Suggested backend .env.example:

PORT=8080
BOT_TOKEN=your_telegram_bot_token
CHAT_ID=your_telegram_chat_id
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
CLOUDFLARE_URL=http://127.0.0.1:8788

Run backend API:

node index.js

5) Cloudflare Workers setup (cloudflare)

Uploader worker:

cd ../cloudflare/tdrive-uploader
npm install
npm run dev

Set worker secrets/vars used at runtime:

• BOT_TOKEN
• TELEGRAM_CHAT_ID
• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY

Download worker:

cd ../tdrive-worker
npm install
npm run dev

Set worker secret:

• BOT_TOKEN

6) Optional validation commands

# frontend tests
cd ../../frontend
npm run test:ci

# worker tests
cd ../cloudflare/tdrive-uploader && npm test
cd ../tdrive-worker && npm test

Deployment

TDrive is designed to deploy each layer independently:

• Frontend deploys as a static React build (for example on Cloudflare Pages, Vercel, or Netlify).
• Backend deploys as a Node.js service (for example Docker/container host, VM, or PaaS).
• Cloudflare Workers deploy with Wrangler and provide the edge bridge to Telegram and Supabase.

Runtime integration flow

1. Frontend sends upload metadata to backend.
2. Frontend streams chunks to tdrive-uploader Worker.
3. Uploader Worker sends chunks to Telegram and records chunk references in Supabase.
4. Backend finalizes upload and exposes file metadata APIs.
5. On download, backend resolves Telegram file paths and returns Cloudflare download URLs.
6. tdrive-worker fetches chunk binaries from Telegram and streams them back.

Contributing

Contributions are welcome and appreciated.

1. Fork the repository.
2. Create a feature branch.
3. Run tests before opening a pull request.
4. Open a PR with a clear description, rationale, and screenshots/logs where relevant.

Built for practical, distributed file handling across web, API, and edge runtimes.