diff --git a/docs/architecture/adr/0008-server-CQRS-pattern.md b/docs/architecture/adr/0008-server-CQRS-pattern.md index 69dceb6e5..b4b69264c 100644 --- a/docs/architecture/adr/0008-server-CQRS-pattern.md +++ b/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 diff --git a/docs/architecture/server/_category_.yml b/docs/architecture/server/_category_.yml new file mode 100644 index 000000000..f13944ff1 --- /dev/null +++ b/docs/architecture/server/_category_.yml @@ -0,0 +1,2 @@ +label: "Server Architecture" +position: 6 diff --git a/docs/architecture/server/index.md b/docs/architecture/server/command-query-separation.md similarity index 98% rename from docs/architecture/server/index.md rename to docs/architecture/server/command-query-separation.md index d885a16c3..85b2438ea 100644 --- a/docs/architecture/server/index.md +++ b/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. diff --git a/docs/architecture/server/models-separation-of-concerns.md b/docs/architecture/server/models-separation-of-concerns.md new file mode 100644 index 000000000..8086c2a21 --- /dev/null +++ b/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**