Models separation of concerns

docs/architecture/adr/0008-server-CQRS-pattern.md

@@ -70,7 +70,7 @@ removed over time.
 
 ## Further reading
 
-- [Server Architecture](../server/index.md) - Practical guide on implementing CQS in the server
-  codebase
+- [Command Query Separation](../server/command-query-separation.md) - Practical guide on
+  implementing CQS in the server codebase
 - [Martin Fowler on CQS](https://martinfowler.com/bliki/CommandQuerySeparation.html) - High-level
   summary of the CQS principle

docs/architecture/server/_category_.yml

@@ -0,0 +1,2 @@
+label: "Server Architecture"
+position: 6

docs/architecture/server/index.md → docs/architecture/server/command-query-separation.md

@@ -1,10 +1,8 @@
 ---
-sidebar_position: 6
+sidebar_position: 1
 ---
 
-# Server Architecture
-
-## Command Query Separation (CQS)
+# Command Query Separation (CQS)
 
 Our server architecture uses the Command Query Separation (CQS) pattern.
 

docs/architecture/server/models-separation-of-concerns.md

@@ -0,0 +1,38 @@
+---
+sidebar_position: 2
+---
+
+# Models separation of concerns
+
+To maintain clean architecture and separation of concerns, **API contracts** (request/response
+models) must be kept separate from **data models**. This separation allows:
+
+- **API contracts to evolve independently** from internal data structures
+- **Versioning of APIs** without affecting internal business logic
+- **Validation and serialization** specific to API layer
+
+### Model Types and Their Purposes
+
+#### Request Models (`*RequestModel`)
+
+- Define the shape of data received from API clients
+- Handle data validation (e.g., `[Required]`, `[StringLength]`)
+- Convert to data models via `ToData()` methods
+
+#### Response Models (`*ResponseModel`)
+
+- Define the shape of data sent to API clients
+- Construct from data models via constructors or factory methods
+- Handle API-specific formatting and structure
+
+#### Data Models
+
+- Internal representation used by business logic
+- Handle domain logic and transformations
+- Should be clearly distinguishable from API models
+
+### Guidelines
+
+1. **Never expose data models directly in API endpoints**
+2. **Provide conversion methods**
+3. **Keep validation at the API layer**