Naming

Every interface, component, base, project, and workspace needs a name. Finding good names is both important and challenging. When we fail to find good names, our systems are harder to reason about and change.

Components are the core of Polylith, so let’s start with them. If a component does one thing, consider basing its name on the one action it fulfills, e.g., validator, invoicer, or purchaser. A component sometimes operates around a concept or noun, e.g., account or car. This can be an alternative if the component does multiple things, but still ties it to a single concept.

If a component’s main responsibility is to simplify access to a third-party API, consider suffixing it with -api, e.g., foobarcorp-api. When using a well-known cloud service like AWS, consider dropping the -api suffix and using plain service names, like s3, dynamodb, and cloudwatch, or group them with a vendor prefix: aws-s3, aws-dynamodb, aws-cloudwatch. Grouping can work nicely for output from commands like info and deps.

When you have found a good name for a component, we recommend you use the same name for its interface. The poly tool does this by default when you create a component:

Is equivalent to:

When you have two components that use the same interface where one is responsible for the business logic and the other is simply a delegator to that business logic, consider a naming scheme of, for example:

Bases are responsible for exposing a public API and delegating incoming calls to components. Consider naming them after what they do, followed by the type of the API. For example, if you have a REST API that takes care of invoicing, consider invoicer-rest-api. For a lambda function that generates different reports, consider report-generator-lambda.

Deployable projects represent your deployable artifacts. Consider naming services after what they do, like invoicer or report-generator. A tool might do many things and therefore deserve a more generic name, like, for a great example, poly.