Learning DDD with example building an invoice

[Eduard-Hasa]

I am really dedicated to doing things right from the start and could really use some guidance. I Learning nest js while building a hotel PMS. Currently in my Nest JS project I split my modules up already into things like bookings, invoices, invoice night stay items, invoice fees, invoice discounts, etc. I am wondering if someone could give me a very simple example of how you guys want me to do the following.

I have a quote and an invoice. They share most of the business logic in generating all of the line items, discounts, fees, calculations. I really really love the guide and there is so much for me to learn there but the example is a bit too simple to learn from. Any way someone could give me a very simplified example of how I could have a quote and invoice share generating invoice line items following all of the principles in this repo?

Also if allowed... I am willing to pay someone to be my mentor while I learn. I am a software engineer that is trying to learn building reliable and scalable architecture on my free time because my works simply doesnt care.

[Sairyss]

There is no way to create an example that will match everyone's needs, every case is unique and good architecture depends on a lot of factors.

Any way someone could give me a very simplified example of how I could have a quote and invoice share generating invoice line items following all of the principles in this repo

This description is not very detailed. You want to execute something that relies on multiple entities, or aggregate data from multiple modules? If so, a pattern that can help is Domain Service. I'd just create a service that gets all the data it needs from other modules, then generates whatever you need. Something like:

class InvoiceLineItemsGenerationService {
 async generateInvoiceLineItems() {
     const quote = getQuote(); // <- get the quote, depending on your implementation. can be a simple query call or a method call
     const invoice = getInvoice();
     const lineItems = generateLineItems(quote, invoice);
     return lineItems;
  }
}

Just expose methods/queries in Quote and in Invoice to get whatever you need.

If something is not clear, please provide more details so I can give you a better suggestion.

[Sairyss]

ChatGPT gave you the right answer. Difference between application and domain services is that one orchestrates app logic, another orchestrates domain logic. It's described in the repo:

• Application services
• Domain services

My confusion though is I know there is a query/command handler tag that marks that class with execute method a service but confused if you are labeling that handler service a domain or application service?

You just need to be able to send commands/queries to services. Doesn't matter what service it is, I usually decorate both of them (if I need them to handle commands/queries).

[Sairyss]

Here is all my understandings so far in a draw io diagram. Maybe easier to communicate all these rules by chart

You diagram looks correct pretty much (according to this repo). Just keep in mind that all those "rules" are not really rules, just recommendations. You don't necessarily need to do everything the exact same way, just do what makes sense for you app (I described it here).

[Eduard-Hasa]

Yeah I am aware they are not hard rules.

It's finally clicking and I can't thank you enough.

I had to break a rule here if you don't mind letting me know if it's justified.

I have an entity invoice which is getting all its pieces line items, discounts, fees put together in application service query handler. I created a domain service called "night stay line item generation service". That domain service will need the nightly rate to pass in the "night stay line item" value object when instantiating new one. I created a pricing engine module with a query "get nightly rate" which comes back with a rate dollar amount and I pass that in the "night stay line item" params when creating new instance.

I want to keep night stay line item as a value object because there is no identity to it. It has a room type id and rate field but if those were equal that would make the objects equal. It made sense to make night stay line item generation service a domain service and since the night stay line items building are getting orchestrated there sending the "get rate" query from a domain service was most convenient.

Does that sound like okay logic to you or would you have moved that logic up to the application service where the invoice pieces are getting put together?

[Sairyss]

For simple cases having 1 service like you described is more convenient yes, I usually do that. Separating it into 2 services mostly makes sense if you either have a lot of application logic, or a lot of domain logic, and you want to separate them and/or test them separately. But for typical cases like "I need to execute 1 query and do something" IMO it's not worth separating into 2 services most of the times.

[Eduard-Hasa]

Makes perfect sense. Thanks. I will continue to grow that diagram in hopes that I can be a contributor one day. I really think it helps portray all those small details well by putting them all in one place.

[Eduard-Hasa]

@Sairyss

Going back to my scenario where I have a query "getPrebookingInvoice". Is the following correct:

dto gets passed in controller. Controller sends query to query handler application service. Application service query handler creates a prebooking invoice entity and populates everything using prebooking Invoice entity methods. Now we have an entity in a application or domain service and we want to send that back to the controller to return to the client. Inside the application service do we simply use the prebooking invoice mapper .toResponse method to convert it to a response dto and send the dto to the controller?

I saw in your example your find users query handler is returning a user model which comes directly from you database query.

Question:
What can/should a query/command respond with (response dto from mapper converting entity->response dto, model, something else?)
Where should the creation of the response dto happen? controller only? or if using mapper in the application/domain service okay?

Thanks

[Sairyss]

I usually do transformations in the controller, "response" is a dto for the end user and controller decides how it wants to return it. Keep in mind that you can have multiple types of controllers. You can have HTTP requests, GraphQL requests, or call it from a CLI, each can have it's own response schema. If you do transformations in the service you are losing flexibility.

[Eduard-Hasa]

Do I use the mapper to convert the prebooking invoice from an entity to response dto in the controller then? Reason I'm asking is because you didn't use the mapper to create your response dto.

Also so application/domain services can return anything? Or a Model and local dto (trying not to use local dto, only if justified) only?

[Sairyss]

You can use mapper or you can convert it directly in the controller like I do in find-users.http.controller.ts, whatever you prefer more. For simple cases like this there is no need for mapper IMO, if you have complex transformations you can create a mapper.

Also so application/domain services can return anything? Or a Model and local dto (trying not to use local dto, only if justified) only?

Inside the same module you can return anything (for simplicity), between modules ideally DTOs to not make modules depend on each other and don't expose functionality that other modules shouldn't see (for example of you return an entity, some other module can execute methods on it potentially corrupting it, which cannot happen with a DTO).

[Eduard-Hasa]

One more thought on this topic.

In my case I have a query handler application service working with the prebooking invoice entity directly. Can I return that entity to the controller in the same module? Reason im asking is because I thought entities should not leak outside of domain? If I couldnt return a entity from application service to controller and entity is what im working with then I thought I could either do 2 things:

1. convert the entity to a model and return that just like you did with your find users query. This wouldnt work though because my prebooking invoice model wont have the line items in it since they are stored in a different table.

2. I could just return a prebooking invoice dto from the application service to the controller.

[Sairyss]

Ideally you shouldn't leak domain objects out of domain layer, but sometimes it can be annoying to pollute everything with tons of DTOs and types, so you could just return domain objects inside the same module. You have to try it out and decide for yourself what is easier to work with.

If you decide not to leak domain models, just create a specific type for prebooking invoice that also has line items inside, and return that.