Skip to content

Commit 716209f

Browse files
Docs: Move the architecture guide to the root and split out the decision log
The repo had two files called ARCHITECTURE.md. The root one, an untracked Architecture Vision file excluded via .git/info/exclude, was last touched on 26 July and described the tiered Packages/ layout that the consolidation replaced. The tracked docs/ARCHITECTURE.md was the maintained one. Reading the stale file while I edited the other is what surfaced this. The guide now sits at the root, where a newcomer looks alongside README and CONTRIBUTING, and is tracked normally with the exclude entry removed. Three sections were merged from the vision file first, each verified against the code: the design principles (point 8 rewritten, since it described the retired Packages/ tiers), state ownership (reworded to stop overloading the word service, because git status, tasks and LSP sessions live in feature targets rather than service targets), and the rejected-options list. Two claims in that list were wrong and are corrected. The @observable entry justified itself with a macOS 13 minimum, but the declared target is 14 in both the pbxproj and the manifest, so the blocker is team agreement rather than code. The Combine entry claimed the EventBus could swap to AsyncStream without touching call sites; subscribe(_:) returns AnyPublisher and all five subscribers use sink and AnyCancellable, so it would rewrite every one. The guide dropped from 557 to 435 lines by moving decision records to docs/architecture-decisions.md: the four target-separation rulings, what the I/O norm prevents, the panel seam detail, the Core charter evidence, and the singletons inventory. What stayed is the rule plus its reasoning. Panel contributions shrank from 41 lines to the reusable pattern, since it is the first of several seams and logging each in full would bloat the guide. Folder conventions lost its per-target history, which is the only content deleted rather than moved: 170 words. Also removes the em dash separator from CONTRIBUTING.md prose, per the writing style rule.
1 parent 85256b8 commit 716209f

4 files changed

Lines changed: 236 additions & 161 deletions

File tree

0 commit comments

Comments
 (0)