view models

docs/architecture/FORM_SUBMISSION.md

@@ -0,0 +1,156 @@
+Form Submission Flow (UI → System)
+
+This document defines the only valid data flow when a user submits a form.
+It applies to all write operations (create, update, delete).
+
+There are no exceptions.
+
+⸻
+
+Core Principle
+
+Read and Write paths are different.
+
+What is displayed is never sent back.
+
+⸻
+
+High-Level Flow
+
+UI → Command DTO → API → Core Use Case → Persistence
+
+	•	View Models are read-only
+	•	Display Objects are read-only
+	•	Commands are write-only
+
+⸻
+
+1. UI (Component)
+
+Responsibility
+	•	Collect user input
+	•	Manage UX state (loading, disabled, local errors)
+
+Rules
+	•	Only primitives are handled (string, number, boolean)
+	•	No DTO reuse
+	•	No ViewModel reuse
+	•	No domain objects
+
+The UI does not decide whether an action is allowed.
+
+⸻
+
+2. Form Model (Optional)
+
+Responsibility
+	•	Local form state
+	•	Client-side validation (required, min/max length)
+	•	Field-level errors
+
+Rules
+	•	UX-only validation
+	•	No business rules
+	•	Never shared with API or Core
+
+⸻
+
+3. Command DTO (Frontend)
+
+Responsibility
+	•	Express intent
+	•	Represent a write operation
+
+Rules
+	•	Created fresh on submit
+	•	Never derived from a ViewModel
+	•	Never reused from read DTOs
+	•	Write-only
+
+⸻
+
+4. Frontend Service
+
+Responsibility
+	•	Orchestrate the write action
+	•	Call the API Client
+	•	Propagate success or failure
+
+Rules
+	•	No business logic
+	•	No validation
+	•	No UI decisions
+	•	No ViewModel creation for writes (except explicit success summaries)
+
+⸻
+
+5. API Client (Frontend)
+
+Responsibility
+	•	Perform HTTP request
+	•	Handle transport-level failures
+
+Rules
+	•	Stateless
+	•	No retries unless explicitly designed
+	•	Throws technical errors only
+
+⸻
+
+6. API Layer (Backend)
+
+Responsibility
+	•	HTTP boundary
+	•	Transport validation (schema / class-validator)
+	•	Map API DTO → Core Command
+
+Rules
+	•	No business logic
+	•	No persistence
+	•	No UI concerns
+
+⸻
+
+7. Core Use Case
+
+Responsibility
+	•	Enforce business rules
+	•	Validate domain invariants
+	•	Change system state
+
+Rules
+	•	Single source of truth
+	•	No UI logic
+	•	No HTTP knowledge
+
+⸻
+
+Response Handling
+
+Success
+	•	API returns a Result DTO (IDs, status)
+	•	Frontend reacts by:
+	•	navigation
+	•	reload via GET
+	•	toast / confirmation
+
+Failure
+	•	Business errors → user-visible message
+	•	Technical errors → error boundary / monitoring
+
+⸻
+
+Forbidden Patterns
+	•	ViewModel → Command
+	•	DisplayObject → API
+	•	DTO roundtrip
+	•	Domain Object in UI
+	•	Reusing read models for writes
+
+⸻
+
+Summary
+	•	Read Flow: DTO → ViewModel → UI
+	•	Write Flow: UI → Command DTO → Core
+
+What is shown is never sent back.