diff --git a/README.md b/README.md
index e6f0cdf..71ca5ce 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,5 @@
-# whack-a-mole-core-lib
\ No newline at end of file
+# whack-a-mole-core-lib
+
+This repository contains the core libraries for the Whack-a-Mole game.
+
+Architectural decisions are recorded [here](./docs/adr-toc.md)
\ No newline at end of file
diff --git a/adr.config.json b/adr.config.json
new file mode 100644
index 0000000..e0ae801
--- /dev/null
+++ b/adr.config.json
@@ -0,0 +1,4 @@
+{
+  "path": "docs\\adr",
+  "templates": "docs\\adr-templates"
+}
\ No newline at end of file
diff --git a/docs/adr-templates/Ad.md b/docs/adr-templates/Ad.md
new file mode 100644
index 0000000..304c71a
--- /dev/null
+++ b/docs/adr-templates/Ad.md
@@ -0,0 +1,19 @@
+# {RecordId}. {Title}
+
+{DateTime}{Supersedes}
+
+## Status
+
+{Status}
+
+## Context
+
+{Context}
+
+## Decision
+
+{Decision}
+
+## Consequences
+
+{Consequences}
diff --git a/docs/adr-templates/Init.md b/docs/adr-templates/Init.md
new file mode 100644
index 0000000..304c71a
--- /dev/null
+++ b/docs/adr-templates/Init.md
@@ -0,0 +1,19 @@
+# {RecordId}. {Title}
+
+{DateTime}{Supersedes}
+
+## Status
+
+{Status}
+
+## Context
+
+{Context}
+
+## Decision
+
+{Decision}
+
+## Consequences
+
+{Consequences}
diff --git a/docs/adr-toc.md b/docs/adr-toc.md
new file mode 100644
index 0000000..2e15e75
--- /dev/null
+++ b/docs/adr-toc.md
@@ -0,0 +1,14 @@
+# ADR Documentation
+
+__Date__ : Wednesday, 17 January 2024 11:06:43
+
+This file contains the table of contents for the architecture decision records.
+It is auto generated by the adr-cli tool and manual modifications are overwritten.
+
+# Table of contents
+
+| Adr | Title | Status |
+| --- | ----- | ------ |
+| 1 | [Record Architecture Decisions initialization](..\docs\adr\00001-record-architecture-decisions-initialization) | Accepted |
+| 2 | [Programming language and version](..\docs\adr\00002-programming-language-and-version) | New |
+
diff --git a/docs/adr/00001-record-architecture-decisions-initialization.json b/docs/adr/00001-record-architecture-decisions-initialization.json
new file mode 100644
index 0000000..6a74a72
--- /dev/null
+++ b/docs/adr/00001-record-architecture-decisions-initialization.json
@@ -0,0 +1,10 @@
+{
+  "DateTime": "2024-01-17T00:00:00+01:00",
+  "FileName": "00001-record-architecture-decisions-initialization",
+  "RecordId": 1,
+  "Status": "Accepted",
+  "TemplateType": "Init",
+  "Title": "Record Architecture Decisions initialization",
+  "Context": "",
+  "References": {}
+}
\ No newline at end of file
diff --git a/docs/adr/00001-record-architecture-decisions-initialization.md b/docs/adr/00001-record-architecture-decisions-initialization.md
new file mode 100644
index 0000000..4306c3d
--- /dev/null
+++ b/docs/adr/00001-record-architecture-decisions-initialization.md
@@ -0,0 +1,21 @@
+# 00001. Record Architecture Decisions initialization
+
+2024-01-17
+
+## Status
+
+__Accepted__
+
+## Context
+
+Architecture for agile projects has to be described and defined differently. Not all decisions will be made at once, nor will all of them be done when the project begins.
+
+## Decision
+
+We will keep a collection of records for "architecturally significant" decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques.
+
+## Consequences
+
+See [cognitect 2011.11.15](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) for more information about ADR's.
+
+This documentation is created using the (adr-cli tool)[https://github.com/gjkaal/adr-cli].
diff --git a/docs/adr/00002-programming-language-and-version.json b/docs/adr/00002-programming-language-and-version.json
new file mode 100644
index 0000000..c88c164
--- /dev/null
+++ b/docs/adr/00002-programming-language-and-version.json
@@ -0,0 +1,10 @@
+{
+  "DateTime": "2024-01-17T00:00:00+01:00",
+  "FileName": "00002-programming-language-and-version",
+  "RecordId": 2,
+  "Status": "New",
+  "TemplateType": "Ad",
+  "Title": "Programming language and version",
+  "Context": "",
+  "References": {}
+}
\ No newline at end of file
diff --git a/docs/adr/00002-programming-language-and-version.md b/docs/adr/00002-programming-language-and-version.md
new file mode 100644
index 0000000..291e90f
--- /dev/null
+++ b/docs/adr/00002-programming-language-and-version.md
@@ -0,0 +1,19 @@
+# 00002. Programming language and version
+
+2024-01-17
+
+## Status
+
+__New__
+
+## Context
+
+This ADR describes the codingh standards and programming language that is used for the core library.
+
+## Decision
+
+Coding is done in C# 12, for the net8.0 target platform.
+
+## Consequences
+
+Code that is ported from older code bases, may need some rework. See [C# language version](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/configure-language-version)