C1 · Core data & storage

This cluster is a single StorageAdapter interface (lib/storage/adapter.ts) implemented four times — LocalAdapter (markdown files on disk as source of truth plus a rebuildable per-vault SQLite index), SupabaseAdapter (multi-tenant Postgres where RLS is the security boundary), MemoryAdapter (test double), and JsonFileAdapter (single-file portability reference). It also owns mode selection (ELI_MODE), the vault config store (~/.eli/config.json), the markdown/frontmatter/wikilink helper library, both database schemas and migration chains (SQLite FTS5; Postgres tsvector + pgvector + RLS), the walker → scanner → incremental-index pipeline, the chokidar watcher + in-process event bus that keep the local index fresh, and process bootstrap (env.ts, instrumentation.ts, middleware.ts). Every Server Action, RSC page, API route, and MCP tool reaches notes exclusively through getStorage() (lib/storage/index.ts) — components never import an adapter directly.

• Modes: local (files + SQLite) and saas (Supabase Postgres + RLS), selected by ELI_MODE.
• Key dirs: lib/storage/, lib/db/, lib/domain/, lib/index/, lib/watch/, lib/config/, root bootstrap (env.ts, instrumentation.ts, middleware.ts).
• Depends on: better-sqlite3, chokidar, supabase-js, gray-matter, diff-match-patch.
• Feeds: every other cluster — authoring UX (02), search (03), AI platform (04), agent surface (05), versioning (06), SaaS collaboration (07), capture/templates (08), platform ops (09).

Capabilities

System view — simplified

This cluster IS the persistence layer: one interface, two production backends, one mode switch. Standalone, it is a complete local-first markdown note store — point LocalAdapter at any folder of .md files and you get CRUD, full-text search, versions, backlinks, tags, and live re-indexing of external edits, with zero network, zero auth, and an index that can be deleted and rebuilt from the files at any time. The SaaS half is a drop-in replacement of the same interface where Postgres rows are the source of truth and row-level security (not application code) enforces tenancy. Everything above this layer — editor, search UI, AI, agents — is written against the StorageAdapter contract and does not know which backend it is talking to.

System view — detailed

Data flow — simplified

The single most load-bearing flow: a local save writes the markdown file first (disk is the source of truth), then updates the derived SQLite index and appends an immutable version row in one transaction. markEcho is stamped before and after the rename so the chokidar watcher discards the filesystem event the write itself produces — without it every save would trigger a redundant full rescan. The emitted ChangeEvent fans out over SSE so other open tabs refresh.

Data flow — detailed

Local save (file-first write, echo suppression) followed by an external edit picked up by the watcher:

SaaS save via notes_save RPC with optimistic concurrency and conflict snapshot:

Works separately / works together

Standalone

With every other cluster turned off, this cluster is still a usable product core: a local markdown vault with CRUD, atomic file-first saves, full-text search (FTS5), version history with section-level diff, backlinks, tag/type/folder lenses, trash/restore, and an index that self-heals — delete ~/.eli/index and the first db() call rebuilds it from the files (lib/storage/local.ts:87-128). External tools (Obsidian, scripts, agents editing files directly) are first-class: the watcher re-indexes their writes within milliseconds. The SaaS half standalone is a complete multi-tenant note database whose invariants (role ladder, append-only versions, tenancy bootstrap, audit) live in the database itself — triggers and RLS hold even if application code is bypassed. MemoryAdapter and JsonFileAdapter prove the contract is backend-agnostic.

Composed

• Every cluster above consumes this one exclusively through getStorage() — app/_actions/*.ts and all app/(local)/v/* + app/(saas)/(app)/w/* RSC pages (C2), MCP tools (C5), the clipper app/api/clip/route.ts (C8), and cron routes (C9).
• C3 Semantic search: lib/search/hybrid.ts and app/api/search/hybrid/route.ts bypass adapter.semanticSearch (which throws) and call lib/storage/local/embeddings.knnByEmbedding / lib/storage/supabase/knn.knnNotesdirectly, reusing the adapter's RLS-scoped sb client; app/api/ai/embed/route.ts, lib/ai/auto-embed-queue.ts, and scripts/embed-backfill.mjs populate the embedding stores.
• C4 AI platform: lib/ai/key-resolver.ts reads BYOK keys from lib/storage/supabase/ai-keys.getAiKeyPlaintext (service-role decrypt) or config.json#aiKey; workspaces.ai_gateway_config and config.json#aiGateway feed gateway routing; chat_threads/chat_messages/ai_usage exist in both schemas so the chat UI is mode-agnostic.
• C5 Agent surface: MCP servers (bin/eli-mcp.mjs stdio, app/api/mcp/[transport]/route.ts HTTP) authenticate against config.json#mcpToken (local) or personal_access_tokens rows (saas) and operate on notes purely through the adapter contract; comment section anchors power the add_comment tool.
• C6 Versioning: the versions tables, diffVersions section diff, and replaceSection written here are the entire data layer of the history UI; every local save additionally calls lib/git/commit-loop.enqueueCommit using config.json#git.
• C7 SaaS collaboration: memberships/invites/audit/profiles/shares/attachments and all RLS policies defined in lib/db/migrations/pg/ are its foundation; middleware.ts is its request-level gate.
• C9 Platform ops: owns the delivery side of the freshness machinery described here (SSE route, VaultEventsBridge, kill switches), the dev/test endpoints that reach into closeAll/_resetCacheForTests/scanVault, the pgTAP CI gate over the RLS migrations, and the perf gate over local search.
• Frontend live updates: app/api/events/route.ts subscribes to lib/watch/events-bus and streams ChangeEvents to components/vault-events-bridge.tsx, which debounces 500ms and calls router.refresh().

Load-bearing details

• ELI_MODE is a zod enum ['local','saas'] defaulting to 'local' (env.ts:15); saas additionally requires NEXT_PUBLIC_SUPABASE_URL/ANON_KEY via superRefine (env.ts:103-120). Verified in source.
• The local index DB lives at ~/.eli/index/<first-16-hex-of-sha256(vaultPath)>.db (lib/db/client.sqlite.ts:31-34, verified); ELI_HOME overrides ~/.eli (lib/config/path.ts:10-12).
• SQLite clients, LocalAdapter instances, watchers, and the event bus are all cached on globalThis (__ELI_SQLITE_CACHE__, __ELI_LOCAL_ADAPTERS__, __ELI_WATCHERS__, __ELI_EVENT_BUS__) to survive Turbopack multi-bundle evaluation and dev HMR; the SQLite cache is additionally invalidated by inode change so a wiped/recreated DB file under a live dev server isn't read through a stale fd (lib/db/client.sqlite.ts:19-29,62-73).
• The two hash schemes are not comparable across modes: local content_hash = sha256 of the full serialized file (frontmatter block + body, lib/storage/helpers/hash.ts); SaaS/memory/json-file compute sha256(body + JSON.stringify(frontmatter)) (lib/storage/supabase/writes.ts:40,98; memory.ts:72).
• Conflict handling is last-write-wins + snapshot, never a 409: a stale expectedVersionId snapshots the loser to a versions row tagged auto-conflict-snapshot and proceeds; onConflictSnapshot fires at most once per updateNote (lib/storage/adapter.ts:43-68; local/writes.ts:255-277; supabase/writes.ts:100-183, verified). notes_save raises errcode 40001on OCC mismatch and the adapter's retry force-accepts with p_expected_version_id=null after snapshotting (0006_notes_save.sql:48-49, verified; supabase/writes.ts:132-172, verified).
• Version author identity diverges: local always stores author_id NULL (local/writes.ts:168); SaaS notes_save derives it from request.jwt.claims.sub inside the function (0006:38); local comments use the literal sentinel 'local' as author_id (local/comments.ts:23).
• IDs are monotonic ULIDs locally (sub-millisecond ordering for versions, lib/domain/ids.ts:1-9, verified) but random UUIDs in SaaS; getNote disambiguates id-vs-path by ULID regex locally (local/row.ts:36-38) and UUID regex in SaaS (supabase/queries.ts:124).
• Echo suppression: markEchostamps a 750ms-TTL per-relative-path entry, GC'd beyond 500 entries; an entry is consumed (deleted) on first match (lib/watch/chokidar.ts:36-59, verified). atomicWrite marks before and after the rename because chokidar's awaitWriteFinish can fire later than the rename returns (local/writes.ts:35-49, verified).
• incremental.updatePath deliberately re-runs the full scanVault(prune:false) for any single-file change, relying on sha256 hash-skip for cheapness — an explicitly documented v1 tradeoff (lib/index/incremental.ts:35-42, verified in source comments).
• First-touch indexing is race-proof across concurrent Next workers: an exclusive transaction stamps meta.initial_scan_at='pending' before scanning (lib/storage/local.ts:100-124).
• The walker's SKIP_DIRS includes .eli, so files soft-deleted into <vault>/.eli/trash/ never re-index (lib/index/walk.ts:5, verified).
• Postgres notes.fts is a STORED generated tsvector with a GIN index and notes.embedding is vector(1536) with an HNSW vector_cosine_ops index — declared only in hand-written SQL because drizzle-kit cannot emit them (0000_initial.sql:75-105; schema.pg.ts:34-41). notes_knn returns 1 - cosine distance to match the local knnByEmbedding contract (0013_notes_knn.sql:31-36); local embedding BLOBs use explicit little-endian DataView reads for cross-CPU portability (local/embeddings.ts:45-53).
• RLS role ladder: notes/versions/note_links/attachments/share_links writes require owner|admin|editor; comment inserts require commenter+ AND author_id=auth.uid(); versions are append-only (no UPDATE/DELETE policies); user_favorites and chat_threads are strictly self-only even for admins (0001_rls.sql; 0009; 0014). Service-role usage is a documented allow-list (profiles trigger, share-token validation, seeds, invite acceptance, PAT last_used_at bumps, embedding writes — 0001_rls.sql footer).
• SaaS FTS goes through the notes_search SECURITY INVOKER function specifically to fix a previously injection-prone websearch_to_tsquery string interpolation (0010_notes_search.sql header).
• postgres-js is intentionally not a dependency: lib/db/client.pg.ts only exposes a lazy factory; the production SaaS runtime path is entirely supabase-js so RLS is enforced via the session JWT (client.pg.ts:4-19). The pg migration runtime runner is used only by PGlite tests; production applies migrations via supabase db push (lib/db/migrations/pg/runner.ts:12-15).
• config.json is written 0600 (dir 0700); localToken (CSRF/DNS-rebinding cookie) and mcpToken are auto-generated 32-byte base64url secrets on first read (lib/config/index.ts:19-47); forward-compatible repair merges user data over defaults on schema mismatch (index.ts:103-115).
• instrumentation.register() only runs when NEXT_RUNTIME==='nodejs' and ELI_MODE is unset-or-local, because chokidar and better-sqlite3 break Edge bundles (instrumentation.ts:16-17); both are serverExternalPackages (next.config.ts:7).
• ai_keys ciphertext uses pgp_sym_encrypt with cipher-algo=aes256, s2k-mode=3, s2k-digest-algo=sha256 keyed by ELI_KMS_KEY (min 16 chars, env.ts:45); decrypt is a service-role-only RPC (0011_ai_keys.sql:157,170-186).
• Bucket predicates wrap status in IFNULL(...,'') to avoid SQLite 3-valued NULL propagation silently hiding status-less notes (lib/storage/helpers/status.ts:41-55); default listNotes excludes archived but includes inbox; bucket:'all' disables status filtering (local/reads.ts:179-190).

Gaps and partially wired

• StorageAdapter.semanticSearch throws NotImplementedError in both production adapters (lib/storage/local.ts:244-246; supabase.ts:133-135, both verified) even though the underlying embedding stores are fully built — hybrid search (C3) consumes lib/storage/local/embeddings.ts and lib/storage/supabase/knn.ts directly, including reaching into SupabaseAdapter.sb as a public field. The contract method is effectively dead.
• graph() throws everywhere — reserved for Phase 7 (graph view).
• subscribe is a no-op in both LocalAdapter and SupabaseAdapter (local.ts:315-321; supabase.ts:295-299): local live updates flow watcher → bus → SSE instead; SaaS has no real-time channel at all pending Supabase Realtime. Only Memory/JsonFile implement in-process channel subscription.
• Local mode has no attachments and no share links (local.ts:299-304 and share methods throw NotImplementedError).
• SaaS applyTemplate throws (Phase 6) — templates are local-only today (C8).
• JsonFileAdapter is deliberately partial: comments, attachments, shares, and diff throw; O(N) per operation with a documented ~1k-note ceiling (lib/storage/json-file.ts:43-78).
• Incremental indexing is not incremental: any single-file watcher event triggers a full-vault scanVault(prune:false) walk, cheap only because of hash-skip (lib/index/incremental.ts:35-42) — acknowledged in-source as a v1 tradeoff to optimize when chokidar fan-out becomes a bottleneck.
• notes.locked_by is a reserved column in the Postgres schema with no wiring.
• Cross-mode hash incompatibility: local vs SaaS content_hash schemes differ (see load-bearing details), so hashes cannot be used to compare or sync content across modes.
• recentEvents() ring buffer is dead to the SSE path: /api/events intentionally does not replay backlog on connect (replay caused router.refresh flurries that broke e2e), and the companion hooks/use-vault-events.ts hook is currently unmounted — see C9.
• No Supabase adapter-contract test run exists: tests/_helpers/pglite.ts docs reference a tests/adapter/supabase.spec.ts that is not in the tree; the contract suite runs only against Local/Memory/JsonFile (C9).
• CRON_SECRET is zod-optional (env.ts:98) — if a deployment forgets to set it, both cron endpoints permanently return 401 (fail-closed, but silently disables digests and trash pruning; C9).