Design Decisions

Design decisions

An architecture decision record (ADR) is a short document about one important choice. It records the problem, the options, what was chosen, and what follows from it. Anything hard to reverse gets an ADR before the code.

The full list, and the steps to add one, are in the ADR index.

Decisions so far

There are 42 decision records. The titles and statuses below are read from the files on the beta branch.

ADR	Decision	Status
0001	App stack	Accepted, pending the owner's camera check in record 0004
0002	License	Accepted
0003	TypeScript version	Accepted
0004	Ink latency	Accepted, pending the owner's camera check and budget review
0005	Text containers on a freeform page	Accepted, pending the owner's review of the typing budget
0006	PDF export	Accepted
0007	Audio capture	Accepted
0008	Note file format	Proposed
0010	Interface components, state, and structure	Proposed
0011	Self-updater and where the app lives	Proposed
0012	Keep the native window frame for now	Accepted
0013	Settings and device state storage	Proposed
0014	Notes service contract between the shell and storage	Proposed, to be accepted jointly by the Phase 2 and Phase 3 owners
0015	App lifecycle: single instance, start-up order, and exit handshake	Proposed
0016	Phase 2 test stack and CI gates	Proposed
0017	Custom window frame and title bar	Proposed, pending the manual checks below. The shell.customFrame and window.snapLayouts flags stay off until they pass.
0020	The typed notes editor	Proposed. The 20-page note types within 16 ms on the Surface Laptop Studio 2 (docs/perf/phase-4.md); the reference laptop run, the outline, and the owner's approval remain
0021	Code highlighting with lowlight, not CodeMirror 6	Proposed, pending the owner's approval of the change to DEVELOPMENT.md section 2
0022	The page viewport: native scrolling, app touch panning, and the camera	Proposed, pending spike S5 on real touch hardware. The typing and frame numbers are re-measured in docs/perf/phase-4.md
0023	Spell check and read aloud through Windows services	Proposed. Spike S2 passed in Edge 154; spike S1 waits for a run with NVDA and Narrator
0024	The keyboard model for typed notes	Proposed, pending the owner's confirmation of the OneNote set's editor keys
0025	Paste, clipboard facts, and image import	Proposed, pending real captures for spike S4. Spike S3 is done: display-size renditions are not built (docs/perf/images.md)
0026	Layout rules for text boxes and reading order	Proposed, pending the Phase 3 owner's agreement to P3-1 and P3-11
0027	Palm rejection by evidence, with managed touch and retractable ink	Accepted
0030	Connector sign-in and token storage	Proposed, pending a sign-in with real client IDs for each service
0035	Share as a file is a ZIP of Markdown, optionally locked	Accepted
0036	Object groups	Proposed
0037	Ink layers	Proposed
0038	iCloud stays folder-based, with no iCloud sign-in	Accepted
0040	PDF files are read by pdf.js in the webview	Proposed
0041	Stamped entry lock lives in the page view, and the core enforces it	Proposed
0042	Protected sections are sealed file by file, and open only in memory	Proposed
0046	One command registry for the local API, the opennote command, and MCP	Accepted
0047	Typed #words become page tags	Proposed
0048	Choice columns keep their options in the column schema and their values as plain text	Proposed
0049	Optional end-to-end-encrypted sync over storage people already have	Proposed
0050	The tutor gives graded hints from what the person shows it, on this device unless they agree to more	Proposed
0051	Check my work checks each step on the device, and says "I could not check this step" before "wrong"	Proposed
0052	Practice exams are made on the device, taken in a tool window, and saved as ordinary pages	Proposed
0053	Import from Goodnotes, Notability, and Samsung Notes reads what the packages show, and the PDF export is the dependable route	Proposed
0054	LaTeX export writes escaped text, checked math, and typeset code, and never compiles	Proposed
0055	macOS and Linux builds degrade feature by feature and say what they lack	Proposed

ADR 0000 is the template. The numbers skip some values, such as 0009. Decisions are proposed on the phase branches and listed here once they merge.

Statuses

Status	Meaning
Proposed	Written and open for discussion, but not yet binding
Accepted	Agreed, and the code should follow it
Superseded	Replaced by a later ADR, which the status line links to

Accepted records aren't rewritten when plans change. A new ADR replaces the old one, and the old status changes to "Superseded by ADR NNNN". Numbers are never reused.

Add a decision

1. Copy the template to a new file with the next free number.
2. Fill in each section. One or two pages is enough.
3. Set the status to Proposed, and open a pull request with the ADR and no code.
4. Before it merges, set the status to Accepted, and add it to the index.

See Development process and Phase 1 spike results, which covers ADRs 0004 to 0007.