ADR-001-Hybrid-Transport-Layer

ADR 001: Hybrid Transport Layer (API with FS Fallback)

Date: 2026-03-31
Status: Accepted

Context:
The core ethos of pour is killing friction. Relying solely on the Obsidian Local REST API means data entry fails if the Obsidian Electron client is closed. Relying solely on the filesystem means missing out on advanced API features when the vault is open.

Decision:
Implement a dual-pronged Transport dispatcher.

  1. Attempt an HTTP connection to the Local REST API first using reqwest with a 5-second timeout.
  2. If the connection is refused, automatically fall back to direct filesystem writes via std::fs.

Consequences:

  • Positive: Maximum resilience. The user never loses a log entry due to application state.
  • Negative: Feature asymmetry. The API backend returns raw filenames (for example, latte.md) while the FS backend returns file stems (latte). This requires normalization in The-3-Tier-Data-Fallback.

See also System-Architecture-Overview, pour-design-spec, and sprint-2-transport-report.