feat: introduce ADRs

README.md

@@ -55,6 +55,8 @@ for starting and stopping the dev environment, for running tests and for generat
 Feel free to explore it to find out more, and don't forget to have a look at the `scripts/` folder
 for more details on the implementation.
 
+For more information on the architectural decisions that have been made, refer to the [docs/arch/](./docs/arch/) folder.
+
 [asdf]: https://asdf-vm.com/
 [direnv]: https://direnv.net/
 [kind]: https://kind.sigs.k8s.io/

docs/arch/0001-record-architecture-decisions.md

@@ -0,0 +1,20 @@
+# 1. Record architecture decisions
+
+Date: 2023-05-01
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+There is a good summary of available resources at [https://adr.github.io](https://adr.github.io).
+
+## Consequences
+
+See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

docs/arch/0002-implement-a-kubernetes-apiserver-proxy.md

@@ -0,0 +1,21 @@
+# 2. Implement a proxy for the kubernetes API server
+
+Date: 2023-05-01
+
+## Status
+
+Accepted
+
+## Context
+
+Companies often needs to build user interfaces and dashboards to show the status of their Kubernetes clusters, and to allow their users to interact with them.
+Such dashboards are built on top of a custom api layer that abstracts the kubernetes api in some way, and that talks to the kubernetes api server to perform the actual operations.
+Given there are dozens -if not hundreds- of such dashboards, the amount of the work invested in writing such api layers is huge, and possibly redundant: the Kubernetes API Server -or a subset of it- is already exposed as a REST API, and it would be great if we could reuse it to some degree.
+
+## Decision
+
+We are going to build a configurable proxy for the Kubernetes API Server, that will allow the user to expose a subset of its endpoints as a REST, gRPC or GraphQL API: while the first two will likely be transparent proxies, the GraphQL one will be an entirely new implementation that will allow us to expose the Kubernetes API in a more frontend-friendly way, making the development of user interfaces and dashboards easier.
+
+## Consequences
+
+We hope that this project will allow us to reduce the amount of work needed to build new dashboards and user interfaces, discouraging the creation of new custom api layers and empowering the users to focus on the real business value of their projects.

docs/arch/0003-add-quality-assurance-tooling.md

@@ -0,0 +1,28 @@
+# 3. Add Quality Assurance tooling
+
+Date: 2023-05-01
+
+## Status
+
+Accepted
+
+## Context
+
+We want to increase the internal quality of the project.
+
+## Decision
+
+We are going to introduce a number of tools and practices to help with most aspects of development, including:
+
+- Writing down Architectural Decision Records
+- Ensuring all required tooling is installable with a few commands
+- Running static code analysis wherever possible on all files
+- Developing automated tests to cover most of the codebase
+- Setting up CI pipelines to ensure all checks are run all the time
+- Keeping a consistent format when redacting commit messages and release notes
+
+In general, we want to automate all aspect of the project development lifecycle and leverage tools to the maximum extent to ensure we can focus our attention on delivering value
+
+## Consequences
+
+The project should reach a high level of automation and quality, guaranteed by practices and tools, while keeping maintenance costs at a reasonable level.

docs/arch/0004-setup-main-project-libraries.md

@@ -0,0 +1,26 @@
+# 4. Setup main project libraries
+
+Date: 2023-05-01
+
+## Status
+
+Accepted
+
+## Context
+
+As we are starting to develop the tool, we need to decide on a few architectural patterns to follow and some libraries to use.
+
+## Decision
+
+We are going to use [Cobra] as the main CLI library: it is a well-known library that is used by many other projects, it is easy to use and has a lot of features that we will need. We recognize there are lighter options available, but we think that the benefits of using a well-known library outweigh the cons of using a heavier one.
+
+We will introduce a lightweight dependency injection container to make it easier to test the code and to relieve the code handling the business logic from being cluttered by initializations.
+
+We will explore the use of [Slog] to handle logging, to try to stick to the standard library as much as possible and avoid vendor lock-in.
+
+## Consequences
+
+We will speed up development by using well-suppoerted, consolidated libraries, but we'll also leave some space for experimentation where we think it is needed, such as the logging library.
+
+[cobra]: https://github.com/spf13/cobra
+[slog]: https://pkg.go.dev/golang.org/x/exp/slog

docs/arch/0005-handling-libraries-extensions.md

@@ -0,0 +1,19 @@
+# 5. Handling libraries extensions
+
+Date: 2023-05-01
+
+## Status
+
+Accepted
+
+## Context
+
+We sometimes find ourselves in a situation where we need to extend a library that we use. This can be for a number of reasons, but the most common ones are that we need to add a feature that the library doesn't support, or to add one or more helper functions that we need to make our life easier, or to reduce duplication, or to refactor away some non-business logic from our codebase to the library.
+
+## Decision
+
+We will store all extensions and helpers to third-party and golang own's libraries with the `x/` folder. For example, helper functions for the `net/http` package will be stored in `x/net/http`.
+
+## Consequences
+
+This will allow us to keep our codebase clean and easier to read, and it will keep the folders containing the business logic more focused on the tasks to solve.

docs/arch/0006-dependency-alert-tool.md

@@ -0,0 +1,19 @@
+# 6. Dependency alert tool
+
+Date: 2023-05-01
+
+## Status
+
+Accepted
+
+## Context
+
+We need a tool that helps us update the project dependencies automatically, keeping it as secure as possible.
+
+## Decision
+
+We are going to use [Renovate bot](https://github.com/renovatebot/renovate) as the dependency maintainer: it is a GitHub app that simplifies the update process, opening new Pull Requests when new dependencies' updates are available.
+
+## Consequences
+
+This will allow us to keep our codebase dependecies updated at a lower cost, and it possibly help avoiding security issues.