setup

docs/architecture/DISPLAY_OBJECTS.md

@@ -0,0 +1,82 @@
+# Display Objects
+
+## Definition
+
+A **Display Object** encapsulates **reusable, UI-only display logic**.
+
+It answers the question:
+
+> “How should this specific piece of information be shown?”
+
+Display Objects are **not screen-specific**.
+They exist to avoid duplicating presentation logic across View Models.
+
+---
+
+## Responsibilities
+
+A Display Object MAY:
+
+- format values (money, dates, durations)
+- handle localization and language-specific rules
+- map codes to labels
+- encapsulate UI display conventions
+- be reused across multiple View Models
+
+A Display Object MUST:
+
+- be deterministic
+- be side-effect free
+- operate only on presentation data
+
+---
+
+## Restrictions
+
+A Display Object MUST NOT:
+
+- contain business logic
+- enforce domain invariants
+- perform validation
+- influence system behavior
+- be sent back to the server
+- depend on backend or infrastructure concerns
+
+If a rule affects system correctness or persistence,
+it does not belong in a Display Object.
+
+---
+
+## Ownership & Placement
+
+- Display Objects belong to the **presentation layer**
+- They are frontend-only
+- They are not shared with the backend or core
+
+---
+
+## Relationship to View Models
+
+- View Models MAY use Display Objects
+- Display Objects MUST NOT depend on View Models
+- Display Objects represent **parts**
+- View Models represent **screens**
+
+---
+
+## Testing
+
+Display Objects SHOULD be tested because they often contain:
+
+- locale-specific behavior
+- formatting rules
+- edge cases visible to users
+
+---
+
+## Summary
+
+- Display Objects encapsulate **how something looks**
+- View Models encapsulate **what a screen needs**
+- Both are presentation concerns
+- Neither contains business truth