BUILDING
BLOCKS.

What the application does: use cases, commands, queries, ports and application services.

Domain and application.

Broadly, the application has four parts.

Ports

The application talks to the outside world through ports and adapters. A port is a contract that gives your application some capability: a weather forecast, sending an email, taking a payment. It says what the application needs, not how it is done.

export abstract class WeatherForecastProvider {
    abstract forecastFor(city: string, date: Date): Promise<Forecast>
}

Ports have no common suffix. Each one is named by what it means in its own case: a WeatherForecastProvider, an EmailSender, a PaymentGateway, or just a Clock.

Execution queries

An execution query is an atomic operation that reads data from any source and changes nothing in the system.

In spirit it is very close to a port: only the contract lives in the application layer. Its concrete implementations, say through Prisma, through an external API or over an in-memory store for tests, live in infrastructure.

Unlike ports, execution queries always end in Query: a UserBalanceQuery, a CustomerDetailsQuery, an OrderHistoryQuery.

An execution query exposes a single method, handle.

Execution commands

An execution command is built exactly like an execution query: a contract in the application layer, implementations in infrastructure, a single handle method. Only the suffix differs: Command, as in an UpdateUsernameCommand or a CreateUserCommand.

The difference is in what it is for. A query gets data and changes nothing. A command does the opposite: it changes the state of the system and returns either nothing or only the minimum needed to use its result later. Say a CreateUserCommand returns the ID of the user it created.

Orchestration queries and commands

In meaning, orchestration queries and commands are the same queries and commands. A query gets data and changes nothing in the system. A command changes the state of the system and returns either nothing or only what is needed to use its result.

The difference is in how they are built. An execution operation is a single atomic step: the application layer holds only its contract, and the implementation lives in infrastructure. An orchestration operation is made of several such steps, and all of its logic lives in the application layer. It takes the execution operations it needs and combines them into one scenario.

An orchestration query exposes a single method, handle, and an orchestration command exposes the same single method.

What each one may use is not symmetric. An orchestration query may use only execution queries: reading stays reading. An orchestration command may use both execution commands and execution queries. A multi-step update often needs extra data along the way, and fetching it through a query is simpler and cleaner than passing everything in as parameters.

Queries and commands of both kinds may also use repositories.

Queries and commands vs repositories

At first glance this may look like extra work. Why write a separate query, with its own implementation, for a paginated list of users, if the same method could just go into the repository?

Just like calling save in a query, nobody forbids it. But the repository is part of the domain, and the domain describes only business rules: what would hold for any application built around it. Every other layer may depend on the domain, so the less often it changes, the better. That is why it should keep only what is most resistant to changes in the application.

Say tomorrow numbered pages turn into infinite scroll. The query changes, but the business rules don't.

Use cases

At first glance, use cases may look odd: there are already queries and commands, and they can even be orchestration ones. Why one more thing? Because a use case solves its own problem. It describes one complete thing a user does that doesn't fit into a single query or command.

A use case lives entirely in the application layer. It has no infrastructure implementations: it takes the ports, queries and commands it needs and works with them. In that it is like orchestration queries and commands. Its name always ends in UseCase, as in a PlaceOrderUseCase or a RegisterUserUseCase.

Say a user should be able to change their name in the profile, and you already have a ChangeUserProfileNameCommand (execution or orchestration, doesn't matter) that does exactly that. A ChangeUserProfileNameUseCase that only forwards the call to it makes no sense.

Use cases should appear in your code naturally. Once you see complex, important logic that doesn't fit into one query or one command, that is a good place for a use case.

Like orchestration queries and commands, a use case exposes a single method, handle, so it can be called over HTTP too.

Use cases are kept as isolated from each other as possible. A use case always describes business behavior, and two different use cases are two different use cases, even when their logic looks very much alike.

Application services

An application service holds reusable logic that doesn't fit into one port, one query or one command: a complex orchestration of commands, queries and ports that is not a use case on its own.

Like a use case, it has no infrastructure implementations: all of its logic lives in the application layer.

Say several use cases share the same tricky sequence: a couple of queries, a command, a call to a port. Instead of copying it from one use case to another, move it into an application service with a method for it.

An application service also works well as a business-facing facade over a port. Say there is a JwtSigner port that signs and verifies JWTs. It knows only about JWTs: nothing about your user IDs or the shape of your app's token, and most likely it lives in the shared layer. Inside a bounded context, an AuthJwtApplicationService takes the JwtSigner as a dependency and adds what the context knows: what goes into your token and how to read it back.

export class AuthJwtApplicationService {
    constructor(private readonly jwtSigner: JwtSigner) {}

    issueFor(userId: UserId): Promise<string> {
        // builds the app's token payload and signs it
    }

    userIdFrom(token: string): Promise<UserId> {
        // verifies the token and reads the user ID back
    }
}