Merge pull request #87 from danskernesdigitalebibliotek/DDFBRA-249-ti…

…lfoj-dokumentation-pa-xstate-og-config-systemet Add documentation about Xstate and configuration handling
danskernesdigitalebibliotek · Jan 15, 2025 · bc4551f · bc4551f
2 parents c55dd45 + e0f01f8
commit bc4551f
Show file tree

Hide file tree

Showing 3 changed files with 145 additions and 12 deletions.
diff --git a/README.md → docs/README.md b/README.md → docs/README.md
@@ -1,4 +1,4 @@
-![GO logo](./public/icons/logo-white-readme.svg)
+![GO logo](../public/icons/logo-white-readme.svg)
 
 <p>
   <br/>
@@ -11,13 +11,15 @@
 
 ## URLs
 
-| Description                                             | URL                                                      |
-| ------------------------------------------------------- | -------------------------------------------------------- |
-| Demo site (may change)                                  | https://node.pr-1707.dpl-cms.dplplat01.dpl.reload.dk/    |
-| Demo site Drupal CMS (may change, login through lagoon) | https://varnish.pr-1707.dpl-cms.dplplat01.dpl.reload.dk/ |
+| Description                                             | URL                                                        |
+| ------------------------------------------------------- | ---------------------------------------------------------- |
+| Demo site (may change)                                  | <https://node.pr-1707.dpl-cms.dplplat01.dpl.reload.dk/>    |
+| Demo site Drupal CMS (may change, login through lagoon) | <https://varnish.pr-1707.dpl-cms.dplplat01.dpl.reload.dk/> |
 
 ## Table of contents
 
+- [URLs](#urls)
+- [Table of contents](#table-of-contents)
 - [Getting started](#getting-started)
   - [Prerequisites](#prerequisites)
   - [Setup](#setup)
@@ -28,12 +30,19 @@
   - [UI components from shadcn/ui](#ui-components-from-shadcnui)
   - [Tailwind](#tailwind)
   - [Codegen](#codegen)
+  - [Codegen types](#codegen-types)
   - [Custom types](#custom-types)
+  - [xState](#xstate)
+  - [Config handling](#config-handling)
+  - [Storybook](#storybook)
+  - [Cypress](#cypress)
 - [Deployment](#deployment)
   - [git branches and pull requests](#git-branches-and-pull-requests)
   - [Create pull request](#create-pull-request)
   - [Reviewing a PR](#reviewing-a-pr)
   - [Updating the demo site](#updating-the-demo-site)
+    - [Create a release tag in dpl-go based on sprint number](#create-a-release-tag-in-dpl-go-based-on-sprint-number)
+    - [Deploying a release](#deploying-a-release)
 - [Quality assurance](#quality-assurance)
   - [GitHub Workflows for quality assurance](#github-workflows-for-quality-assurance)
 - [Developers](#developers)
@@ -212,11 +221,11 @@ To add a custom type, create a new file in the `lib/types` directory and define
 
 ### xState
 
-TODO: write something if relevant
+Read about xState [here](architecture/adr-002-xstate.md).
 
 ### Config handling
 
-TODO: MIKKEL: write some nice words
+Read about configuration [here](architecture/adr-001-configuration.md).
 
 ### Storybook
 
@@ -332,14 +341,13 @@ Quality assurance (QA) is a critical aspect of our development process, ensuring
 
 ## Developers
 
-- Adam Antal - [email protected]
-- Mikkel Jakobsen - [email protected]
-- Thomas Gross Rasmussen - [email protected]
-- Jacob Pihl - [email protected]
+- Adam Antal - <[email protected]>
+- Mikkel Jakobsen - <[email protected]>
+- Thomas Gross Rasmussen - <[email protected]>
+- Jacob Pihl - <[email protected]>
 
 [nextjs]: https://nextjs.org/
 [app-router]: https://nextjs.org/docs/app
-[dotenv]: https://vault.dotenv.org/ui/ui1/project/KVCj0W
 [react]: https://react.dev/
 [shadcn]: https://ui.shadcn.com/
 [typescript]: https://www.typescriptlang.org/

diff --git a/docs/architecture/adr-001-configuration.md b/docs/architecture/adr-001-configuration.md
@@ -0,0 +1,79 @@
+# Configuration
+
+## Context
+
+We have several places where configuration come from:
+
+- Environment variables
+- Configuration from external API's
+- Static local configuration
+
+We wanted a unified way of handling configuration that addresses those (and
+possibly future) configuration sources.
+The reasons why is listed in the "Consequences" section of this document.
+
+## Decision
+
+We decided to make our own configuration system that uses a plugin-system we
+call resolvers. They are placed in our centralized directory `lib` directory:
+`/lib/config/resolvers`.
+
+A resolver can either be a flat value like:
+
+```typescript
+const search = {
+  "search.item.limit": 12,
+  "search.offset.initial": 0,
+  "search.param.initial": 0,
+  "search.facet.limit": 100,
+...
+```
+
+...or a function:
+
+```typescript
+{
+  "service.fbi.graphql.endpoint": () => {
+    if (process.env.NEXT_PUBLIC_GRAPHQL_SCHEMA_ENDPOINT_FBI) {
+      return process.env.NEXT_PUBLIC_GRAPHQL_SCHEMA_ENDPOINT_FBI
+    }
+  },
+}
+```
+
+...or even a asynchronous function:
+
+```typescript
+{
+  "service.unilogin.api.url": async () => {
+    if (process.env.UNILOGIN_API_URL) {
+      return process.env.UNILOGIN_API_URL
+    }
+
+    const config = await getDplCmsUniloginConfig()
+    if (config?.unilogin_api_url) {
+      return config?.unilogin_api_url
+    }
+  },
+}
+```
+
+NOTE:
+
+With configuration that is coming from an asynchronous resolver function and is dependant
+on external systems you MUST specify an environment variable that possibly can
+overwrite what is coming from outside (like in the async example).
+
+In that way it is possible in eg. in tests, development and CI to overwrite the configuration.
+
+## Alternatives considered
+
+We did not look into alternatives.
+
+## Consequences
+
+With the new configuration system we:
+
+- Do not need to know where the configuration comes from when we refer it.
+- Can have one place where we control the error handling
+- The configuration is typed so we know what is available
diff --git a/docs/architecture/adr-002-xstate.md b/docs/architecture/adr-002-xstate.md
@@ -0,0 +1,46 @@
+# Xstate
+
+## Context
+
+We wanted a methodology of handling state when we have a feature set with a
+growing number of different states, transitions and context.
+
+Also we wanted to get acquainted with Xstate both because of its principle of
+using a state tree and because of it's possibility of visualizing the various
+scenarios/flows a user could go through.
+
+## Decision
+
+The search page was growing into being a problematic scenario as described above
+with multiple elements and connected states to be managed:
+
+- Searching
+- Loading more results
+- Filtering and loading possible filters
+- Linking to a search/filtering
+
+So we decided to implement the current early version of the search in Xstate in
+order to get a transparent state tree controlling the different states and
+transition to other states.
+
+## Alternatives considered
+
+Other state handlers where considered:
+
+- Zustand
+- Redux
+
+## Consequences
+
+Common to the alternatives considered is the fact that they do have the concept
+of a state tree controlling which transitions are available at the various levels.
+
+By having all the states and possible transitions between them in a Xstate machine
+we have a predictable way of treating the various cases/flows a user can go through.
+
+Also Xstate has powerful tools in order to handle side effects of the machine/actor.
+One example is the [event handlers](https://stately.ai/docs/event-emitter#event-handlers) which we use for listening if a filter was toggled. When a filter is toggled
+we can either set or remove a query parameter accordingly.
+
+Even machine/actors can interact with each other, but let's see if we will ever
+need that complexity.