QuixiCloud Desktop: Architecture & Workflow

When the user launches the QuixiCloud Desktop app (or when it launches via system Auto-Start), the following sequence occurs:

Background Initialization (Rust/Tauri)

• Configuration Load: The ConfigManager reads config.json from the disk to load user preferences (Auto-Free Space, Language, Max Speeds, etc.).
• Database Initialization: The local SQLite inventory database is initialized. This database tracks file metadata, sync state, and unresolved conflicts.
• Telemetry Worker: A dedicated background thread starts, batching internal diagnostic metrics and periodically sending them to the telemetry server (independent of standard application logging).
• System Tray & Window: The System Tray icon is registered. Depending on the fast_popup_launch setting, the main window is either shown immediately or held in memory (hidden) for instantaneous access when the tray icon is clicked.

Foreground Initialization (React/TypeScript)

• The Vite-powered React UI mounts.
• It fetches the current state from the Rust backend via Tauri IPC (invoke).
• If no credentials exist, the user is presented with the Login screen.

• Login: The user enters their QuixiCloud URL and credentials.
• API Verification: The backend (crates/quixicloud-api) authenticates with the server.
• Token Storage: An Access Token and a Refresh Token are securely stored in memory.
• Automatic Refresh: The application employs a proactive credential manager. If any API call or background connection (like SSE) receives a 401 Login Required or 40089 Session Expired error, the active request pauses, the Refresh Token is used to fetch new credentials, and the original request resumes transparently without user intervention.

To sync files, the user maps a remote QuixiCloud directory to a local Windows folder.

• Mount Creation: The backend initializes a Mount instance (crates/quixicloud-sync/src/drive/mounts.rs).
• Windows Cloud Files API (cfapi): The app hooks into the native Windows file system. The mapped folder becomes a "Virtual Drive".
• Placeholder Generation: The app performs an initial sync, downloading metadata only. It creates 0-byte "placeholders" on the local disk. These look and feel like regular files in Windows Explorer, but take up no space.

Once a drive is mounted, the sync engine operates continuously in the background using asynchronous Tokio tasks.

A. Remote-to-Local Sync (Server-Sent Events)

• SSE Connection: The app opens a long-lived Server-Sent Events (SSE) connection (remote_events.rs) to the QuixiCloud server.
• Real-time Updates: When a file is uploaded, modified, or deleted on the server, QuixiCloud pushes an event down the SSE pipeline.
• Local Application: The desktop app receives the event and immediately reflects the change locally.

B. Local-to-Remote Sync (File System Watcher)

• Hydration (Downloading): If the user double-clicks a 0-byte placeholder, Windows traps the request and asks QuixiCloud for the file data. The backend downloader fetches the file chunks from QuixiCloud, streams them to the disk, and hands the hydrated file to the requesting application.
• Uploads: If the user drops a new file into the local folder, the file system watcher detects the change, places it in the Upload Queue, and the uploader splits the file into chunks (uploader/chunk.rs) to upload to QuixiCloud.
• Concurrency: Large files use concurrent chunk uploading to maximize bandwidth efficiency without overwhelming the server.

C. Storage Management (Auto-Free Space)

If the user enabled Auto-Free Space:

• Immediately after a successful local-to-remote upload, the sync engine tells the Windows Cloud Files API to "dehydrate" the file.
• The actual file content is deleted from the local drive, returning it to a 0-byte placeholder.

• Background Tokio tasks receive cancellation signals.
• The SSE connections are gracefully closed.
• Active uploads/downloads are suspended and their state is saved to the local SQLite DB to be resumed on the next launch.
• The Tauri process terminates.