At Code BEAM 2020, our CTO and co-founder Marcelo Lebre introduced Four Patterns to Save your Codebase and your Sanity. Remote has been utilizing these patterns for over a year now, and the results have been incredible! The speed at which we can build out new ideas and features while maintaining a consistent structure throughout all parts of the codebase is truly remarkable.

The patterns outlined below have served us well, but they do come with a drawback: boilerplate.

phx_gen_solid aims to solve the boilerplate problem as well as educate and empower others to create with the building blocks described here.

SOLID principles

The patterns from the talk build on a set of principles first introduced in Design Principles and Design Patterns by Robert Martin.

• S ingle-responsibility principle: "There should never be more than one reason for a class to change." In other words, every class should have only one responsibility.
• O pen-closed principle: "Software entities...should be open for extension, but closed for modification."
• L iskov substitution principle: "Functions that use pointers or references to base classes must be able to use objects of derived classes without knowing it.”
• I nterface segregation principle: "Many client-specific interfaces are better than one general-purpose interface.”
• D ependency inversion principle: "Depend upon abstractions, [not] concretions.”

There’s no need to deep dive into each of these, but they are important to keep in mind as they are the reasons behind each of the following solutions.

Finders, handlers, services, and values

These four patterns are the building blocks behind everything we build in our Phoenix app at Remote. Surprisingly, there is very little overlap between each, and features usually find a happy home in one of the following ideologies.

Finders

Finders fetch data. They don’t mutate nor write, only read and present.

Non-complex database queries may also exist in Phoenix Contexts. A query can be considered complex when there are several conditions for filtering, ordering, and/or pagination. Rule of thumb is when passing a params or opts Map variable to the function, a Finder is more appropriate.

Do

• Organized by application logic
• Reusable across Handlers and Services
• Focuses on achieving one single goal
• Exposes a single public function: find
• Read data structure
• Uses Values to return complex data
• Finders only read and look up data

Don't

• Call any services
• Create/modify data structures

Below is an example of a finder that finds a user.

defmodule Remoteoss.Accounts.Finder.UserWithName do
  alias Remoteoss.Accounts

  def find(name) when is_binary(name) do
    case Accounts.get_user_by_name(name) do
      nil -> {:error, :not_found}
      user -> {:ok, user}
    end
  end

  def find(_), do: {:error, :invalid_name}
end

Handlers

Handlers are orchestrators. They exist only to dispatch and compose. A handler orders execution of tasks and/or fetches data to put a response back together.

Do

• Organize by business logic, domain, or sub-domain
• Orchestrate high level operations
• Command services, finders, values or other handlers
• Multiple public functions
• Keep controllers thin
• Make it easy to read
• Flow control (if, case, pattern match, etc.)

Don't

• Directly create/modify data structures
• Execute any read/write operations

Below is an example of a handler that creates a user, sends a notification, and fetches some data.

defmodule Remoteoss.Handler.Registration do
  alias Remoteoss.Accounts.Service.{CreateUser, SendNotification}
  alias Remoteoss.Accounts.Finder.UserWithName

  def setup_user(name) do
    with {:ok, user} <- CreateUser.call(name),
         :ok <- SendNotification.call(user),
         user_details <- UserWithName.find(name) do
      {user, user_details}
    else
      error ->
        error
    end
  end
end

Services

Services are the execution arm. Services execute actions, write data, invoke third-party services, etc.

Do

• Organize by application logic
• Reusable across handlers and other services
• Commands services, finders and values
• Focuses on achieving one single goal
• Exposes a single public function: call
• Create/modify data structures
• Execute and take actions

Don't

• Use a service to achieve multiple goals
• Call handlers
• If too big, you need to break it into smaller services or your service is actually a handler.

Below is an example of a service that creates a user.

defmodule Remoteoss.Accounts.Service.CreateUser do
  alias Remoteoss.Accounts
  alias Remoteoss.Service.ActivityLog
  require Logger

  def call(name) do
    with {:ok, user} <- Accounts.create_user(%{name: name}),
         :ok <- ActivityLog.call(:create_user) do
      {:ok, user}
    else
      {:error, %Ecto.Changeset{} = changeset} ->
        {:error, {:invalid_params, changeset.errors}}

      error ->
        error
    end
  end
end

Values

Values allow us to compose data structures such as responses, intermediate objects, etc. You’ll find that values are very helpful in returning JSON from an API, and in most cases trims our View render functions into just a single line, MyValue.build(some_struct).

Do

• Organize by application logic
• Reusable across handlers, services, and finders
• Focuses on composing a data structure
• Exposes a single public function: build
• Use composition to build through simple logic
• Only returns a List or a Map

Don't

• Call any services, handlers or finders

Below is an example of a value that builds a user object to be used in a JSON response.

defmodule Remoteoss.Accounts.Value.User do
  alias Remoteoss.Value

  @valid_fields [:id, :name]

  def build(user, valid_fields \\\\ @valid_fields)

  def build(nil, _), do: nil

  def build(user, valid_fields) do
    user
    |> Value.init()
    |> Value.only(valid_fields)
  end
end

How does phx_gen_solid help?

When building an application as large as Remote’s (almost 400k lines!), it becomes tedious to write the same sort of structure over and over. We want to get into the business logic and the specifics as fast as possible. phx_gen_solid gets us to the fun part faster by generating as much boilerplate as we can right away. We can then tweak and fine-tune the specifics in any way we like! Hopefully, the generators are useful, and at the very least phx_gen_solid can act as a resource to learn a few new patterns or tricks!

phx_gen_solid is still in its infancy, but it can already assist with one of the more complicated parts of the above patterns, values.

You can add phx_gen_solid to your Phoenix app by adding the following to your mix.exs:

def deps do
  [
    {:phx_gen_solid, "~> 0.1", only: [:dev], runtime: false}
    ...
  ]
end

Thenn install and compile the dependencies:

$ mix do deps.get, deps.compile

An example in action

All phx_gen_solid generators follow the same structure as the Phoenix tasks you’re familiar with already, Context SchemaSingular schema_plural [fields].

Generating a simple Value

$ mix phx.gen.solid.value Accounts User users id slug name

This will produce the following code in my_app/accounts/values/user.ex

defmodule MyApp.Accounts.Value.User do
  alias MyApp.Value

  @valid_fields [:id, :name]

  def build(user, valid_fields \\\\ @valid_fields)

  def build(nil, _), do: nil

  def build(user, valid_fields) do
    user
    |> Value.init()
    |> Value.only(valid_fields)
  end
end

If you have defined your “Composer” with all the helpers to build values, you can specify it with the flag --value-module MyApp.Composition.Value, and the alias used in the generator will become alias MyApp.Composition.Value.

If you would like to generate the recommended Value composer, simply pass the --helpers flag along with the command. It will populate the context my_app/value.ex.

Conclusion

Remote has carefully crafted a workflow for engineers that allows us to iterate quickly and give our complete focus to the problem at hand. It’s a beautiful symphony of stakeholders, product managers, designers, and engineers working together towards a larger goal. The funny thing is, in a space where common problems are uncommon, we still find inefficiencies in what remains. It’s human nature, but it fuels progress.

If you’re interested in contributing, head over to our GitHub!

The documentation for phx_gen_solid is also available over on hexdocs.