Merge pull request #225 from os2display/feature/adr

ADR - Architecture Decision Records

Author: tuj

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)

docs/adr/001-record-architectural-decisions.md

@@ -0,0 +1,28 @@
+# ADR 001 - Record architectural decisions
+
+Date: 26-11-2024
+
+## Status
+
+Accepted
+
+## Context
+
+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.
+
+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
+
+This introduces an additional burden on core project maintainers to diligently follow architecture discussions and
+record the decisions in this repo as an ADR.

docs/adr/002-api-first.md

@@ -0,0 +1,42 @@
+# ADR 002 - API first
+
+Date: 26-11-2024
+
+## Status
+
+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.
+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 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.
+
+## Decision
+
+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
+
+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.
+
+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).

docs/adr/003-api-versioning.md

@@ -0,0 +1,30 @@
+# ADR 003 - API versioning
+
+Date: 26-11-2024
+
+## Status
+
+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
+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 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
+
+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.

docs/adr/004-browser-based-clients.md

@@ -0,0 +1,31 @@
+# ADR 004 - Browser based clients
+
+Date: 26-11-2024
+
+## Status
+
+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
+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.
+
+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.

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

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.

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 and increase the complexity of the application code.