From e003c10e944fdf215398a37e445e5f4a934897c2 Mon Sep 17 00:00:00 2001
From: Mateusz Kwasniewski <kwasniewski.mateusz@gmail.com>
Date: Fri, 11 Apr 2025 14:49:51 +0200
Subject: [PATCH] docs: ADR correct type dependencies (#9749)

---
 website/docs/contributing/ADRs/ADRs.md        |  1 +
 .../back-end/correct-type-dependencies.md     | 38 +++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 website/docs/contributing/ADRs/back-end/correct-type-dependencies.md

diff --git a/website/docs/contributing/ADRs/ADRs.md b/website/docs/contributing/ADRs/ADRs.md
index 45ef4c0780..b2d53588e5 100644
--- a/website/docs/contributing/ADRs/ADRs.md
+++ b/website/docs/contributing/ADRs/ADRs.md
@@ -29,6 +29,7 @@ We are in the process of defining ADRs for the back end. At the time of writing
 * [Specificity in database column references](./back-end/specificity-db-columns.md)
 * [Write model vs Read models](./back-end/write-model-vs-read-models.md)
 * [Frontend API Design](./back-end/frontend-api-design.md)
+* [Correct type dependencies](./back-end/correct-type-dependencies.md)
 
 ## Front-end ADRs
 
diff --git a/website/docs/contributing/ADRs/back-end/correct-type-dependencies.md b/website/docs/contributing/ADRs/back-end/correct-type-dependencies.md
new file mode 100644
index 0000000000..1e03f088ff
--- /dev/null
+++ b/website/docs/contributing/ADRs/back-end/correct-type-dependencies.md
@@ -0,0 +1,38 @@
+---
+title: "ADR: Domain Code Must Not Depend on Infrastructure Types (e.g., OpenAPI)"
+---
+
+## Background
+
+We’ve identified an architectural issue in our backend code: domain-layer code (especially store interfaces) sometimes directly references infrastructure-layer types, such as OpenAPI schemas.
+This breaks a foundational principle of layered architecture: "Domain code should not depend on infrastructure, but infrastructure can depend on domain."
+
+## Decision
+
+All domain code—including store interfaces and business logic—must operate on domain types, not infrastructure types such as OpenAPI schemas.
+Any mapping between API types and domain types must occur at the boundary (e.g., in controllers), not in the core logic.
+
+## Consequences
+
+* Clear architectural boundaries: Domain is isolated from infrastructure concerns like transport and serialization.
+* Improved modularity: Domain logic can move between OSS and Enterprise without dragging along OpenAPI types or other infrastructure.
+* Greater flexibility: We can evolve domain types rapidly and experimentally without worrying about breaking public API contracts.
+* Increased mapping boilerplate: Conversion logic between domain and infrastructure types must be written explicitly at the boundaries.
+
+## Example
+
+Before 
+```typescript
+store.createUser(user: CreateUserSchema): Promise<void>;
+```
+
+After 
+```typescript
+// Domain-layer store uses a domain type
+store.createUser(user: DomainUser): Promise<void>;
+
+// API-layer controller maps OpenAPI to domain
+const domainUser = mapFromApiType(apiUser);
+await store.createUser(domainUser);
+```
+