docs(v0.1): cross-link technical doc to ADRs and qfd

Adds a companion-docs header and inline ADR jumps on every load-bearing
choice (ADR-001 runtime, ADR-002 UI, ADR-004 git kill-switch, ADR-006
concurrency, ADR-007 storage, ADR-009 USB-host gate). Render module
also points at qfd §3 to anchor "why these functions rank top."
This commit is contained in:
Julien Calixte
2026-05-14 12:50:12 +02:00
parent 2a2c268010
commit 90e98d2375

View File

@@ -2,12 +2,20 @@
> Scope: ships the product surface in [`v0.1-mvp-product.md`](v0.1-mvp-product.md).
> No more, no less.
>
> Decisions referenced inline point at [`adr.md`](adr.md). Tradeoff weights
> and the critical-performance budget live in [`qfd.md`](qfd.md). Project
> overview: [`../README.md`](../README.md). Release sequence:
> [`roadmap.md`](roadmap.md).
## Architecture
Single Rust binary on `esp-idf-rs` (std). Two cores, several threads, one
shared editor state behind a mutex. Wi-Fi and git work happens off the input
thread so the typing path is never blocked by I/O.
Single Rust binary on `esp-idf-rs` (std)
[ADR-001](adr.md#adr-001-language-and-runtime--rust-on-esp-idf-rs-std).
Two cores, several threads, one shared editor state behind a mutex
([ADR-006](adr.md#adr-006-concurrency--stdthread--channels-no-async-runtime)).
Wi-Fi and git work happens off the input thread so the typing path is never
blocked by I/O.
```
┌──────────────────────────────────────────┐
@@ -71,6 +79,10 @@ Target boot time: ≤ 5 s to cursor (v0.1). The 3 s target is v1.0.
We do **not** try to build the whole stack and turn it on. Each spike below
is a small program that proves one risk before we commit to the next layer.
Spike 7 is the kill-switch for
[ADR-004 (gitoxide)](adr.md#adr-004-git-implementation--gitoxide-gix);
spike 4 is the gate for
[ADR-009 (USB host)](adr.md#adr-009-keyboard-transport--usb-host-tinyusb).
1. **Spike 1 — Blink.** Confirm toolchain, flash, and basic GPIO.
2. **Spike 2 — EPD.** Drive the GDEY0579T93 (via DESPI-c579 breakout) over
@@ -119,6 +131,11 @@ Anything else is ignored in v0.1.
### `render` — dirty-rect to EPD
Custom widget layer on `embedded-graphics`
[ADR-002](adr.md#adr-002-ui-strategy--custom-widgets-on-embedded-graphics-not-ratatui).
Owns the top-ranked engineering functions (latency, refresh-region area)
in [qfd.md §3](qfd.md#3-house-of-quality--whats--hows).
- A render request is a `RenderOp { Lines(range) | Status(text) | FullRefresh }`.
- The render thread maintains a shadow of the current screen contents per
region (header / edit area lines / status).
@@ -131,6 +148,9 @@ Anything else is ignored in v0.1.
### `persistence` — SD I/O
Storage split rationale:
[ADR-007](adr.md#adr-007-storage-split--fat-on-sd-for-working-copy-littlefs-on-flash-for-config).
- Atomic save: write to `notes.md.tmp`, fsync, rename. We accept FAT's
weakness here; on power loss between rename and dir flush, the user gets
the previous version, which is the documented behavior.
@@ -149,6 +169,12 @@ Anything else is ignored in v0.1.
### `git` — commit + push
`gitoxide` choice and kill-switch:
[ADR-004](adr.md#adr-004-git-implementation--gitoxide-gix).
Auth model: [ADR-005](adr.md#adr-005-auth--https--github-personal-access-token).
PSRAM heap during push is a top-3 watched metric — see
[qfd.md §6](qfd.md#6-critical-performance-budget).
- `gix` with the smart-HTTP transport backed by `esp-idf` mbedtls (via a
custom transport impl, or `gix-transport` with `reqwest`+`rustls-mbedtls`
if that path is cleaner — decided in spike 7).
@@ -187,6 +213,9 @@ for SPI buffers).
## Concurrency model
Rationale and rejected alternatives:
[ADR-006](adr.md#adr-006-concurrency--stdthread--channels-no-async-runtime).
- Editor state behind a single `Mutex`. Holders: `ui_task` (writer),
`render_task` (reader, snapshot then unlock), `git_task` (reader for save).
- No `await` / no async runtime — std threads only. Simpler debugging on