wip repository docs

Author: madsrasmussen

17/umbraco-cms/.gitbook/assets/data-flow.svg

@@ -55,3 +55,6 @@ After fetching data, the next step is to execute the request. You can use the `t
 ### [Custom Generated Client](custom-generated-client.md)
 
 For advanced scenarios, you can generate a custom client for your API using tools like [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts). This approach is ideal when working with custom API controllers or when you need type-safe, reusable client code.
+
+### [Repositories](../repositories/README.md)
+Repositories provide a structured way to manage data operations in the Backoffice. They abstract the data access layer, allowing for easier maintenance and scalability.

17/umbraco-cms/customizing/foundation/fetching-data/README.md

@@ -0,0 +1,87 @@
+# Repositories
+Repositories provide a structured way to manage data operations in the Backoffice. They abstract the data access layer, allowing for easier reuse and scalability.
+
+Repositories create separation between domain logic and data access. By providing a known interface for data requests, we can reuse UI components across different domains. For example, we have a generic UX flow for deleting an entity. By supplying this flow with a repository that has a known interface for deletion, we can use the same UX flow to delete any entity.
+
+Additionally repositories can utilize different data sources depending on the application's state. These sources may include:
+
+* A REST API
+* Offline storage
+* A local cache
+* Etc.
+
+This abstraction ensures that consumers don’t need to worry about how to access data. The repository serves as the Backoffice’s entry point for requesting new data. As a result, we achieve a loosely coupled connection between consumers and data storage procedures, effectively hiding complex implementations.
+
+**Repository:** defines what data operations are available (get, add, update, delete).
+**Data Source:** defines how data is actually fetched or stored.
+
+### Data flow with a repository <a href="#data-flow-with-a-repository" id="data-flow-with-a-repository"></a>
+
+A repository must be instantiated where it is used. It should take an [UmbController](../../umbraco-controller/README.md) as part of the constructor. This ensures that any contexts consumed in the repository, like notifications or modals, are rendered in the correct context.
+
+A repository can be initialized directly from an element, but will often be instantiated in a [context](../../context-api/README.md), like the Workspace Context.
+
+```text
+Element → (Context) → Repository → Data Source(s)
+```
+
+### Using an existing Repository <a href="#using-a-repository" id="using-a-repository"></a>
+
+Often, you will find that data is already available and observable in a [context](./contexts/README.md), such as the Workspace Context. In that case, subscribing to the context [state](./states.md) will be the right approach to take. This way, you will receive all runtime updates that occur to the data throughout the session.
+
+When a context with the appropriate data state is not available, reaching for a repository will ensure access to the needed information no matter the current application state.
+
+```typescript
+import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
+import { LitElement} from '@umbraco-cms/backoffice/external/lit';
+import {UmbDocumentDetailRepository} from '@umbraco-cms/backoffice/document';
+
+class MyElement extends UmbElementMixin(LitElement) {
+  ...
+  #documentRepository = new UmbDocumentDetailRepository(this);
+
+  firstUpdated() {
+    const { data, error } = await this.#documentRepository.requestByUnique('some-unique-key');
+    console.log('The Document Data:', data);
+  }
+  ...
+}
+
+const documentRepository = new UmbDocumentDetailRepository(this);
+
+```
+
+### Register a custom Repository <a href="#register-a-custom-repository" id="register-a-custom-repository"></a>
+
+By registering your repository in the [Extension Registry](../../extension-registry/README.md) you make it available to use in different extension kinds that requires a repository alias.
+
+Some of the common repository interfaces are:
+* [UmbDetailRepository](./repository-types/detail-repository.md) - for detail views of a single entity.
+* [UmbCollectionRepository](./repository-types/collection-repository.md) - for collection views of multiple entities.
+* [UmbTreeRepository](./repository-types/tree-repository.md) - for tree structures of entities.
+* [UmbItemRepository](./repository-types/item-repository.md) - for item requests.
+
+See the example below of how to register a custom repository:
+
+```typescript
+import { umbExtensionsRegistry } from "@umbraco-cms/backoffice/extension-registry";
+
+interface MyEntityDetailModel {
+  unique: string;
+  entityType: string;
+}
+
+class MyEntityDetailRepository implements UmbDetailRepository<MyEntityDetailModel> {
+  // Implement repository methods here
+}
+
+const repositoryManifest = {
+  type: "repository",
+  alias: "My.Repository.EntityDetail",
+  name: "My Entity Detail Repository",
+  api: MyRepository,
+};
+
+umbExtensionsRegistry.register(repositoryManifest);
+```
+

17/umbraco-cms/customizing/foundation/repositories.md

@@ -0,0 +1,11 @@
+# Collection Repository
+
+A collection repository is a specific type of repository designed to handle operations related to collections of items. It provides methods to request collections of data in a filtered and paginated manner.
+
+The interface below is simplified for clarity and omits return types and arguments. See full interfaces in the [UI API Documentation](https://apidocs.umbraco.com/v17/ui-api/interfaces/packages_core_collection.UmbCollectionRepository.html)
+
+```typescript
+interface UmbCollectionRepository {
+  requestCollection();
+}
+```

17/umbraco-cms/customizing/foundation/repositories/README.md

@@ -0,0 +1,15 @@
+# Detail Repository
+
+A detail repository is a specific type of repository designed to handle operations related to individual entities. It provides methods to create, retrieve, update, and delete single entities.
+
+The interface below is simplified for clarity and omits return types and arguments. See full interfaces in the [UI API Documentation](https://apidocs.umbraco.com/v17/ui-api/interfaces/packages_core_repository.UmbDetailRepository.html)
+
+```typescript
+interface UmbDetailRepository {
+  createScaffold();
+  create();
+  requestByUnique();
+  save();
+  delete();
+}
+```

17/umbraco-cms/customizing/foundation/repositories/repository-types/collection-repository.md

@@ -0,0 +1,11 @@
+# Item Repository
+
+An item repository is a specific type of repository designed to handle operations related to multiple individual items. It provides methods to request multiple items based on unique identifiers.
+
+The interface below is simplified for clarity and omits return types and arguments. See full interfaces in the [UI API Documentation](https://apidocs.umbraco.com/v17/ui-api/interfaces/packages_core_repository.UmbItemRepository.html)
+
+```typescript
+interface UmbItemRepository {
+  requestItems();
+}
+```

17/umbraco-cms/customizing/foundation/repositories/repository-types/detail-repository.md

@@ -0,0 +1,14 @@
+# Tree Repository
+
+A tree repository is a specific type of repository designed to handle operations related to tree data structures. It provides methods to request tree roots, tree items, and their ancestors.
+
+The interface below is simplified for clarity and omits return types and arguments. See full interfaces in the [UI API Documentation](https://apidocs.umbraco.com/v17/ui-api/interfaces/packages_core_tree.UmbTreeRepository.html)
+
+```typescript
+interface UmbTreeRepository {
+  requestTreeRoot();
+  requestTreeRootItems();
+  requestTreeItemsOf();
+  requestTreeItemAncestors();
+}
+```