Desktop Email Archive Agent — Tauri wrapper per import archivi email

Desktop Archive Agent — Tauri wrapper for email & file import

Cross-platform Tauri desktop app (Mac / Windows / Linux) that provides a graphical interface for the existing Python agents that import local email archives and local files/folders into the Rainty server. Runs as a background tray icon and is configurable through a dedicated settings window.

Repository and workflow

git clone https://github.com/vinovalab/rainty-desktop.git
cd rainty-desktop
git checkout DK002

All work goes on DK002. The WP8 baseline agents (agent/ for email, file-agent/ for files) land on master; build DK002 on top of master. When complete, open a Pull Request targeting master.

Compensation and timeline

This supersedes the original (email-only) scope and compensation: scope now includes email attachments and generic file/folder push (see below).

Development and test environment

The app uses two API keys, each for its own endpoint:

Verification endpoints

• File key (rainty-lpush-...): GET https://dev.rainty.vinovalab.ai/local-push/status with header X-Api-Key — returns { "ok": true, "connection": {...} } if valid.
• Email key (rainty-imp-...): GET https://dev.rainty.vinovalab.ai/archive/status with the bearer key — endpoint to be added server-side by the coordinator. Until it ships, treat the email key as "validated on first import".

Use the DEV server exclusively during development.

Context and goal

The project already includes working Python CLI agents:

• agent/main.py — reads local email archives (PST, MBOX, OLM, Apple Mail, EML) and sends email bodies to POST /archive/batch, with extracted attachments rebounced to POST /local-push/batch.
• file-agent/ — pushes arbitrary local files/folders to POST /local-push/batch.

Both already handle API key authentication, filters, batch upload, deduplication, and resuming interrupted sessions.

This challenge consists of wrapping those agents graphically in a native desktop application, without rewriting the import logic. The app should make accessible to non-technical users what today requires the terminal.

Prerequisite: the Python agents (agent/, file-agent/ and their modules core/, readers/) are already in the repository on master (WP8 baseline). The developer may modify them if needed to adapt the output format or add features required by the Tauri integration.

Scope

In scope

• Native tray icon on Mac, Windows and Linux (Tauri 2.x)
• Tray menu with quick access to main functions
• Dedicated settings window: two API keys (Email / File), server URL, archives, folders, schedule
• Email archive management: add/remove files or folders to import (PST, MBOX, OLM, Apple Mail, EML)
• Email attachment handling: attachments extracted from the archives are sent to POST /local-push/batch with the file key
• Generic local file/folder push: wrap the file-agent/ CLI to import arbitrary files and folders to POST /local-push/batch
• Manual import from UI with real-time progress bar (email + files)
• Scheduled import (cron/at): configure a recurring time for automatic sending
• Tracking of already-imported archives/files: a completed item is not re-sent; force re-import is possible manually
• Session history with status, counts and timestamps
• Resume interrupted imports
• Dry-run ("simulate import") before sending
• Info page with app version
• Easter Egg: clicking 5 times on the version in the Info page unlocks a field to change the server URL
• Configuration persists across app restarts

Out of scope

• Email content preview inside the app
• Continuous real-time archive monitoring

Architecture

Python sidecars — bundling

The agent/main.py and file-agent/ scripts are compiled with PyInstaller into self-contained executables and included in the Tauri bundle as sidecars. The end user does not need to install Python.

The developer may modify the agents if needed. In particular, it is recommended to update their output to the JSON-per-line format ({ "event": "progress", "sent": 10, "total": 50, ... }) to simplify parsing from Rust. Example:

{ "event": "start", "total": 50, "archive": "Inbox.mbox" }
{ "event": "progress", "sent": 10, "total": 50, "duplicates": 2, "errors": 0 }
{ "event": "done", "sent": 50, "total": 50, "duplicates": 5, "errors": 1 }
{ "event": "error", "message": "Invalid API key" }

The Rust backend launches the sidecar, reads stdout line by line, deserialises the JSON, and updates the frontend via Tauri events.

Configuration

The app stores securely (system keychain on Mac, Credential Manager on Windows, Secret Service on Linux):

• Email API key (rainty-imp-...) — for email import. Obtained from the Rainty server (Connectors → Add → Local Email Archive)
• File API key (rainty-lpush-...) — for attachments and file/folder push. Obtained from the Rainty server (Connectors → Add → Local Archive / Push)
• Server URL — defaults to https://vinovalab.ai. Editable only via the Easter Egg (5 clicks on the version in the Info page)

Settings window

The settings window is the main screen of the app and contains:

• Email key field (masked, Show/Hide + "Verify" that calls GET /archive/status)
• File key field (masked, Show/Hide + "Verify" that calls GET /local-push/status)
• List of email archives to import: add via drag & drop or file picker, remove with a button
• List of files/folders to push: add via drag & drop or file picker, remove with a button
• Schedule configuration: on/off toggle + time picker (e.g. every day at 02:00)
• "Start import" button — opens the progress screen

Tray menu

● Rainty Agent
──────────────
  Open settings
  Start import now
  History
  ──────────────
  Quit

"Start import now" opens the progress screen and launches the import immediately.

Scheduled import

The app registers a job with the operating system scheduler (launchd on Mac, Task Scheduler on Windows, cron on Linux) to launch the import at the configured time. The job is active even when the window is closed, as long as the tray process is running.

Main user flow

1. The user installs the app: the tray icon appears
2. First launch: the settings window opens and asks for the two API keys
3. The user enters the keys and clicks "Verify" on each — immediate response from the server
4. The user adds email archives and/or files/folders and, optionally, configures a schedule
5. The user clicks "Start import" — the progress screen opens with a progress bar
6. The progress bar shows: current item, emails/files sent / total, duplicates, errors
7. Import complete: the session is recorded in History
8. If the same archive/file is started again, the app warns the user before proceeding
9. If a schedule is configured, the import starts automatically at the set time

Expected deliverables

• Compiled Tauri app working on macOS, Windows and Linux
• Tray icon with menu (Open settings, Start import now, History, Quit)
• Settings window: two API keys with verification, archive list, file/folder list, schedule configuration
• Email import with attachments sent to the file endpoint
• Generic file/folder push via the file-agent/ sidecar
• Progress screen with real-time progress bar
• Session history screen with date, status and counts
• Easter Egg: 5 clicks on the version → server URL field
• Scheduled import via OS scheduler
• README with build instructions, PyInstaller configuration (both sidecars) and first run guide

Acceptance criteria

• The app runs as a tray icon on all 3 platforms with no window open by default
• The tray menu contains: Open settings, Start import now, History, Quit
• The settings window is accessible from the tray menu and opens on first launch
• The settings window has two key fields (Email / File), each masked with Show/Hide
• "Verify" on the File key validates via GET /local-push/status; shows success or failure
• "Verify" on the Email key validates via GET /archive/status (once available); shows success or failure
• Both API keys are stored in the system keychain and not in plain text on disk
• "Start import now" from the tray menu opens the progress screen and launches the import
• Email bodies are sent to POST /archive/batch; extracted attachments to POST /local-push/batch
• Files/folders added for push are sent to POST /local-push/batch
• The progress bar shows in real time: current item, sent, total, duplicates, errors
• The progress bar updates on every JSON line emitted by the Python sidecars
• A completed import is recorded in History with date, status and counts
• Starting an import on an already-completed archive/file warns the user before proceeding
• An interrupted import can be resumed without re-sending already-sent items
• The dry-run ("simulate import") shows the count without sending anything
• The schedule is configurable from the settings window; the import starts automatically at the set time
• Clicking 5 times on the version in the Info page reveals the field to change the server URL
• Configuration (both API keys, archives, files, server URL if changed, schedule) persists across restarts