Project Architecture & Developer Setup

This document describes the architectural layout, internal protocols, security model, and developer setup for the Nextcloud Upload Tool.

1. Workspace Layout

The repository is organized as a Cargo workspace with three primary crates:

nextcloud-upload-tool/
├── nextcloud_client/         # Shared Rust core library
│   ├── src/
│   │   ├── auth.rs           # Nextcloud Login Flow v2 client & polling
│   │   ├── client.rs         # NextcloudClient WebDAV client & status checks
│   │   ├── config.rs         # ClientConfig and URL normalization
│   │   ├── credentials.rs    # CredentialStore (OS Keychain + accounts.json)
│   │   ├── download.rs       # Direct-download URL generator
│   │   ├── progress.rs       # Async ProgressStream & progress callbacks
│   │   └── sharing.rs        # OCS Sharing API (public share link creation)
├── cli/                      # CLI binary (`nut`)
│   └── src/
│       └── main.rs           # Clap CLI parser, upload handlers, terminal output
├── gui/                      # Desktop application (Tauri v2 + React)
│   ├── src/                  # React + TypeScript frontend
│   │   ├── App.tsx           # UI tabs, drag-and-drop, state management
│   │   └── App.css           # Styling and responsive layout
│   └── src-tauri/            # Tauri Rust backend
│       ├── src/commands.rs   # IPC command handlers forwarding to nextcloud_client
│       └── tauri.conf.json   # Multi-platform bundle configuration
└── docs/                     # Documentation & user guides

2. Shared Core Architecture (`nextcloud_client`)

Both the CLI and GUI frontends share the nextcloud_client crate to ensure consistent behavior:

WebDAV Upload Pipeline:
- Implements HTTP PUT requests against Nextcloud's WebDAV endpoint (/remote.php/dav/files/<user>/<path>).
- Employs streaming request bodies wrapped in a custom ProgressStream to capture transferred byte counts in real time without buffering large files in RAM.
- Automatically handles intermediate remote directory resolution.
OCS Sharing API:
- Interacts with /ocs/v2.php/apps/files_sharing/api/v1/shares using OCS headers (OCS-APIRequest: true).
- Creates public read-only shares (shareType=3, permissions=1) with optional password protection.
- Generates canonical public share links (/index.php/s/<token>) and direct download links (/index.php/s/<token>/download).
Unified Credential Storage:
- Keyring Service: Keyring service identifier me.majinnaibu.nut.
- Account Metadata: Stored in ~/.config/nut/accounts.json containing account IDs, server URLs, usernames, labels, and default account flags.
- Secrets: App passwords and tokens are stored in the OS native keychain (Apple Keychain on macOS, Windows Credential Manager on Windows, and Secret Service on Linux).

3. GUI Architecture & IPC Bridge

The GUI is built with Tauri v2 using a lightweight React frontend:

Tauri Commands: Defined in gui/src-tauri/src/commands.rs exposing async Rust functions (upload_file, get_accounts, login_v2_start, login_v2_poll, set_default_account, etc.) to TypeScript.
Event Streaming: As WebDAV uploads progress, the Rust backend emits upload-progress events to the Tauri webview containing file_id, bytes_transferred, total_bytes, and percent.
Drag-and-Drop Integration: The native OS drag-and-drop listener intercepts dropped files and invokes get_file_info to populate the upload queue.

4. Developer Setup & Testing

Running Tests

# Run all unit and integration tests across the workspace
cargo test --workspace

# Run CLI tests only
cargo test -p nut

# Run core library tests only
cargo test -p nextcloud_client

Running GUI in Development Mode

# In terminal 1: start Vite dev server
cd gui
npm install
npm run dev

# In terminal 2: run Tauri dev desktop app
cargo run -p gui
# Or use Tauri CLI
npm run tauri dev

4.1 KiB Raw Blame History