remoras — architecture plan#
These docs are LLM-generated with minimal human editing. They serve as shared context for AI builders. Humans should read
../docs/for curated summaries. If you're reviewing or contributing to design decisions, edit../docs/— changes here are typically AI-driven and may not reflect deliberate human review.
An outliner built on the bones of Logseq DB (block tree, types), with the features people love from Obsidian, Reflect, and clean-markdown outliners, plus native database rollups, ClickUp-style planning, offline-first no-data-loss storage, E2EE sync, atproto sharing, and local LLM/RAG — on a modern stack (Rust + TypeScript) that is easy for open-source contributors to join.
This plan is deliberately opinionated. The stated bottleneck for this project is decision fatigue, not implementation difficulty (it will be built with heavy LLM assistance). So every file makes a call and records the rejected alternatives once, so you never have to re-litigate them.
Read in this order#
| File | What it decides |
|---|---|
design/00-overview.md |
Vision, non-negotiables, the one-page stack decision. |
design/01-decisions-adr.md |
Every major decision + why + what was rejected. The anti-decision-fatigue file. |
design/02-core-engine.md |
The Rust core: op log as source of truth (Path C+), SQLite as derived index, storage/format. |
design/03-data-model.md |
Blocks, pages, types, properties, rollups, formulas, views. |
design/04-ui-architecture.md |
Tauri v2 + Solid, the editor stack, mobile, why not GPUI-primary. |
design/05-sync-and-storage.md |
Offline-first, file-sync, self-hosted relay, E2EE, keys. |
design/06-atproto-social.md |
Lexicons, PDS, the hard public/private boundary. |
design/07-search-llm-rag.md |
FTS5 + sqlite-vec, on-device embeddings, local LLM, RAG. |
design/08-tasks-planning-calendar.md |
ClickUp-style tasks/projects, views, Reflect-style calendar. |
design/09-plugins.md |
WASM (WIT) + TypeScript plugin surfaces. |
design/10-adhd-ux-principles.md |
Executive-function design rules that constrain every feature. |
design/11-roadmap-phases.md |
Build order. What to ship first and why. |
design/12-agent-delegation.md |
How to keep building this cheaply with Claude Code subagents. |
design/13-preflight.md |
The handoff: open decisions, Phase-0 specs, repo/harness checklist. |
specs/16-migration-strategy.md |
Format versioning, schema evolution, decades-vault migration strategy. |
specs/17-failure-modes.md |
Failure mode catalog: corruption, divergence, disk full, malicious peers, lost recovery phrase. |
specs/18-accessibility.md |
Accessibility beyond cognitive load: screen reader, keyboard, motor, visual. |
specs/19-testing-strategy.md |
Per-crate testing, FFI integration, property-based, performance regression, sync convergence, E2E. |
specs/20-security-threat-model.md |
Systematic threat model: untrusted atproto, malicious peers, WASM sandbox, metadata leakage. |
specs/21-mobile-constraints.md |
iOS/Android background, storage, biometric at-rest encryption, ProseMirror mobile IME, memory. |
specs/22-performance-budget.md |
Per-operation SLOs, max graph size, memory budget, cold-start targets, CI enforcement. §Appendix B: historical Loro-era performance research (merged from former doc 15 (no longer exists)). |
design/23-smaller-fixes.md |
Today surface, atproto deletion, i18n, backup verification, contributor onboarding, collab UX. |
evidence/25-benchmark-roadmap.md |
Followup benchmarks + gap caveats mapped to project phases. Tracks what's untested and when to test it. |
specs/27-op-log-compaction-design.md |
Op log compaction design: checkpoint format, trigger, sync, time travel, content redaction. The "decades vault" enabler. |
design/30-deferred-features.md |
Deferred features from competitive gap analysis: graph view, voice notes, templates, footnotes/citations, tabs/split panes, real-time collab, Readwise/Zotero, web clipper, and more. Status + what needs designing before implementation. |
Validation & spikes#
Spike results and validation docs — proof that the architecture works. Read after the architecture docs, not as part of the design narrative.
| File | What it validates |
|---|---|
evidence/26-path-c-validation.md |
Path C+ validation: op-log architecture spikes. Phase 0 exit gate for committing to op-log over Loro-as-truth. |
evidence/28-y-prosemirror-spike-results.md |
y-prosemirror mount/unmount spike: virtualized scrolling, state preservation, memory leak, undo scoping, sync delta. All pass. |
evidence/29-ios-spike-v2-results.md |
iOS spike v2: op-log + Yrs + Kleppmann tree on iOS. 52 MB stripped, 0.007ms FFI, 26ms replay at 10k. All pass. Replaces ../archive/24-ios-spike-results.md. |
Build specs (specs/)#
Implementation contracts — the exact specs Phase 0 builders implement against.
| File | What it specifies |
|---|---|
specs/01-oplog-document-schema.md |
Graph data model (Path C+): op types, tree structure, Yrs per-block text, checkpoint format, rendering supertags, views. |
specs/02-on-disk-layout.md |
On-disk graph layout: op_log/, checkpoints/, mirror/, assets/, index.sqlite, graph.json. Naming, locking, encryption-at-rest. |
specs/03-md-json-mirror.md |
md/json mirror format: Markdown conventions, JSON sidecar schema, round-trip invariants, 3-level external edit matching. The decades guarantee. |
specs/04-sqlite-ddl.md |
SQLite DDL v1: blocks, properties, block_tags, links, supertags, views, blocks_fts, block_vectors, asset_registry. Incremental update contract, rebuild, query patterns. |
specs/05-ffi-commands.md |
FFI command list v1: ~15 commands/queries for Phase 0–1 (create/edit/move/delete, load page, search, backlinks, subscribe). |
Archived docs (archive/)#
Completed work trackers and stale spikes, kept for historical reference:
archive/24-ios-spike-results.md— Loro iOS FFI spike (historical). Superseded by Path C+ (ADR-002). Replaced byevidence/29-ios-spike-v2-results.md.
The one-sentence architecture#
A UI-agnostic Rust core (remoras-core) owns an op log (append-only JSONL, one file per actor) as the source of truth, materialized via a Kleppmann tree CRDT + per-block Yrs text docs, continuously mirrors to plain Markdown + JSON for durability, maintains a rebuildable SQLite index (FTS5 + sqlite-vec) for fast query/search/RAG, and is driven by thin Tauri v2 shells (desktop + mobile) with a SolidJS frontend — with sync offered at five escalating tiers from fully-offline to E2EE-cloud to atproto-public-sharing.
Status of the moving parts (verified July 2026)#
- Op log (Path C+) — committed. ADR-002 was revised from Loro-as-truth to op-log-as-truth. All five Phase 0 exit gate criteria pass (
evidence/26-path-c-validation.md): op log replay <500ms at 1M ops, Kleppmann tree fuzz 10k trials zero divergence, Yrs per-block memory <2KB/doc, matching 100% accuracy, compaction designed. The original Loro benchmarks (loro-tree-bench,loro-cycle-fuzz) remain as historical reference data; the original iOS spike (archive/24-ios-spike-results.md, archived) tested Loro's FFI. The op-log architecture iOS spike (evidence/29-ios-spike-v2-results.md) passed: 52 MB stripped, 0.007ms FFI, 26ms replay at 10k. - Tauri v2 — stable since Oct 2024; iOS/Android are a stable API but the team is explicit it is a foundation, not the finished mobile story. Usable, with known App Store 4.2 (webview-wrapper) review risk to plan around.
- GPUI — beautiful, fast, pre-1.0, usable standalone now, but mobile is experimental/unpublished. Kept as an optional desktop shell only.
- atproto — self-hostable PDS, custom lexicons work today. All data is public; encryption/private content is a deferred protocol phase. This forces a clean split: atproto is the sharing layer, never the private-sync layer.
- sqlite-vec — pure-C vector search that runs everywhere SQLite runs (including mobile/WASM), with a clean rusqlite path. Green light for RAG.