Files
Marcos Paulo a71e294566
ci / ci (macos-latest) (push) Has been cancelled
ci / ci (ubuntu-latest) (push) Has been cancelled
ci / ci (windows-latest) (push) Has been cancelled
docs: specs, designs, research and agent rules for mobile, sync and collaboration
- specs: mobile-and-sync, collaboration, vault-launcher, e2ee, attachments-and-history, capture-and-publish, agents (brief and orchestrator notes for MiniMax and GLM agents)
- research: sync landscape, security and server, mobile platform (browsed, cited)
- design/mobile: 24 PaperCraft exports (dark and light) of the phone, desktop, sharing and launcher screens
- .claude: project skills and path rules so delegated agents follow the repo rules; CLAUDE.md imports AGENTS.md
- ARCHITECTURE and ROADMAP updated; AGENTS.md lists the approved sync dependencies

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-20 07:46:30 -03:00

8.3 KiB

Mobile (Android, iOS) and sync

Problem

NotesCraft runs on macOS, Windows and Linux only. A vault lives on one machine, so notes cannot follow the owner to a phone, and ROADMAP lists "no mobile build" and "no bottom tab bar". Sync, mobile apps and git remotes are out of scope in SPEC 6.1.

Goal

Open the same vault on desktop, Android and iOS, edit offline anywhere, and see edits converge on every device within seconds of being online.

Non-Goals

  • End-to-end encrypted multi-user sharing (single owner, many devices, v1).
  • Real-time co-editing of one note (character-level CRDT). Conflicts are file-level.
  • Obsidian Sync wire compatibility. Plain .md files stay the source of truth, so Obsidian and git keep working on the same folder.
  • A web (wasm) build.

Findings (what the code says today)

Desktop-only seams, all small:

  • apps/notescraft: main.rs, desktop.rs, audio.rs (cpal), menu.rs (muda), notify.rs, keychain.rs, net.rs, google.rs; window via eframe::NativeOptions with wayland/x11 features.
  • rfd (file dialogs): no Android/iOS backend for folder pick.
  • notify file watcher (crates/vault/src/watch.rs): inotify/FSEvents; no use on iOS sandbox beyond own container, polling fallback needed.
  • Command::new users: git (crates/git), ACP agents (crates/acp), syntax fetch, ps/PowerShell (perf.rs), PDF preview, video/audio players. None can spawn processes on iOS; Android restricted. These features are desktop-only behind cfg.
  • Pure Rust, portable as is: vault markdown index graph canvas backlinks blocks lint templates themes i18n editor math diagrams whiteboard engine (minus control server, mcp, plugins process paths).
  • ui-egui: panels are floating desktop cards; width logic exists (shell/layout.rs) but there is no phone layout.

Mobile approach

  1. Shell: keep egui. eframe supports Android (android-activity, android-native-activity feature) and iOS via a static lib wrapped in a thin Xcode project. New app crate apps/notescraft-mobile (cdylib/staticlib) calls the same ui-egui root. No webview, no JS.
  2. Layout: below 600 pt width switch to one column: bottom tab bar (Notes, Search, Graph, Calendar, More), full-screen note, bottom sheet for Outline/Backlinks/Related, safe-area insets from the OS, 44 pt targets, soft-keyboard toolbar above the keyboard (the "mobile bottom toolbar" already on the ROADMAP).
  3. Input: touch scroll, long-press for context menu, two-finger pinch for zoom. Vim mode off by default.
  4. Storage: vault inside app sandbox (filesDir on Android, Documents on iOS, Files-app visible). External folder access later via SAF / security-scoped bookmarks. Desktop-only commands report "not available on this device" through the command registry (enabled).
  5. Cfg split: cfg(not(any(target_os="android", target_os="ios"))) around process-spawning features; the engine already has enabled on commands.

Sync design

Model: device-local vault is truth while offline. A server stores the latest revision of every file and a change log. Files only, no database inside the vault; sync state lives in .notescraft/sync/state.json (written via write_private).

Entities

  • Vault id (uuid). Device id. Revision = monotonically increasing server seq (u64).
  • File record: path, hash (sha-256 hex), size, mtime_ms, seq, deleted.

API (HTTPS, JSON, bearer device token). Base /v1/vaults/{vault}.

Method Path Purpose
POST /v1/devices register a device with a one-time pairing code, returns device token
GET /changes?since={seq} file records with seq > since, plus head seq; long-poll with wait=25
GET /files/{path} download blob (If-None-Match: hash)
PUT /files/{path} upload blob; header X-Base-Seq is the seq the client last saw; 201 ok, 409 {current} on conflict
DELETE /files/{path} tombstone; same X-Base-Seq rule
POST /batch/check body = list of {path,hash}; returns the hashes the server lacks (skip uploads)

Client loop (desktop and mobile share one crate)

  1. Scan vault, hash changed files (size+mtime cache), build local changes.
  2. GET /changes?since=last_seq, apply remote changes whose local file is unchanged since last sync.
  3. Upload local changes with X-Base-Seq. On 409 run conflict rule.
  4. Store new last_seq; long-poll again. Debounce 2 s after local edits. Mobile: sync on foreground, on save, and by OS background task (WorkManager / BGAppRefreshTask).

Conflict rule (never lose data)

  • Both sides changed a note: keep the server version at the path, write the local version as name (conflict <device> <date>).md, show a Conflicts list. For .md, if a three-way merge against the common ancestor hash (kept in local snapshots, .notescraft/history) is clean, merge silently.
  • Edit vs delete: edit wins (restore the file).
  • Rename = delete + create; the content hash lets the server and client detect it and move instead of re-upload.
  • Sync never touches .obsidian/ plugins, .notescraft/history, .trash; settings sync is opt-in per folder.

Server (homelab, k3s)

  • Namespace notescraft-sync, one Deployment behind Traefik at sync.marcospaulo.dev.br, TLS by cert-manager.
  • Blobs: private bucket notescraft-sync in the existing MinIO (HOMELAB_OPERATIONS: object semantics fit). Metadata (file records, seq, devices): SQLite on a small local-path PVC, or a JSON-lines log in the bucket if the owner prefers zero PVC.
  • Auth: per-device bearer token minted by pairing code (shown on desktop as QR); optional Logto SSO later. Tokens stored hashed. Rate limit, 25 MB per file cap, path guard identical to Vault::resolve.
  • Backup: bucket versioning on; metadata snapshot with the existing backup flow.
  • Implementation language: Rust (apps/notescraft-sync-server) to share protocol types in crates/sync.

Crates

  • crates/sync (L1): protocol types, manifest diff, conflict rules, hashing. Pure, no I/O, fully unit-tested.
  • crates/engine: sync client driver, commands sync.now, sync.status, sync.pair, sync.conflicts.
  • apps/notescraft-sync-server: the HTTP service.
  • ui-egui: Settings > Sync page, status-bar indicator, Conflicts view.

Many vaults

A person has many vaults. The device token is per user and device (not per vault), the client keeps one binding per local vault in .notescraft/sync/binding.json, and a Vaults screen connects or creates server vaults. Details and acceptance criteria: specs/collaboration/spec.md, section "Many vaults".

Acceptance Criteria

  • Given two devices paired to one vault, when device A saves a note online, then device B has the same bytes within 10 s.
  • Given device A offline edits note N and device B edits N, when both reconnect, then no text is lost and a conflict copy exists unless a clean three-way merge applies.
  • Given a file deleted on A and edited on B, when synced, then the edited file survives on both.
  • Given an 8,000-note vault, when nothing changed, then a sync cycle sends one /changes request and no uploads.
  • Given a wrong or revoked token, then the server answers 401 and the client shows "Sign in again" without touching files.
  • Given path ../x or .notescraft/.., then the server answers 400.
  • Given a phone at 390 pt wide, then the shell shows one column with a bottom tab bar and no horizontal scroll.

Constraints

  • Stack: Rust only, egui, no JS. New third-party dependencies need owner approval (see Open Questions).
  • Never crash: no unwrap, bounded sizes, checked_* on all sequence and size maths.
  • Every disk write through craft-atomic / write_private.
  • Layering: sync at L1, client driver in engine (L4), UI in L6.
  • Server follows HOMELAB_OPERATIONS.md: live discovery first, MinIO for blobs, no secrets in Git, accessctl for ingress, explicit CPU/memory limits.

Open Questions

  1. Dependencies: HTTP server (axum + tokio, or tiny_http), HTTP client (ureq with rustls), rusqlite, sha2 outside engine. Approve which?
  2. Deploy to the homelab k3s now, or build and test the server locally first? Deploy mutates the cluster.
  3. Metadata store: SQLite on a PVC, or MinIO-only?
  4. Auth: pairing-code device tokens (recommended) or Logto SSO from day one?
  5. iOS needs a Mac with Xcode and an Apple developer account for device install; Android needs the NDK + cargo-ndk. Confirm both toolchains exist here.