Add documentation about configuration handling

...and move documentation into `/docs` since that is where it needs to reside in order to be fetched by our documentation site.
danskernesdigitalebibliotek · Jan 13, 2025 · b5a7e5b · b5a7e5b
1 parent 488e332
commit b5a7e5b
Show file tree

Hide file tree

Showing 2 changed files with 95 additions and 8 deletions.
diff --git a/README.md → docs/README.md b/README.md → docs/README.md
@@ -13,11 +13,13 @@
 
 | 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/ |
+| 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)
@@ -216,7 +225,7 @@ TODO: write something if relevant
 
 ### 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