docs(architecture): comprehensive architecture record #692

Merged

raisondetredev merged 1 commit from refs/pull/692/head into main

2026-06-26 02:27:48 +02:00

raisondetredev commented

2026-06-26 01:14:21 +02:00

(Migrated from codeberg.org)

Adds docs/architecture/ — a comprehensive architecture record explaining how the app and the wider four-repo system are built and why.

Overview + 10 chapters: system overview · app layering & DI · bootstrap & the account-keyed dependency graph · persistence & the offline-first sync engine (the centrepiece) · routing · the editor · reference data & edge services · FSRS study · security · testing.
10 ADRs for the load-bearing decisions (offline-first, last-write-wins, account-keyed subtree, AccountManager, reference-data-on-server, Edge-Functions-for-secrets, FSRS, multi-repo split, Drift, BLoC).
README pointer.

Grounded in the real code (main.dart bootstrap, FlashcardSyncService, the Drift schema, the router, the editor). The source already carries thorough local rationale; this is the global layer. Docs only — no code change.

Part of a 3-repo documentation pass — infra project-halkyon/halkyon-infra#67, curator project-halkyon/halkyon-curator#20.

Adds **`docs/architecture/`** — a comprehensive architecture record explaining how the app and the wider four-repo system are built and **why**. - **Overview** + **10 chapters**: system overview · app layering & DI · bootstrap & the account-keyed dependency graph · **persistence & the offline-first sync engine** (the centrepiece) · routing · the editor · reference data & edge services · FSRS study · security · testing. - **10 ADRs** for the load-bearing decisions (offline-first, last-write-wins, account-keyed subtree, AccountManager, reference-data-on-server, Edge-Functions-for-secrets, FSRS, multi-repo split, Drift, BLoC). - README pointer. Grounded in the real code (main.dart bootstrap, `FlashcardSyncService`, the Drift schema, the router, the editor). The source already carries thorough *local* rationale; this is the *global* layer. Docs only — no code change. Part of a 3-repo documentation pass — infra project-halkyon/halkyon-infra#67, curator project-halkyon/halkyon-curator#20.