🧭 Nodus

Secure, verifiable, deterministic file sync for desktop.
Local-first by design. Policy-driven. Receipt-backed.

Quick Start • Core Capabilities • Architecture • Endpoint Matrix • Testing

📌 What Is Nodus?

Nodus is a desktop sync system that helps you:

• define source/destination endpoints,
• attach an explicit sync policy,
• run deterministic scan/plan/transfer pipelines,
• generate verifiable receipts,
• package transfer evidence as portable capsules (.ndc).

It is designed for operators and engineers who want local control, auditability, and clear execution flow instead of opaque black-box sync behavior.

✨ Core Capabilities

🗂️ Job + Endpoint Orchestration

• Endpoint management with typed configuration forms (local, FTP/SFTP/SCP/WebDAV/HTTP(S), cloud variants).
• Job wizard for source/destination wiring.
• Policy attachment per job (mode, checksum, include/exclude filters, delete behavior).

⚙️ Deterministic Engine Pipeline

• Scan: inventories source files and computes BLAKE3 hashes.
• Plan: diffs current scan against persisted object inventory.
• Run: executes transfer and emits live state/progress events.
• Commit policy: mirror / keep-on-delete / trash-on-delete behavior.

🧾 Receipt + Integrity System

• Per-run transfer manifest with file/chunk metadata.
• BLAKE3 manifest hashing.
• Merkle-root receipt generation from chunk hashes.
• Receipt verification workflow (rehash + recompute Merkle root).

📦 Capsule Workflow

• Pack verified run artifacts into compressed .ndc capsules.
• Capsule contains manifest.json, header.json, and chunk payloads.
• Capsule apply flow restores content to a destination endpoint.

📊 Observability and Audit

• Live Tauri event stream for job progress/state/logs.
• Persisted audit logs in local SQLite (audit.db).
• Logs UI with filters, level toggles, and live tail behavior.

🌍 UX and Localization

• Bulma + Svelte UI with dashboard, jobs, runs, scans, receipts, capsules, logs, settings.
• i18n support for multiple locales (en, fr, hi, zh, es, ru, de, ja, te, ta).

🧱 Architecture

Svelte UI (routes/components)
        │
        │ Tauri IPC commands
        ▼
Rust Host (src-tauri/src/main.rs)
        │
        ├─ nodus-engine   (scan/diff/plan/transfer/commit)
        ├─ nodus-protocols (local + transport adapters)
        ├─ nodus-db       (SQLite + schema + query bridge)
        ├─ nodus-receipts (manifest + receipt verify)
        ├─ nodus-capsules (.ndc pack/apply)
        ├─ nodus-secrets  (OS keyring integration)
        └─ nodus-logging  (audit sink + structured log listing)

🔄 Execution Flow

1. Create endpoints.
2. Create a job and assign a policy.
3. Run Scan to build source inventory.
4. Run Plan to produce sync operations (copy, update, delete).
5. Run Run to execute transfer and commit behavior.
6. Generate receipt (manifest hash + Merkle root).
7. Optionally pack capsule (.ndc) from receipt.
8. Re-verify receipts or apply capsules later.

📂 Repository Layout

.
├─ src/                         # Svelte app (routes, components, stores, i18n)
├─ src-tauri/
│  ├─ src/main.rs               # Tauri command surface + runtime wiring
│  ├─ crates/
│  │  ├─ engine/                # scan/diff/plan/transfer/commit stages
│  │  ├─ protocols/             # endpoint protocol adapters
│  │  ├─ db/                    # SQLite init + query facade
│  │  ├─ receipts/              # manifest/receipt record + verify
│  │  ├─ capsules/              # .ndc pack/apply logic
│  │  ├─ logging/               # audit logging stack
│  │  ├─ secrets/               # keyring-backed secret storage
│  │  ├─ watcher/               # filesystem watch utilities
│  │  └─ cloud/                 # cloud adapter crate (integration path)
├─ tests/e2e/                   # Playwright UI/E2E suite
├─ docker/                      # integration service containers (FTP/SFTP/etc.)
└─ .github/workflows/           # CI, nightly integration, release workflows

🚀 Quick Start

1) Prerequisites

• Node.js >= 20.10.0
• pnpm >= 9
• Rust stable toolchain
• Tauri v2 system prerequisites for your OS

2) Install Dependencies

pnpm install

3) Run UI Dev Server

pnpm dev

4) Run Desktop App (Tauri)

pnpm tauri:dev

5) Build Desktop App

pnpm tauri:build

🧪 Testing

Frontend checks

pnpm check

E2E tests (Playwright)

pnpm test:e2e

Manual split mode:

pnpm e2e:start
pnpm e2e

Rust workspace tests

cd src-tauri
cargo test --workspace --all-features

🔌 Endpoint Support Matrix

Current runtime status in this repository:

Legend:

• ✅ implemented and wired
• 🚧 scaffolded / integration pending in engine_run
• ⚠️ available in dedicated crate path but not currently wired into active run flow

🗃️ Data, Logs, and Secrets

Nodus stores runtime data locally under your OS app-data directory (or NODUS_DATA_DIR if set).

Typical layout:

Nodus/
├─ nodus.sqlite           # primary relational state
├─ nodus.kv               # key-value store (redb)
├─ receipts/
│  └─ <run_id>/manifest.json
└─ logs/
   ├─ audit.db            # structured audit entries
   └─ nodus.log           # rolling file logs

Secrets are stored via OS keyring APIs through nodus-secrets.

🧰 Useful Scripts

From package.json:

• pnpm dev - Vite dev server
• pnpm build - production web bundle
• pnpm tauri:dev - desktop dev mode
• pnpm tauri:build - desktop production build
• pnpm check - Svelte/TS checks
• pnpm test:e2e - end-to-end tests
• pnpm win:portable / pnpm win:msi - Windows packaging script entry points

🧪 Integration Services (Optional)

Bring up local FTP/SFTP test services:

docker compose -f docker/compose.integration.yml up --build

Stop them:

docker compose -f docker/compose.integration.yml down

⚠️ Current Implementation Notes

• The app is intended to run in Tauri desktop context; browser-only mode is limited.
• engine_cancel is currently a placeholder command.
• Windows packaging script files are present but currently minimal stubs.

🧭 Roadmap Direction

• Expand runtime endpoint wiring beyond local destination.
• Harden cancellation/resume semantics in run lifecycle.
• Improve cross-protocol integration test coverage.
• Extend capsule verification/apply ergonomics.
• Continue UI polish and operator workflow refinement.

🤝 Contributing

Contributions are welcome, especially around:

• protocol integration wiring,
• receipt/capsule correctness tests,
• engine reliability and performance,
• UI/UX improvements for operational workflows.

👤 Author

Mahesh Chandra Teja Garnepudi
GitHub: MaheshChandraTeja

Authors

Mahesh Chandra Teja Garnepudi
Sagarika Srivastava

Built at Kairais Tech

License

Private project for now. Licensing details will be published later.