[ADR] Api - State providers structure

adr/2024_07_15_api_state_providers_structure.md

@@ -0,0 +1,95 @@
+# API - State Providers Structure
+
+* Status: Accepted
+* Date: 2024-07-15
+
+In effect from version: 2.0
+
+Related PRs: #16543
+
+## Context and Problem Statement
+
+Until version 2.0, we supported API Platform version 2, which utilized
+`DataProviders` to deliver data to the API. These `DataProviders` were all
+located within the `Sylius\Bundle\ApiBundle\DataProvider` directory.
+This structure lacked differentiation between the admin and shop sections
+and did not provide clear organization for individual resources. 
+As a result, it became challenging to manage and maintain the codebase
+as the number of providers grew.
+
+With Sylius 2.0, the API Platform has been upgraded to version 3.0.
+One of the significant changes in API Platform 3.0 is the shift from 
+`DataProviders` to `StateProviders`. This change necessitates a 
+reconsideration of how we organize and structure our data-providing
+classes to ensure clarity, maintainability, and scalability.
+
+## Decision Drivers
+
+* Moving from DataProviders to StateProviders
+* Clear separation between admin and shop providers
+* Clear separation between resources
+
+## Considered Options
+
+### Leave all StateProviders in one directory
+
+* **Good, because:**
+    * Less to refactor
+* **Bad, because:**
+    * Hard to see which provider is for admin and which for shop
+
+### Separate StateProviders by resource
+
+* **Good, because:**
+    * Clear separation between resources
+* **Bad, because:**
+    * Need to refactor all providers
+    * Hard to see which provider is for admin and which for shop
+
+### Separate StateProviders by sections
+
+* **Good, because:**
+    * Clear separation between admin and shop providers
+* **Bad, because:**
+    * Need to refactor all providers
+    * A lot of providers in one directory
+
+### Separate StateProviders by sections and resources
+
+* **Good, because:**
+    * Clear separation between admin and shop providers
+    * Clear separation between resources
+* **Bad, because:**
+    * Need to refactor all providers
+
+## Decision Outcome
+
+Chosen option: `Separate StateProviders by sections and resources`,
+because it provides a clear and manageable way to customize form types
+for different contexts.
+
+New Structure:
+
+```
+/StateProvider
+    /Admin
+        /Order
+            ItemProvider.php
+        /Product
+            ItemProvider.php
+            CollectionProvider.php
+    /Shop
+        /Order
+            ItemProvider.php
+            CollectionProvider.php
+        /Product
+            CollectionProvider.php
+    /Common
+        /Adjustment
+            CollectionProvider.php
+```
+
+Providers for Command classes should be placed in the relevant resource
+directory and named with a `Provider` suffix,
+e.g., `/StateProvider/Shop/ShopUser/ResetPasswordProvider.php` for the
+`ResetPassword` command.