Overview

Data flow documents trace a single operation end-to-end through the Clean Architecture layers, showing exactly which crates, types, and functions participate and in what order. Each document covers one major pipeline.

How to Read These

Each data flow document follows the same structure:

1. Sequence or flow diagram showing the components involved and message ordering
2. Step-by-step walkthrough of the operation through each layer
3. Key types and functions referenced at each boundary crossing
4. Error and edge-case handling where relevant

The diagrams trace real code paths — component names map directly to Rust structs, use cases, and repository methods.

Data Flow Index

Flow	Starting Point	Ending Point	Key Layers
Write Path	Editor keystroke	SQLite + side effects	Framework, Application, Infrastructure
Search	User query string	Ranked result list	Application (SearchRouter), Infrastructure (FTS5, ONNX)
Embedding	Page save event	Stored vector in page_embeddings	Infrastructure (EmbeddingManager, ONNX Runtime)
Import	External markdown folder	Created pages + converted links	Framework, Application, Infrastructure
Sync	Local edit or remote change	Merged state on both sides	Application (SyncEngine), Infrastructure (Supabase)
Authentication	Sign-in action	Persisted session + capability resolution	Framework, Infrastructure (Supabase Auth)

Common Patterns

Several patterns recur across data flows:

• WriteEffectCoordinator — After any mutation, side effects (event log, embedding queue, analytics) fire as best-effort, never blocking the primary write. See Write Path for the canonical example.
• Trait boundary crossing — Application use cases depend on repository traits; infrastructure provides the concrete implementation. This boundary appears in every flow at the Application-to-Infrastructure transition.
• CRDT binary pass-through — Content flows as opaque Vec<u8> (LoroDoc snapshot) through every layer. Only the editor and the CRDT library deserialize it. Materialized text is a derived projection for FTS indexing.
• Error sanitization — Technical errors from infrastructure are converted to user-facing messages at the Commands layer boundary via UserFacingError and sanitize_error. Internal details never reach the frontend.