PureXML/docs/rules/rules-swift/domain-first.md

110 lines
5.9 KiB
Markdown

# Domain First (defer the renderer)
**Status: MANDATORY for any app.** An app does not start with a UI framework. The
first decision is never "this is a SwiftUI app," "this is a UIKit app," or "this
is an AppKit app." That decision is made last, and under the pre-UI layer it need
not be made exclusively at all. The first work is the domain and the business
rules: the entities, their invariants, and the behavior that operates on them, all
framework-free and runnable with no display. The renderer is attached to that, not
the other way around.
## The anti-pattern
Naming the renderer first ("a SwiftUI app") inverts the dependency. It makes the
framework the root of the project and the domain a thing you reach through it, so
business rules end up scattered across view bodies, controllers, and callbacks,
welded to one SDK and untestable without a screen. Every later question (is this
correct, can I reuse this, can I ship it on macOS too) is then blocked behind the
UI you chose before you understood the problem. The renderer is the most
replaceable layer in the system; choosing it first spends your one
feels-irreversible decision on the one part that should have stayed cheap to
change.
## What to start with
The input to this is a clear definition of the business rules and the constraints
that bound them, which external REST services, what compliance, which auth model,
written down first (see `business-rules-and-constraints.md`). Then start with the
domain and the business rules, as the pre-UI layer's two value tiers and three
roles describe (see `ui/pre-ui-layer.md`): Domain (what the
entities are), Surface (display state over them), and the engine that runs every
business rule in response to an enumerable intent vocabulary, reaching I/O only
through injected seams. Build that, prove it headless, and you have an app whose
correctness is established before any pixel exists. The renderer is then a thin
adapter you add at the end.
## Defer the renderer, then pick by behavior
Because the model is renderer-agnostic, the SDK choice is deferred, and it is no
longer forced to be singular. You can develop the SwiftUI, AppKit, and UIKit
renderers over the one model and see which one actually fits a given scenario
better (its animation, accessibility, gesture handling, layout under load,
large-list performance), instead of committing to one on faith at the start. The
renderer becomes an experiment you run late and cheaply, not an assumption you
bake in early. See the renderer section of `ui/pre-ui-layer.md`: the triple render
is both the architecture's payoff and a comparison instrument, one model and
identical behavior underneath, so the framework is the only variable.
## Why this is now a must, not a preference
Two shifts move starting from a formalized domain from tidy to mandatory.
First, the cost of building several renderers has collapsed. Machine
pattern-matching at scale now makes it practical to develop all three Apple UIs
over one model and compare them, work that was too expensive to justify when each
renderer was hand-written from scratch. The deferred, plural renderer choice this
rule asks for is now affordable.
Second, and deeper: that same capability has made tractable, in hours, work that
was prohibitive before. Discovering the latent grammar in a
corpus, naming the possible language it implies, and devising a parser or compiler
for it is now feasible on a timescale that did not exist a few years ago. That
capability rewards a domain already written down as explicit, value-typed,
rule-governed structure, and is nearly blind to one that lives only as scattered
imperative code. A formalized domain (typed entities, named invariants made
unrepresentable or validated as values, an enumerable intent vocabulary,
round-trip laws for every transform) is exactly the structure these tools can
read, check, extend, and translate. So formalizing the domain rules is no longer
optional discipline. In this world it is a must.
## DO
- Begin every app at the domain and the business rules, framework-free and
headless-provable, before naming any renderer.
- Write the domain down as explicit structure: typed entities, invariants made
unrepresentable or validated as values (`validation-rules.md`), an enumerable
intent vocabulary (`ui/pre-ui-layer.md`).
- Treat the renderer as a late, reversible, and plural choice: develop more than
one and pick by observed behavior.
## DON'T
- Do not open a project by declaring its UI framework ("this is a SwiftUI app");
the framework is the last decision, not the first.
- Do not put business rules in a view, a controller, or a callback; they belong in
the framework-free domain and engine.
- Do not leave the domain implicit in imperative code on the promise of formalizing
it later; formalize it now.
## Acceptance check
A conforming project has: (1) a framework-free domain and engine that build and
pass tests with no UI target present; (2) no business rule reachable only through a
renderer; (3) the renderer named as a late, swappable boundary (one or more),
never as the project's root; and (4) the domain expressed as explicit typed
structure with named, checked invariants, not as imperative code that only a
screen exercises. A project whose first and load-bearing decision is its UI
framework, or whose business rules cannot run without a display, fails this rule.
## Companion rules
- `ui/pre-ui-layer.md`: the two value tiers and three roles this rule starts from;
the triple render as payoff and comparison instrument.
- `validation-rules.md`: invariants as composable values; every public type
validated or excluded with a reason.
- `dependency-injection.md`: inject every collaborator, no singletons, so the
domain stays liftable and testable.
- `parsing-rules.md`, `core/round-trip-transformation.md`, `core/proof-discipline.md`:
formalizing structure, transforms, and translation claims, the discipline a
formalized domain makes possible.