Marcos Paulo
a71e294566
- 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>
3.3 KiB
Plan: Mobile and sync
Approach
Files stay the truth; a small HTTP service keeps a per-vault revision ledger and content-addressed blobs; every device runs the same client loop (scan, fetch changes, plan, act). Pure decisions live in crates/sync (done); the network and disk driver lives in engine so desktop and phone share it; the phone is the same egui app in a second shell crate with a compact layout. Chosen over git-based sync (no git on phones, merge UX poor) and over a CRDT (plain .md interop with Obsidian would break).
Architecture
- Data flow: device edit -> vault file ->
sync_once(scan,GET /changes,plan,PUT/GET/DELETE) -> serverLedger-> SQLite + blob file -> long-poll wakes the other devices. - New modules:
crates/sync(done),apps/notescraft-sync-server(done, hardening in task 3),crates/engine/src/sync/(task 4), enginesync.*commands and worker (task 5),ui-eguisync views (task 6), compact layout (task 7),apps/notescraft-mobile(task 8). - Modified:
engine(module, commands, settings),ui-egui(Settings > Sync, status bar pill, Conflicts view, bottom tab bar, keyboard toolbar),docs/ARCHITECTURE.md,ROADMAP.md.
Files
- Create: see tasks.
- Modify:
crates/engine/Cargo.toml(notescraft-sync,ureq),crates/engine/src/lib.rs,crates/engine/src/prefs/*(sync settings),crates/ui-egui/src/shell/layout.rs(compact mode).
Data
- Server: SQLite tables
vaults,pairings,devices,files(+audit,updated_ms,last_seen_msin task 3). Blobsblobs/<vault>/<sha256>. - Client:
.notescraft/sync/state.json(last_seq,bases),.notescraft/sync/base/<hash>(merge ancestors), device token in the OS keychain where available (desktopkeychain.rs), else.notescraft/sync/credentials.jsonwith 0600 permissions on first version. - API: see
apps/notescraft-sync-server/src/routes.rsand ARCHITECTURE.
Dependencies
Approved 2026-10-19: axum, tokio, ureq (rustls), rusqlite, sha2. Needs approval before use: chacha20poly1305, argon2, zeroize, rand (E2EE, task 9); qrcodegen (QR, task 6; dormant crate, alternatives noted in research); tower_governor only if IP limits become possible (they are not behind the tunnel).
Risks
- egui on mobile: soft keyboard/IME and safe-area support are the weak spots (see research/mobile-platform.md); mitigate with a spike (task 8) before committing to the full port.
- A sync bug can destroy notes: never lose data (conflict copies,
.trash, base copies); property tests oncrates/sync; a dry-run mode in the driver before the first real sync. - E2EE changes the server data model (opaque ids); design the blob and record format before shipping v1 to the public, or accept a one-time migration.
- Cloudflare Tunnel hides client IPs, so rate limits are global, not per IP.
Out of scope (defer)
Real-time co-editing, shared multi-user vaults, server-side search, web client, publish, web clipper (ranked in research for later).
Test strategy
- Unit:
crates/sync(26), driver with a fake remote (task 4). - Integration: server over real HTTP (6 now, more in task 3); client against the real server in a test binary (task 5).
- Manual: two real devices on the homelab after the deploy approval; offline edit and reconnect; airplane-mode drill.