Home > Posts Organizing backend code

Max Heinritz

Organizing backend code

I’ve come to prefer a backend codebase structure that involves four top-level directories, arranged in an ordered dependency hierarchy:

Code in app/ can depend on all other code; code in domain/ can depend on anything except app/; etc.

Dependency restrictions can be enforced with tools like eslint’s no-restricted-imports or ArchUnit for Java.

Let’s walk through these directories in detail, starting from the bottom up.

Common code

Examples of common code include:

Common code could be easily bundled up and distributed as packages or libraries via npm, maven, etc. Indeed, reusing open source external packages instead of hand rolling common code is generally the best approach. But in every codebase I’ve worked in, we’ve ended up with some components that are library-like in nature but still specific to our particular application.

Common code is usually domain-agnostic, but not always. For example, if you are working on a payments company, you might have a common/psp-clients directory that holds client libraries for various payment service providers. These are specific to the payments domain in general, but they are stateless and could be deployed as NPM packages, so make sense within the common domain.

Common code is almost always domain-_model_-agnostic. For example, the client libraries for the PSPs should be written in a way that conforms to the external PSP rather than the team’s own domain model. Some exceptions here might be shared enum constants that are conceptually global but defined precisely as part of the domain model: transportation mode, currency code, etc.

System code

Examples of system code:

The difference between “system” and “common” is stateful vs stateless. When I say “stateful”, I mean the component actively reads/writes from a persistent data store like PostgreSQL, Redis, Elasticsearch.

A Redis client library wrapper would live in “common”. A durable event system that uses that client library to write messages for consumers to read in our database – that would be a system-level component.

Domain code

The contents of the domain directory will vary based on the application problem domain. For example:

One way to think about domain code is: if a concept is part of your domain model shared with business stakeholders, it should be within the domain directory. If a concept is exposed to end users in the product, it should live within the domain directory. End users do not care about which logging library you use (at the common layer) or which web server runner you use (at the app layer). End users do care about the domain concepts they manipulate through the product (at the domain layer).

For this reason, I tend to include in the domain directory any modules responsible for tenants, users, and roles. While these are domain-agnostic in the sense that any software system needs them, they are domain-model-specific in that the behavior of such modules heavily impacts product behavior and is an important part of users’ mental models of the system.

App code

The app directory is the orchestrator of the system. It is like the common directory in that it doesn’t deal directly with domain concepts, but it differs in that it depends on the domain code. Here are some examples of things that live at the app layer:

Unlike the common code, app code cannot simply be copied from one codebase to another. But the parts that reference the domain code can be built in a configurable way that is easy to swap out for other domains.

Tying it all together

A codebase for a restaurant SaaS application might look something like:

app/
  authentication
  entity-lookup
  gql-server
  http-server-entry
  cli-entry

domain/
  reservations
  menu
  orders
  seating-layout
  users
  tenants

system/
  durable-event
  revision-history
  system-bots

common/
  db-client
  metrics-client
  s3-client
  string-util

These buckets provide the high-level scaffolding for an application, and other techniques for code organization within these buckets merit their own descriptions.