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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user