From 6e8b4abea55e03286bbb68d0fcc6e93352e4517e Mon Sep 17 00:00:00 2001 From: Troels Ugilt Jensen <6103205+tuj@users.noreply.github.com> Date: Tue, 26 Nov 2024 12:17:24 +0100 Subject: [PATCH 1/7] 2770: Started work on ADRs --- docs/adr/001-record-architecture-decisions.md | 20 +++++++++++ docs/adr/002-api-first.md | 34 +++++++++++++++++++ docs/adr/003-api-versioning.md | 26 ++++++++++++++ docs/adr/004-browser-based-clients.md | 25 ++++++++++++++ 4 files changed, 105 insertions(+) create mode 100644 docs/adr/001-record-architecture-decisions.md create mode 100644 docs/adr/002-api-first.md create mode 100644 docs/adr/003-api-versioning.md create mode 100644 docs/adr/004-browser-based-clients.md diff --git a/docs/adr/001-record-architecture-decisions.md b/docs/adr/001-record-architecture-decisions.md new file mode 100644 index 00000000..1501f49d --- /dev/null +++ b/docs/adr/001-record-architecture-decisions.md @@ -0,0 +1,20 @@ +# API first + +Date: 26-11-2024 + +## Status + +Accepted + +## Context + +We need to record the architectural decisions made on this project. + +## Decision + +We will use Architectural Decision Records, as [described by Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions). + +## Consequences + +Introduces an additional burden on core project maintainers to diligently follow architecture discussions and record the +results in this repo as an ADR. diff --git a/docs/adr/002-api-first.md b/docs/adr/002-api-first.md new file mode 100644 index 00000000..98a076bb --- /dev/null +++ b/docs/adr/002-api-first.md @@ -0,0 +1,34 @@ +# ADR 002 - API first + +Date: 26-11-2024 + +## Status + +Accepted + +## Context + +The "API first" approach is to enforce that all interactions with the system must go through the API. +See more about the "API first" approach [here](https://swagger.io/resources/articles/adopting-an-api-first-approach/). + +The previous version of OS2Display was used without the admin module in some contexts. +We want to support other uses than the standard OS2Display setup. + +By adopting the API first approach it will be possible to replace clients without rewriting the entire application. +This will make the system more future-proof. + +[OpenAPI](https://www.openapis.org/) is a standard for describing an API. + +## Decision + +We will use an API first approach where the only way to manage content is through calls to the API. +The API specification will be included [with the project](../../public/api-spec-v2.json) and kept up to date. + +## Consequences + +The main consequence is that all interactions with data in the system should be implemented in the API. +This can in some cases be more work, but will give the benefit that the interaction can be used in new contexts later +on. + +By supplying an OpenAPI specification clients will be able to auto-generate code for interacting with the API. +This will make it easier to write clients for the system. diff --git a/docs/adr/003-api-versioning.md b/docs/adr/003-api-versioning.md new file mode 100644 index 00000000..88bd4bee --- /dev/null +++ b/docs/adr/003-api-versioning.md @@ -0,0 +1,26 @@ +# ADR 003 - API versioning + +Date: 26-11-2024 + +## Status + +Accepted + +## Context + +By versioning the API we can communicate changes in the API. If an endpoint changes in a way that breaks backwards +compatibility we will change the route version. An example of a backwards compatibility break is changing field names. + +E.g. changing the field "name" to "title" will be breaking backwards compatibility. +On the other hand, adding the "title" field without removing the "name" field and updating "name" when "title" is +changed will no be a breaking change. + +## Decision + +We will version our API routes when we break backwards compatibility. +We will aim at avoiding breaking backwards compatibility as much as possible. + +## Consequences + +By versioning the API we will communicate changes in the API in a clear way. +This will make it easier to maintain clients communicating with the API. diff --git a/docs/adr/004-browser-based-clients.md b/docs/adr/004-browser-based-clients.md new file mode 100644 index 00000000..ce07cfce --- /dev/null +++ b/docs/adr/004-browser-based-clients.md @@ -0,0 +1,25 @@ +# ADR 004 - Browser based clients + +Date: 26-11-2024 + +## Status + +Accepted + +## Context + +Creating a system for managing and displaying content on different machines requires some consideration about how the +content will be displayed on different machines. Creating an application directed at a specific operating system will +limit the application options. + +An alternative is to implement the system with a common technology. Web pages can be displayed in multiple contexts. +By creating browser based clients we can make the system easier to adopt. + +## Decision + +We will write clients as web pages. + +## Consequences + +By being contained in a browser of the client machine we are limited in what we can do and know in the client machine. +The browser sets sandboxing constraints on the application when running in a browser. From bfb584df7cc9bbf5866e21a6ead1e30459659198 Mon Sep 17 00:00:00 2001 From: Troels Ugilt Jensen <6103205+tuj@users.noreply.github.com> Date: Tue, 26 Nov 2024 12:33:09 +0100 Subject: [PATCH 2/7] 2770: Updated changelog --- CHANGELOG.md | 2 ++ docs/adr/001-record-architecture-decisions.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b0eac97..e6badc10 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,8 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +- [#225](https://github.com/os2display/display-api-service/pull/225) + - Added ADRs. - [#215](https://github.com/os2display/display-api-service/pull/215) - Added calendar api feed type. - [#223](https://github.com/os2display/display-api-service/pull/223) diff --git a/docs/adr/001-record-architecture-decisions.md b/docs/adr/001-record-architecture-decisions.md index 1501f49d..24b6f364 100644 --- a/docs/adr/001-record-architecture-decisions.md +++ b/docs/adr/001-record-architecture-decisions.md @@ -1,4 +1,4 @@ -# API first +# ADR 001 - Record architecture decisions Date: 26-11-2024 From 357212bbd4ab6c8d230a7c606f1a7cb57d2ad90b Mon Sep 17 00:00:00 2001 From: Troels Ugilt Jensen <6103205+tuj@users.noreply.github.com> Date: Wed, 27 Nov 2024 11:00:16 +0100 Subject: [PATCH 3/7] 2770: Added ADRs --- ... => 001-record-architectural-decisions.md} | 8 +++-- docs/adr/002-api-first.md | 11 +++++-- docs/adr/003-api-versioning.md | 4 ++- docs/adr/004-browser-based-clients.md | 5 +++ docs/adr/005-technology-stack.md | 31 +++++++++++++++++++ docs/adr/006-templates.md | 30 ++++++++++++++++++ 6 files changed, 83 insertions(+), 6 deletions(-) rename docs/adr/{001-record-architecture-decisions.md => 001-record-architectural-decisions.md} (51%) create mode 100644 docs/adr/005-technology-stack.md create mode 100644 docs/adr/006-templates.md diff --git a/docs/adr/001-record-architecture-decisions.md b/docs/adr/001-record-architectural-decisions.md similarity index 51% rename from docs/adr/001-record-architecture-decisions.md rename to docs/adr/001-record-architectural-decisions.md index 24b6f364..329aee75 100644 --- a/docs/adr/001-record-architecture-decisions.md +++ b/docs/adr/001-record-architectural-decisions.md @@ -1,4 +1,4 @@ -# ADR 001 - Record architecture decisions +# ADR 001 - Record architectural decisions Date: 26-11-2024 @@ -8,11 +8,13 @@ Accepted ## Context -We need to record the architectural decisions made on this project. +We need to record the architectural decisions made on this project. Architectural Decision Records as +[described by Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) provides a +framework for writing down these decisions. ## Decision -We will use Architectural Decision Records, as [described by Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions). +We will use Architectural Decision Records. ## Consequences diff --git a/docs/adr/002-api-first.md b/docs/adr/002-api-first.md index 98a076bb..8a8bd08c 100644 --- a/docs/adr/002-api-first.md +++ b/docs/adr/002-api-first.md @@ -6,6 +6,8 @@ Date: 26-11-2024 Accepted +Written years after the decision was made. + ## Context The "API first" approach is to enforce that all interactions with the system must go through the API. @@ -17,12 +19,13 @@ We want to support other uses than the standard OS2Display setup. By adopting the API first approach it will be possible to replace clients without rewriting the entire application. This will make the system more future-proof. -[OpenAPI](https://www.openapis.org/) is a standard for describing an API. +[OpenAPI](https://www.openapis.org/) is a standard for describing an API interface. ## Decision -We will use an API first approach where the only way to manage content is through calls to the API. +We will use an API first approach where the only way to get and manage content is through calls to the API. The API specification will be included [with the project](../../public/api-spec-v2.json) and kept up to date. +We will to develop the clients (admin and screen) separately from the API project to enforce the "API first" approach. ## Consequences @@ -32,3 +35,7 @@ on. By supplying an OpenAPI specification clients will be able to auto-generate code for interacting with the API. This will make it easier to write clients for the system. + +By adopting the "API first" approach the API specification will be the contract between client and API. +This will limit the extensibility of the project, since the client and API need to be aligned on the interface +between them (the API specification). diff --git a/docs/adr/003-api-versioning.md b/docs/adr/003-api-versioning.md index 88bd4bee..68afcb75 100644 --- a/docs/adr/003-api-versioning.md +++ b/docs/adr/003-api-versioning.md @@ -6,6 +6,8 @@ Date: 26-11-2024 Accepted +Written years after the decision was made. + ## Context By versioning the API we can communicate changes in the API. If an endpoint changes in a way that breaks backwards @@ -13,7 +15,7 @@ compatibility we will change the route version. An example of a backwards compat E.g. changing the field "name" to "title" will be breaking backwards compatibility. On the other hand, adding the "title" field without removing the "name" field and updating "name" when "title" is -changed will no be a breaking change. +changed will not be a breaking change. ## Decision diff --git a/docs/adr/004-browser-based-clients.md b/docs/adr/004-browser-based-clients.md index ce07cfce..5b28caad 100644 --- a/docs/adr/004-browser-based-clients.md +++ b/docs/adr/004-browser-based-clients.md @@ -6,6 +6,8 @@ Date: 26-11-2024 Accepted +Written years after the decision was made. + ## Context Creating a system for managing and displaying content on different machines requires some consideration about how the @@ -22,4 +24,7 @@ We will write clients as web pages. ## Consequences By being contained in a browser of the client machine we are limited in what we can do and know in the client machine. + The browser sets sandboxing constraints on the application when running in a browser. + +The benefit is that that client should be able to run on most environments. diff --git a/docs/adr/005-technology-stack.md b/docs/adr/005-technology-stack.md new file mode 100644 index 00000000..f42f93c6 --- /dev/null +++ b/docs/adr/005-technology-stack.md @@ -0,0 +1,31 @@ +# ADR 005 - Technology stack + +Date: 26-11-2024 + +## Status + +Accepted + +Written years after the decision was made. + +## Context + +We want to create a stack that is simple and could potentially be set up on a simple hosting setup. + +We need a technology stack for the project. + +* [PHP](https://www.php.net/) provides a modern programming language with easy hosting options. +* [Symfony](https://symfony.com/) is one of the biggest PHP frameworks for creating web projects. +* [API Platform](https://api-platform.com/) is PHP framework for creating APIs. +* [OpenAPI](https://www.openapis.org/) is a standard for describing an API interface. +* [React](https://react.dev/) is one of the biggest UI frameworks. + +## Decision + +We will use PHP, Symfony and API Platform as the main technologies for the API. + +We will use OpenAPI for API specification. + +We will use React for writing the clients and templates. + +## Consequences diff --git a/docs/adr/006-templates.md b/docs/adr/006-templates.md new file mode 100644 index 00000000..a68024e6 --- /dev/null +++ b/docs/adr/006-templates.md @@ -0,0 +1,30 @@ +# ADR 006 - Templates + +Date: 27-11-2024 + +## Status + +Accepted + +Written years after the decision was made. + +## Context + +The display client should run in a browser. Slide templates should therefore be written in javascript/React. + +We would like to open up the options for extending the system with custom templates. + +We can use [remote-component](https://github.com/Paciolan/remote-component) to dynamically load react components into +a running React application. + +## Decision + +We will use `remote-component` to load the templates when rendering slides. + +## Consequences + +Templates should be built for use with `remote-component`. + +We introduce a dependency on the `remote-component` library to the project. + +Custom templates can be loaded into the system without being in the core code. From 8ef11e866544bc900dfd1f2be731ec90ab6dfbe5 Mon Sep 17 00:00:00 2001 From: Troels Ugilt Jensen <6103205+tuj@users.noreply.github.com> Date: Wed, 27 Nov 2024 11:01:49 +0100 Subject: [PATCH 4/7] 2770: Fixed sentence --- docs/adr/002-api-first.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/002-api-first.md b/docs/adr/002-api-first.md index 8a8bd08c..4c0e46b9 100644 --- a/docs/adr/002-api-first.md +++ b/docs/adr/002-api-first.md @@ -36,6 +36,6 @@ on. By supplying an OpenAPI specification clients will be able to auto-generate code for interacting with the API. This will make it easier to write clients for the system. -By adopting the "API first" approach the API specification will be the contract between client and API. +By adopting the "API first" approach the API specification will be the contract between the API and clients. This will limit the extensibility of the project, since the client and API need to be aligned on the interface between them (the API specification). From 6f6541cee1a935745ba9ced7e69a1723e2e6249d Mon Sep 17 00:00:00 2001 From: Troels Ugilt Jensen <6103205+tuj@users.noreply.github.com> Date: Wed, 27 Nov 2024 11:12:50 +0100 Subject: [PATCH 5/7] 2770: Added ADR --- docs/adr/007-configurability.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 docs/adr/007-configurability.md diff --git a/docs/adr/007-configurability.md b/docs/adr/007-configurability.md new file mode 100644 index 00000000..79b57b2c --- /dev/null +++ b/docs/adr/007-configurability.md @@ -0,0 +1,29 @@ +# ADR 007 - Configurability + +Date: 27-11-2024 + +## Status + +Accepted + +Written years after the decision was made. + +## Context + +We know the system will be used in different contexts, from a simple setup with showing content on a couple of screens +to large setups with hundreds of screens connected. + +Therefore, we want implementers to be able to configure the project to turn off features that will not be used. + +Environment variables can be used to configure a Symfony application. + +In the browser configuration can come from a file that is available to the client. + +## Decision + +We will make features configurable through environment and config files. + +## Consequences + +Features that are not "core" will have to be implemented as configurable wherever possible. +This will introduce extra work when implementing features. From d9c0fd2316c3e36d3698820871d23e6b82e2acc8 Mon Sep 17 00:00:00 2001 From: Troels Ugilt Jensen <6103205+tuj@users.noreply.github.com> Date: Thu, 28 Nov 2024 21:12:19 +0100 Subject: [PATCH 6/7] 2770: Fixed issues from review --- docs/adr/001-record-architectural-decisions.md | 10 ++++++++-- docs/adr/002-api-first.md | 3 ++- docs/adr/004-browser-based-clients.md | 3 ++- docs/adr/007-configurability.md | 2 +- 4 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/adr/001-record-architectural-decisions.md b/docs/adr/001-record-architectural-decisions.md index 329aee75..3068a72e 100644 --- a/docs/adr/001-record-architectural-decisions.md +++ b/docs/adr/001-record-architectural-decisions.md @@ -12,11 +12,17 @@ We need to record the architectural decisions made on this project. Architectura [described by Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) provides a framework for writing down these decisions. +The project has been running for several years and there is a need for summarizing some of the baselines of the project, +to document the original ideas and decisions. + ## Decision We will use Architectural Decision Records. +We will write down the original architectural decisions as ADRs even though years have passed, to help document the +thoughts behind the project. + ## Consequences -Introduces an additional burden on core project maintainers to diligently follow architecture discussions and record the -results in this repo as an ADR. +This introduces an additional burden on core project maintainers to diligently follow architecture discussions and +record the decisions in this repo as an ADR. diff --git a/docs/adr/002-api-first.md b/docs/adr/002-api-first.md index 4c0e46b9..89d42a9a 100644 --- a/docs/adr/002-api-first.md +++ b/docs/adr/002-api-first.md @@ -16,7 +16,8 @@ See more about the "API first" approach [here](https://swagger.io/resources/arti The previous version of OS2Display was used without the admin module in some contexts. We want to support other uses than the standard OS2Display setup. -By adopting the API first approach it will be possible to replace clients without rewriting the entire application. +By adopting the API first approach it will be possible to replace or write other clients without rewriting the entire +application. E.g. an external system could create content through calls to the API. This will make the system more future-proof. [OpenAPI](https://www.openapis.org/) is a standard for describing an API interface. diff --git a/docs/adr/004-browser-based-clients.md b/docs/adr/004-browser-based-clients.md index 5b28caad..25e783cd 100644 --- a/docs/adr/004-browser-based-clients.md +++ b/docs/adr/004-browser-based-clients.md @@ -27,4 +27,5 @@ By being contained in a browser of the client machine we are limited in what we The browser sets sandboxing constraints on the application when running in a browser. -The benefit is that that client should be able to run on most environments. +The benefit is that that client should be able to run on most environments and most people know how to set up a screen +in a browser. diff --git a/docs/adr/007-configurability.md b/docs/adr/007-configurability.md index 79b57b2c..5082db11 100644 --- a/docs/adr/007-configurability.md +++ b/docs/adr/007-configurability.md @@ -26,4 +26,4 @@ We will make features configurable through environment and config files. ## Consequences Features that are not "core" will have to be implemented as configurable wherever possible. -This will introduce extra work when implementing features. +This will introduce extra work when implementing features and increase the complexity of the application code. From 342c25b4e5c291c809bcf9d5bc066b9936a636c4 Mon Sep 17 00:00:00 2001 From: Troels Ugilt Jensen <6103205+tuj@users.noreply.github.com> Date: Thu, 28 Nov 2024 21:15:53 +0100 Subject: [PATCH 7/7] 2770: Added route versioning explaination --- docs/adr/003-api-versioning.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/adr/003-api-versioning.md b/docs/adr/003-api-versioning.md index 68afcb75..75ec2691 100644 --- a/docs/adr/003-api-versioning.md +++ b/docs/adr/003-api-versioning.md @@ -20,6 +20,8 @@ changed will not be a breaking change. ## Decision We will version our API routes when we break backwards compatibility. +Routes will be prefixed by version: `/v1`, `/v2`... + We will aim at avoiding breaking backwards compatibility as much as possible. ## Consequences