# CLAUDE.md — Wraith Desktop v2

## Project Overview

Wraith is a native desktop SSH/SFTP/RDP client — a MobaXTerm replacement. Rust backend (Tauri v2) + Vue 3 frontend (WebView2). Single binary, no Docker, no sidecar processes.

**Name:** Wraith — exists everywhere, all at once.

## Tech Stack

- **Runtime:** Tauri v2 (stable)
- **Backend:** Rust with `russh` (SSH/SFTP), `ironrdp` (RDP), `rusqlite` (SQLite), `aes-gcm` + `argon2` (vault), `dashmap` (concurrent session registry)
- **Frontend:** Vue 3 (Composition API, `<script setup>`), TypeScript, Vite, Pinia, Tailwind CSS v4, xterm.js 6, CodeMirror 6
- **Distribution:** Tauri bundler (NSIS installer), auto-updater with code signing

## Project Structure

```
src-tauri/                  # Rust backend
  src/
    main.rs                 # Entry point
    lib.rs                  # App state, module declarations, Tauri setup
    ssh/                    # SSH service (russh), host keys (TOFU), CWD tracker
    sftp/                   # SFTP operations (russh-sftp)
    rdp/                    # RDP service (ironrdp), scancode mapping
    vault/                  # Encryption (Argon2id + AES-256-GCM)
    db/                     # SQLite (rusqlite), migrations
    connections/            # Connection CRUD, groups, search
    credentials/            # Credential CRUD, encrypted storage
    settings/               # Key-value settings
    theme/                  # Terminal themes (7 built-in)
    session/                # Session manager (DashMap)
    workspace/              # Workspace snapshots, crash recovery
    commands/               # Tauri command wrappers

src/                        # Vue 3 frontend
  layouts/                  # MainLayout, UnlockLayout
  components/               # UI components
  composables/              # useTerminal, useSftp, useRdp, useTransfers
  stores/                   # Pinia stores (app, session, connection)
  assets/                   # CSS, images
```

## Commands

```bash
npm install                 # Install frontend deps
npm run dev                 # Vite dev server only
cargo tauri dev             # Full app (Rust + frontend)
cargo tauri build           # Production build
cd src-tauri && cargo test  # Run Rust tests (52 tests)
cd src-tauri && cargo build # Build Rust only
```

## Architecture

- **Sessions use DashMap** — lock-free concurrent access, no deadlocks during tab detach
- **Drop trait for cleanup** — SSH/SFTP/RDP connections close automatically when sessions drop
- **CWD following via exec channel** — polls `pwd` on a separate SSH channel every 2 seconds. Never touches the terminal data stream. This avoids ANSI escape sequence corruption.
- **RDP runs in dedicated thread** — ironrdp's trait objects aren't Send, so each RDP session gets its own tokio runtime in a std::thread
- **xterm.js font handling** — `document.fonts.ready.then(() => fitAddon.fit())` prevents cell width miscalculation

## Key Design Decisions

1. **No terminal stream processing.** The Go version's CWD tracker parsed OSC 7 from the terminal output and corrupted ANSI sequences. Never again.
2. **Tauri v2 over Wails v3.** Wails v3 is alpha with breaking changes. Tauri v2 is stable with built-in multi-window, auto-updater, and active community.
3. **ironrdp over FreeRDP FFI.** Pure Rust, no DLL dependency, memory safe. FreeRDP is the fallback discussion if ironrdp can't hit performance targets.
4. **Fresh vault, no Go migration.** 6 connections — faster to re-enter than engineer format compatibility.

## Lineage

This is a ground-up Rust rewrite of `wraith` (Go/Wails v3). The Go version is archived at `wraith-go-legacy`. The original design spec is at `docs/superpowers/specs/2026-03-17-wraith-desktop-design.md` in the Go repo.