nex_shift/docs/ARCHITECTURE.md

224 lines
11 KiB
Markdown

# Architecture
Shift is a single locally running desktop process. There is no application
backend, account service or cloud database. Rust owns native work, durable
state and process boundaries; React owns presentation and transient interaction
state.
This document describes the current shape. Behavioural requirements live in
[`SPECIFICATION.md`](SPECIFICATION.md), security boundaries in
[`SECURITY.md`](SECURITY.md), and historical failure constraints in
[`ENGINEERING-NOTES.md`](ENGINEERING-NOTES.md).
## Process and window model
The Tauri process hosts one webview asset bundle. `src/App.tsx` selects one of
eight view kinds from the `view` query parameter:
| View | Window label | Responsibility |
| --- | --- | --- |
| `main` | `main` | File picker, drop targets, recent library, settings, first-run checks |
| `radial` | `radial` | Transparent always-on-top format/tool ring |
| `capture` | `capture` | Frozen-screen overlay and area selection |
| `recorder` | `recorder` | Recording timer and stop control |
| `editor` | `editor` | Image annotation, video player, read-only text preview, OCR |
| `result-card` | `result-*` | Post-capture actions; one window per capture |
| `share-notice` | `share-*` | Incoming-transfer consent card |
| `pin` | `pin` | Always-on-top image reference |
Closing the main, editor, radial or pin window hides it rather than exiting the
app. Tray and global-shortcut actions can bring these surfaces back. A second
instance is routed to the existing copy by `tauri-plugin-single-instance`; only
one process owns the global shortcuts and, on Windows, the shared discovery
port.
## State ownership
Rust-owned runtime state is registered as managed Tauri state:
- `AppState`: capture session, recording child, editor session, radial drag
context, native drag bridge process and capture-window restoration list.
- `ShareState`: local beacon, bounded peer table, pending consent offers,
accepted batch windows and the discovery enabled flag.
- `HistoryState`: the in-memory recent-file list, persisted to
`app_data_dir/history.json`.
- `UpdateState`: last update status and whether the last signature check
passed.
Settings are persisted as one JSON read-modify-write document at
`app_config_dir/settings.json`. Writes use a process-wide mutex and an atomic
replace (temporary file then rename). History is a convenience cache: its write
is a single replace and a corrupt or missing file falls back to an empty list.
Frontend state is not authoritative for file output, history, downloads or
editing results. A renderer can be hidden and recreated; durable state remains
in Rust or on disk.
## Module boundaries
| Module | Owns |
| --- | --- |
| `files.rs` | Extension classification, previews, conversion/tool catalogue execution, collision-safe output names, editor data commands, external process helpers |
| `pdf.rs` | PDF merge/split/rotate/text/render/compress and PDF-to-DOCX packaging |
| `office.rs` | DOCX image-page extraction, PPTX text/tables and spreadsheet parsing |
| `markdown.rs` | Bundled Markdown-to-HTML fallback |
| `capture.rs` | Screen permission checks, monitor selection, screenshot capture, crop and result handoff |
| `recording.rs` | `screencapture`, FFmpeg and `wf-recorder` backends, stop/finalization |
| `drag_bridge.rs` | Native drag detection, ring mode and radial context |
| `editor.rs` | Editor session and pinned-image window state |
| `history.rs` | Recent-file merge, capacity, pinning, persistence and events |
| `settings.rs` | Settings schema, output directories, write checks, app language |
| `share.rs` | LAN discovery, peer table, SHSF transfer protocol and consent |
| `update.rs` | Manifest fetch/parse/signature, download, integrity gate and installer handoff |
| `result_card.rs` | Post-capture card lifecycle and auto-close |
| `runtime.rs` | External component detection and installation instructions |
| `process.rs` | Spawn helper that suppresses console windows on Windows |
`pdf.rs`, `office.rs` and `markdown.rs` deliberately have no Tauri window
management. They operate on paths and values so they can be tested without a
live app handle.
## Core data flows
### File action
1. A drag, picker or recent row chooses one action and one or more source paths.
2. `RadialMenu.tsx` calls `perform_file_action` with a generated `jobId`.
3. Rust runs `files::perform_action` off the UI thread.
4. Progress may arrive as `app://file-action-progress`; completion arrives as
`app://file-action-finished` with either an `ActionOutcome` or an error code.
5. New paths are recorded in `history.json`, broadcast on `history://changed`
and announced through `app://file-result`.
6. The UI reveals results only if the auto-reveal setting is enabled.
Source files are opened read-only. Every output goes through `unique_output` or
`unique_output_in`, which append ` 2`, ` 3`, ... instead of replacing an
existing file.
### Capture and recording
1. `start_capture` checks screen-capture permission and selects the monitor
under the pointer.
2. The screen is captured to a temporary file, Shift's own windows are hidden,
and the `capture` overlay is shown with the frozen frame.
3. A crop is written through the same collision-safe naming path as any other
result. Full-screen capture skips the overlay.
4. A result card window is created; if it cannot be created, the editor opens
instead so the capture still has an action surface.
5. Recording is a separate child process. Stopping it finalizes the file,
restores hidden windows and hands the recording to the editor/card flow.
### Editor
Images are read by Rust and returned as a data URL so the canvas can export
without cross-origin taint. Annotation happens in the renderer; saving returns
the composed PNG to Rust, which decodes it, checks limits and writes a new file.
Text files are read by Rust and shown in a read-only `<pre>`. Videos are loaded
through the asset protocol and played by the webview.
The editor does not write back to the source. `Copy` and `Save As` remain
separate operations.
### OCR
Image OCR runs in the renderer through Tesseract.js/WASM. The worker, core and
English/Simplified Chinese models are local files under `public/tesseract/`.
PDF OCR is a Rust-to-renderer loop: Rust renders each PDF page into a cache
folder, the renderer recognizes page images, then Rust writes the combined text
result and the cache folder is cleaned up.
No OCR path uploads a file or downloads a model at runtime.
### LAN sharing
One long-lived UDP discovery thread sends multicast, directed broadcast,
limited broadcast and a bounded unicast sweep. Peers are kept in a table capped
at 256 entries and expire after 15 seconds without a beacon. The table emits
`share://peers` only when its visible signature changes.
Transfers use a direct TCP connection to the port advertised in the beacon:
```text
"SHSF" | 4-byte big-endian header length | JSON header | 0/1 decision | body | ack
```
The receiver writes to a temporary `.shift-part` file and renames only after the
exact declared byte count has arrived. The sender copies exactly the header's
declared size, so a source file that grows cannot bleed bytes into the ack.
Inbound offers prompt once; later files in the same accepted batch use a
two-minute trust window.
The protocol has no authentication or encryption. Consent prevents automatic
writing, not sender impersonation. See [`SECURITY.md`](SECURITY.md).
### Updates
1. The manifest URL is derived at build time from the git remote, or overridden
with `SHIFT_UPDATE_URL`.
2. The manifest is fetched, capped at 256 KiB, parsed as `schema: 1`, and each
named artifact must be a safe basename with a nonzero size and SHA256.
3. If a public key is baked in, the detached `shift-update.sig` must verify over
the manifest's exact bytes.
4. The artifact is downloaded to the temp update directory, then its exact size
and SHA256 are checked.
5. Before installing, both checks run again; a failure deletes the artifact.
6. macOS and Windows hand the installer to a detached helper only after Shift
exits. Paths are process arguments, never interpolated script text.
## Events
Events are grouped by owner and are not a replacement for durable state.
| Event | Producer | Purpose |
| --- | --- | --- |
| `app://error` | Rust | User-visible native failure |
| `app://file-action-progress` | `files.rs` | Job-specific progress |
| `app://file-action-finished` | `files.rs` | Success or error for one job |
| `app://file-result` | history/capture/share | New result is available |
| `capture://ready` | capture | Overlay session data |
| `editor://open` | editor | New editor session |
| `pin://show` | editor | Pinned image payload |
| `history://changed` | history | Shared recent list changed |
| `radial://*` | drag bridge | Drag context, mode, drop and dismissal |
| `recording://started` | recording | Recording session data |
| `share://peers` | share | Visible peer list changed |
| `share://transfer` | share | Sending/received/error transfer state |
| `update://progress` | update | Download state |
| `update://status` | update | Verified update or error state |
## Platform adapters
| Concern | macOS | Windows | Linux |
| --- | --- | --- | --- |
| Drag detection | AppKit drag bridge sidecar | Win32 drag-state poll plus native drop | No global drag bridge; main-window picker only |
| Capture | `screencapture` | GDI `BitBlt` / `GetDIBits` | `grim`, fallback `gnome-screenshot` |
| Recording | `screencapture -v` | FFmpeg/X11 | `wf-recorder` on Wayland, FFmpeg on X11 |
| Document/PDF rendering | AppKit/PDFKit Swift sidecars | Poppler/Pandoc | Poppler/Pandoc |
| LAN discovery interface list | `getifaddrs` | `GetAdaptersAddresses` | `getifaddrs` |
All external processes go through `process::command`, which hides console
windows on Windows. A source-check test rejects bare `Command::new` in shipped
code.
## Invariants
- A conversion or tool never overwrites its source or an existing output.
- A visible wedge exists only because the format catalogue lists it and the
backend has a handler.
- Failures the interface maps have stable backend codes; raw third-party
diagnostics may pass through unchanged.
- A transfer or update is not considered complete until all declared bytes are
present and any required hash matches.
- A helper process receives untrusted paths as arguments, never as executable
script text.
- Resource limits are enforced before unbounded allocation where a path can
receive large local input.
## Related documents
- [`SPECIFICATION.md`](SPECIFICATION.md): observable behaviour and acceptance.
- [`SECURITY.md`](SECURITY.md): threat model and residual risk.
- [`ENGINEERING-NOTES.md`](ENGINEERING-NOTES.md): regression constraints.
- [`RELEASE.md`](RELEASE.md): update channel and handoff.