Skip to main content

Go packages organization

Timeline​

TimeDescription
2024-01-22 12:00:00 WESTCreation of the document

Status: Discussion​

Context​

Following ARD 5, we want to restructure the organization of our Go package in the top monorepo.

The goal is to have a filesytem structure that is less flat and reflect the logical organization we introduce in ARD 5.

Decision​

We propose to have 6 top level directories.

  • drivers: contains the Frameworks and Drivers layer. All the code used to communicate to other component we do not maintains should live there. Database, cloud providers, 3rd party services.
  • data: contains the Data Access Layer layer. All the logic to interact with any storage medium we use. This folder would contains for example all the sql queries and its generated code using sqlc, but also all the higher level abstraction build on top of the generated code. Eventually, we want to have a unified attraction that any service can use to fetch any data we manage without needed to know where it comes from.
  • application: contains the Application Layer layer. This is where all our business logic lives. This directory will contains a sub-directory per use-case/service. It will depends on both the drivers and the data layers.
  • api: contains the Presentation Layer. This is where all the communication logic lives. HTTP handlers and server code. The code in here should only be concerned with reading and writing message from/to HTTP. It depends on the code that lives in the application layer.
  • entities: contains all the types used to represent our data. Package on this directory should have 0 dependencies. We can have multiple sub-directory if we need to have different representation of the same data on different layers. This should also have a centralized list of function that can convert one type to another. These function can then be used in application layer when a type from the storage layer need to be passed higher up the stack, and vice-versa.
  • telemetry: contains packages related to monitoring and observability, like metrics and logging.
  • others (need a better name): contains all the other utility packages that does not fit anywhere else. Things like generics and utilities.

A visual representation of this filesystem structure is available on miro at: https://miro.com/app/board/uXjVN4ZaeWM=/

Consequences​

Following this filesystem organization, we'll have a smaller top level directory, deep filesystem structure and more logical organization to navigate the code.

Having this organization will also allow us to add some checks into the CI workflow to ensure that we do not break the dependency tree we want to have between packages. Since all package import paths will contains clear top level repo on their path, we can ensure, for example, that a package in the data directory never import anything from the application sub packages.