☁️ Cloudgram

Cloudgram is a high-performance, 100% native macOS application that turns your Telegram accounts into a unified, distributed cluster of unlimited cloud storage with deep operating system integration.

The app allows you to mount your storage as a virtual network drive, providing instant read/write access to files and media streams directly through the native macOS Finder, without requiring you to pre-download files to your local machine.

The UI is built entirely in SwiftUI for macOS 26 (Tahoe) — no Electron, no webview. It talks to a Rust storage engine (MTProto client, local metadata index, WebDAV bridge) through a compiled uniffi-rs FFI bridge, so the app is a real, fast, native Mac citizen: NavigationSplitView navigation, Liquid Glass materials, MenuBarExtra, and standard system Light/Dark appearance.

---

⚙️ How It Works

The system is built on the principles of local metadata indexing and on-demand data streaming, all implemented in the Rust core and exposed to the Swift UI over FFI:

1. Intelligent Chunking

When uploading a file to the cloud, the app automatically splits it into optimized segments (up to 1.9 GB for regular accounts, and up to 3.9 GB for Telegram Premium). This bypasses Telegram's message size limit and ensures robust transfer of files of any size.

2. Local Meta-Index (SQLite)

Your entire directory structure, folders, and links between files and Telegram messages are cached locally in a SQLite database. Finding, sorting, and browsing your files is instantaneous since it requires no constant requests to the Telegram API.

3. Virtual Drive & Streaming (WebDAV Bridge)

An embedded WebDAV server emulates a network file system. When you play a video or open a document in Finder:

• The OS sends standard HTTP Range requests to the local bridge.
• The bridge maps the requested byte offsets to specific Telegram messages and chunks.
• The MTProto client requests the precise range directly from Telegram servers.
• Data streams on-the-fly, allowing you to play 4K video or skip around media instantly without downloading the whole file.

4. Swift ⇄ Rust Bridge

The Rust engine is compiled as a cdylib, and uniffi-rs generates the Swift bindings against it (see Packages/CloudgramCore/). SwiftUI views never talk to Rust directly — they go through @Observable view models that call into a single shared CloudgramCore FFI object and receive typed CloudgramEvents (upload/download progress, mirror status, task updates) pushed back asynchronously from Rust.

---

🌟 Key Features

• 🖥️ Fully Native SwiftUI App: NavigationSplitView shell, Liquid Glass bento panels, and standard macOS system appearance — built for macOS 26 Tahoe, not a wrapped web app.
• 🚀 Multi-account Cluster: Merge multiple Telegram accounts into a single storage array. Each account acts as an independent storage node, managed from a dedicated Account Manager.
• 📁 File Browser: Miller-column and grid views, multi-select, drag & drop, live upload/download progress, global search with reveal-in-place, and an Inspector with file details and version history.
• 📤 WebDAV R/W Integration: Mount the cloud as a local network drive with full read and write capabilities, allowing you to drag-and-drop files directly in Finder to upload them.
• 📡 On-Demand Streaming: Play media, open documents, and view images without downloading them to your local disk first.
• 🔄 Folder Mirrors: Watch local folders and keep them synced to the cloud, with per-rule status (syncing / synced / error) and a native Add/Edit sheet.
• 📝 Cloud Notes: Two-pane text editor with file-attachment support, storing notes directly in Telegram Saved Messages.
• 🖥️ Menu Bar & Autostart: Lives in the menu bar via MenuBarExtra, supports close-to-tray, and registers for launch-at-login through SMAppService — no LaunchAgents plist hacking.
• ⚙️ Native Settings: A dedicated Settings{} scene with tabs for accounts, local cache, sync engine, OS integration, and maintenance.

---

🛠️ Tech Stack

Swift (Native macOS Frontend)

• Swift 6.2 with strict concurrency, targeting macOS 26 Tahoe.
• SwiftUI: NavigationSplitView, @Observable view models, .inspector(), Settings{} and MenuBarExtra scenes.
• XcodeGen: The .xcodeproj is generated from project.yml — don't hand-edit the project file.

Rust (Storage Engine / Core)

• cloudgram-core: A pure business-logic crate (session management, cluster orchestration, metadata cache, WebDAV, OS integration) with no UI-framework dependency.
• uniffi-rs: Generates the Swift bindings and the CloudgramCoreFFI.xcframework binary target consumed by Packages/CloudgramCore/.
• Grammers: High-performance asynchronous MTProto client for low-level interaction with Telegram servers.
• SQLx + SQLite: Secure and reliable local metadata storage with support for transactions and database migrations.
• Axum: Lightweight web framework implementing the local WebDAV server.

Legacy reference implementation

The original Tauri v2 + React 18 + TypeScript app (src/, src-tauri/) is kept in the repository as a working reference during the native migration. It shares the same Rust core crate but talks to it as an in-process Tauri command handler instead of over FFI. It is not the primary target for new feature work.

---

🚀 Installation & Setup

System Requirements

• macOS 26 Tahoe or later, with Xcode 26+ installed.
• Rust (rustc/cargo) with both aarch64-apple-darwin and x86_64-apple-darwin targets installed via rustup.
• XcodeGen: brew install xcodegen.

Step-by-Step Guide

1. Clone the repository:

   git clone https://github.com/prewue/Cloudgram.git
   cd Cloudgram

2. Build the Rust core and generate the Swift FFI bindings:

   cargo build -p cloudgram-core --release --target aarch64-apple-darwin
   cargo build -p cloudgram-core --release --target x86_64-apple-darwin
   
   lipo -create \
     target/aarch64-apple-darwin/release/libcloudgram_core.dylib \
     target/x86_64-apple-darwin/release/libcloudgram_core.dylib \
     -output /tmp/libcloudgram_core.dylib
   
   cargo run -p uniffi-bindgen-swift -- \
     target/aarch64-apple-darwin/release/libcloudgram_core.dylib /tmp/bindgen-out \
     --swift-sources --headers --modulemap
   
   cp /tmp/bindgen-out/cloudgram_core.swift Packages/CloudgramCore/Sources/CloudgramCore/
   xcodebuild -create-xcframework \
     -library /tmp/libcloudgram_core.dylib -headers /tmp/bindgen-out \
     -output Packages/CloudgramCore/Frameworks/CloudgramCoreFFI.xcframework

   (The .xcframework is a rebuildable binary artifact and is gitignored — this step is required once before the first build.)

3. Generate and open the Xcode project:

   xcodegen generate
   open Cloudgram.xcodeproj

   Build and run the Cloudgram scheme (⌘R).

4. Command-line build (equivalent to the above, without opening Xcode):

   xcodebuild -project Cloudgram.xcodeproj -scheme Cloudgram -configuration Debug build

---

🔒 Security & Privacy

Privacy was a core design priority:

• No Middlemen: All API requests and file chunks go directly between your device and Telegram's servers. No third-party trackers or telemetry.
• Local Session Storage: Auth sessions and the SQLite index database are stored entirely on your local machine at ~/Library/Application Support/Cloudgram/, secured by OS file permissions.
• Session Encryption: Authentication credentials and MTProto keys are fully protected by Telegram's native cryptographic protocols.

---

📄 License

This project is licensed under the PolyForm Shield License 1.0.0.

Under this license, you are free to use, copy, modify, and distribute the software for any purpose except for creating a product or service that competes with Cloudgram or any other product/service provided by the copyright holder.

For the full terms, please see the LICENSE file.