OrbitDrive 🌐

A powerful cloud storage web application that uses Telegram as a backend storage solution via the TDS2 library. Upload, organize, and manage your files through a beautiful web interface while storing them securely in your Telegram group.

✨ Features

📁 File & Folder Management

• 🚀 Web-based File Browser - Upload, download, and delete files through a modern UI
• 📂 Folder Upload - Upload entire folders with automatic structure creation
• 📁 Folder Organization - Create folders and organize files hierarchically
• 🔄 Move Files - Move single or multiple files between folders
• ✅ Batch Operations - Select multiple files and move/delete them at once
• 🗑️ Context Menu - Right-click on files/folders for quick actions

📤 Upload Features

• 📦 Multiple File Upload - Upload multiple files simultaneously with progress tracking
• 📂 Folder Structure Preservation - Upload folders and maintain their complete structure
• 🎯 Drag & Drop - Easy file uploads by dragging files into the upload area
• 📊 Per-file Progress - Individual progress bars for each uploading file
• 💾 Smart Storage - Files temporarily stored on server, then uploaded to Telegram and auto-cleaned

🔍 Search & View

• 🔍 Search Functionality - Quickly find files by name across all folders
• 📋 File Details Modal - View comprehensive file metadata (size, date, type)
• 🎨 Modern UI - Beautiful, responsive design with gradient backgrounds

🛡️ Safety & Limits

• ⚡ Rate Limiting - Built-in 10 GB/hour upload limit to prevent Telegram bans
• 📊 Statistics Dashboard - Real-time tracking of storage usage and rate limit consumption
• ⚠️ Rate Limit Warning - Visual indicator when approaching upload limits
• 🔒 Safe Deletion - Confirmation prompts before deleting files/folders

📋 Prerequisites

• Python 3.8 or higher
• Telegram API credentials (API ID and API Hash)
• A Telegram group for file storage

🔧 Installation

1. Clone the repository:

git clone <repository-url>
cd OrbitDrive

2. Install dependencies:

pip install -r requirements.txt

3. Configure your Telegram credentials:

Edit config.py and set your credentials:

API_ID = 'YOUR_API_ID'
API_HASH = 'YOUR_API_HASH'
GROUP_CHAT_ID = 'YOUR_GROUP_CHAT_ID'

To get these credentials:

• Visit https://my.telegram.org
• Login with your phone number
• Go to "API development tools"
• Create an application to get your API_ID and API_HASH
• Create a Telegram group and get its chat ID (use a bot like @userinfobot)

🚀 Running the Application

1. Start the server:

python backend.py

2. Access the web interface: Open your browser and navigate to:

http://localhost:8000

3. First run: On the first run, you'll need to authenticate with Telegram. Check the terminal for authentication prompts.

📖 Usage

Uploading Files

Single/Multiple Files:

1. Click the "⬆️ Upload File" button
2. Select one or multiple files
3. Each file shows individual progress
4. Files appear in your current folder when complete

Upload Entire Folders:

1. Click the "📂 Upload Folder" button
2. Select a folder from your computer
3. The app automatically:
   • Creates the folder structure
   • Uploads all files to correct locations
   • Shows progress for each file with full path

Drag & Drop:

• Simply drag files into the upload area
• Multiple files supported

Creating Folders

1. Click the "📁 New Folder" button
2. Enter a folder name
3. Click "Create"
4. The new folder appears in your current location

Moving Files

Move Single File:

1. Right-click on a file
2. Select "Move" from the context menu
3. Choose destination folder from the tree
4. Click "Move"

Move Multiple Files:

1. Check the checkbox on each file you want to move
2. A toolbar appears at the bottom showing selection count
3. Click "Move" button in the toolbar
4. Select destination folder
5. Click "Move" to confirm

Downloading Files

1. Click on a file to view details

2. Click "⬇️ Download" button in the modal

   OR

3. Right-click on a file

4. Select "Download" from the context menu

Deleting Files/Folders

Single Item:

1. Right-click on a file or folder
2. Select "Delete" from the context menu
3. Confirm the deletion

Multiple Files:

1. Select files using checkboxes
2. Click "Delete" button in the toolbar
3. Confirm deletion

Note: Deleting a folder removes all files and subfolders inside it.

Searching Files

1. Type in the search box at the top
2. Results appear automatically as you type
3. Search works across all folders
4. Clear search to return to folder view

Viewing File Details

1. Click on any file
2. A modal shows:
   • File icon based on type
   • Original filename
   • File size (formatted)
   • Upload date and time
   • Mime type
3. Download or delete from the modal

🏗️ Project Structure

OrbitDrive/
├── start.py            # Quick start script with validation
├── backend.py          # FastAPI server and API endpoints
├── config.py           # Configuration settings (EDIT THIS!)
├── database.py         # SQLite database models and operations
├── tds_service.py      # TDS2 wrapper for Telegram operations
├── tds_service.py      # TDS2 wrapper service
├── requirements.txt    # Python dependencies
├── main.py            # Test script for TDS2
├── static/
│   ├── index.html     # Frontend HTML
│   └── app.js         # Frontend JavaScript
├── uploads/           # Temporary upload directory (auto-created)
├── sessions/          # Telegram session files (auto-created)
├── orbitdrive.db      # SQLite database (auto-created)
└── tds2_files.json    # TDS2 log file (auto-created)

🔒 Security Considerations

1. Change the SECRET_KEY in config.py for production use
2. Use environment variables for sensitive credentials instead of hardcoding them
3. Enable authentication if deploying publicly
4. Use HTTPS in production
5. Set appropriate CORS origins in production

⚙️ Configuration Options

Edit config.py to customize:

• MAX_UPLOAD_SIZE_MB - Maximum file size (default: 2000 MB)
• RATE_LIMIT_GB_PER_HOUR - Upload rate limit (default: 10 GB)
• HOST - Server host (default: 0.0.0.0)
• PORT - Server port (default: 8000)
• ALLOWED_FILE_EXTENSIONS - Allowed file types

📊 Database Schema

Tables

folders

• id (PRIMARY KEY)
• name (TEXT)
• parent_id (FOREIGN KEY)
• path (TEXT UNIQUE)
• created_at (TIMESTAMP)

files

• id (PRIMARY KEY)
• filename (TEXT)
• original_filename (TEXT)
• folder_id (FOREIGN KEY)
• message_id (INTEGER) - Telegram message ID
• file_size (INTEGER)
• mime_type (TEXT)
• uploaded_at (TIMESTAMP)
• is_deleted (BOOLEAN)

upload_tracking

• id (PRIMARY KEY)
• upload_size (INTEGER)
• upload_timestamp (TIMESTAMP)

🔌 API Endpoints

Statistics

• GET /api/stats - Get overall statistics

Folders

• POST /api/folders - Create a new folder
• GET /api/folders - List folders
• GET /api/folders/{id} - Get folder details
• DELETE /api/folders/{id} - Delete folder

Files

• POST /api/files/upload - Upload a file
• GET /api/files?folder_id={id} - List files in folder
• GET /api/files/search?q={query} - Search files
• GET /api/files/{id} - Get file info
• GET /api/files/{id}/download - Download file
• DELETE /api/files/{id} - Delete file

Maintenance

• POST /api/maintenance/cleanup-tracking - Clean old upload tracking records

🐛 Troubleshooting

"Failed to initialize TDS2 client"

• Verify your API credentials are correct
• Check your internet connection
• Ensure the Telegram group exists and you have access

"Rate limit exceeded"

• Wait for the hourly rate limit to reset
• Check current usage in the dashboard
• Old upload tracking records are cleaned up automatically after 7 days

Authentication Issues

• Delete the session files in the sessions/ directory
• Restart the server and authenticate again

📝 License

This project is open source and available under the MIT License.

🤝 Contributing

Contributions, issues, and feature requests are welcome!

👨‍💻 Author

Built with ❤️ using FastAPI, TDS2, and modern web technologies.

🙏 Acknowledgments

• TDS2 - Telegram as cloud storage library
• FastAPI - Modern Python web framework
• Telegram - For providing the platform

---

⚠️ Disclaimer: This project is for educational purposes. Make sure to comply with Telegram's Terms of Service when using this application.