About good practices with the use of Lucid architecture

[flavioafa]

Hello guys!

Would like to take some questions about good practices with the use of Lucid architecture.

• Reading the materials about it, I came to the conclusion that one should avoid accessing features directly, I understood that the most correct way would be to access the controller, is that correct?
• Is it okay for a service to call a foundation for a feature of another service?
• In the foundation of a service, should I call the features or methods of the controllers?
• When should I not use the foundation?

Sorry for so many questions! Thanks for listening

[Mulkave]

Hello @flavioafa

Thanks for asking these questions.

1. There is no restriction nor a preference to not access features directly. You can access them however you wish, even if you had to skip controllers. They are the consolidation of the feature’s steps so regardless how you would like to achieve the feature, what matters is for them to be in the feature. What needs to be avoided though is a job calling another job, or an operation calling another operation, or a feature calling another feature. These are best avoided because they create hidden dependencies and increase the level of unknowns, resulting in risk when changing code

2. This best be avoided. When services start depending on each other it means that we should rethink the design. Sharing code should usually happen in Domains (jobs) or Data (models, entities, etc.) sections rather than the entire feature. Can you please elaborate on your use case where you found the need to call a feature from another service?

3. What do you mean by foundation of a service? Services have no foundation, they have features, controllers, commands, views etc.

4. Foundation is a shared space for support classes/traits and common interfaces that span across the scope of the entire application, not specific to a service. It should be used only for the most abstract of aspects of the application. I’ve attached a screenshot with below as an example. As you can see they’re the most generic, yet specific to their scope of usage

Please let me know if this clears it for you, and ask away anything you have!

[flavioafa]

Hello @Mulkave, thanks for your attention!

• On question 2, for example, we have a service that manages deadlines, these deadlines are used by other services, for example, to determine the end of an inspection period. In this scenario, we have the Inspection Service that needs the Deadline Service. Remembering that this is an example, we have others. Did you understand?
• In question 3, where I speak of Service Foundation, I explained it poorly. I'll explain better. We have a Foundation folder, in it we have a subfolder for each set of Foundation, according to the Service. We use these Foundations when we need to access functionality that is implemented in another service. For example, the Address Service is used by other Services and each Service uses the Foundations that are in the Address folder. Did you understand? Is that correct? I think I need to better understand the role of the Foundation within the Lucid architecture. When not to use, when to use, these things ...
  
• On question 4, we had understood that the Foundation would serve as a door between one Service and another and we use it whenever a Service uses another Service, as in the example I mentioned above. Would that shape be incorrect? In that case, where does that happen what would be the best way to resolve it?

Thanks!

[Mulkave]

2. Ah, now i see what you mean. I think there's a misunderstanding of what a service in LUCID is. The way you are using them resembles SOA (service-oriented architecture), while in LUCID this is the role of Domains, to contain domain-specific jobs that can be executed by features and operations in any service. As explained in the docs, the example states "a project consisting of an API and an Admin [...]" so you would have API service and Admin service. In your case, Inspection and Deadline may be domains, and in that way you can run jobs and operations that depend on each other within the scope of a feature. For example:

$this->run(InspectSomethingOperation::class)

class InspectSomethingOperation extends Operation
{
    public function handle()
    {
        $deadline = $this->run(GetDeadLineJob::class);
        $this->run(ValidateDeadlineJob::class, compact('deadline');
    }
}

Of course this is a simplified example and there would be more details for each of the units above.

3. Based on the above, Address would also be a Domain and include the classes related to it there and expose their functionalities through Jobs when needed. Use Foundation as you would use Illuminate's Support package

4. With the information previously clarifying the difference between Service, Domain and Foundation, the "door" would be the Domains and Data folders. Use them to hold all that is common across services

Does this information make it easier to understand the difference?

[flavioafa]

Okay, I need to understand more. It's getting interesting!

I will explain to you how I understood it, based on what you explained to me, applying to the example I passed before. Let's go!

• Inspection is a service, which has an API.
• Deadline is a service that has an API.
• Each API mentioned has its methods of index, list, store and etc ... And can be accessed directly through requests.
• However, Inspection has a Deadline.
• With this scenario, I will exemplify the Inspection store feature, it contains the following flow
  • Validating Inspection Job
  • Save Inspection Job
  • Operation or Job to save Deadline
  • Return JSON Job
• Would it be this?
• In this example that I passed, we used to call the Feature through a Foundation to save Deadline. With the understanding you gave me, I would directly call operations or jobs Deadline, right?
  -In the project I am designing, we have many Services and inevitably, they need data that are in other Services. If I understood correctly what you explained to me, instead of calling Foundations whenever you have this scenario, the correct thing would be to directly call Jobs and Operations, right?
• In this scenario that we have Services (Ex .: Inspection) has data references from other Services (Ex .: Deadline), what is the best way to treat this in the database? Using an id from the other Service?
• Here we use massively automated tests, what are the good practices at that moment, what should and should not be done?

So, let me summarize what I’ve understood so far.

• I must create a Service when I want to expose a Domain as an API
• We can have several Services
• Each Service has its API
• Each Service uses Jobs and Operations, regardless of the domain that these Jobs and Operations are, to implement the steps of a Feature
• Each Job must do a domain task
• An Operation represents a set of Jobs and is used to replicate that set in several Services
• A Job should never call another Job
• An Operation must never call another Operation
• A Feature should never call another Feature
• I must avoid calling a Service within another Service, doing so through Jobs and Operations
• Foundation exists to serve as a "bridge" to the Laravel Framework and to reuse generic codes, such as traits, interfaces, constants and utility classes

Sorry for so many questions, but I am perfecting myself in architecture to help my teammates!

We are developing a medium / large project and chose Lucid Architecture because we understand that it would help to organize the project, facilitate maintenance and standardize communication between team members.

This discussion is very valid for us not to go in the wrong direction and use the architecture in the right way.

Thanks for listening!

[Mulkave]

Okay, I need to understand more. It's getting interesting!

I will explain to you how I understood it, based on what you explained to me, applying to the example I passed before. Let's go!

• Inspection is a service, which has an API.

• Deadline is a service that has an API.

• Each API mentioned has its methods of index, list, store and etc ... And can be accessed directly through requests.

• However, Inspection has a Deadline.

• With this scenario, I will exemplify the Inspection store feature, it contains the following flow

  • Validating Inspection Job
  • Save Inspection Job
  • Operation or Job to save Deadline
  • Return JSON Job

• Would it be this?

• In this example that I passed, we used to call the Feature through a Foundation to save Deadline. With the understanding you gave me, I would directly call operations or jobs Deadline, right?

In this scenario, Inspection and Deadline won't be separate services, but rather separate domains. A service is a way for your application to expose functionality. For example, you would have src/Services/Api where you expose functionality through an API, which has its own methods of authentication/authorisation, processing and response structures (JSON etc.).

And you may also expose the same data, using the same jobs (or others) from Inspection and Deadline domains in another service called CMS src/Services/CMS.

-In the project I am designing, we have many Services and inevitably, they need data that are in other Services. If I understood correctly what you explained to me, instead of calling Foundations whenever you have this scenario, the correct thing would be to directly call Jobs and Operations, right?

• In this scenario that we have Services (Ex .: Inspection) has data references from other Services (Ex .: Deadline), what is the best way to treat this in the database? Using an id from the other Service?

This depends on your data model. At the end of the day, this is all one application and should not undergo hard separations between its components, they will eventually have to depend on each other as you mentioned. Domains are perfect for that. Operations can use jobs from different domains in the case of needing cross-domain functionality, and to deal with data relationships we usually use Repository layer to manage that in src/Data/Repositories. That way jobs in domains won't have to deal with components from other domains at all.

• Here we use massively automated tests, what are the good practices at that moment, what should and should not be done?

A new section in the docs for each of the Lucid units (feature, job and operation) will be dedicated for that in details 😉
meanwhile, here's a brief though:

• testing Features is actually functional testing, so concentrate on how the feature behaves in different conditions and what the "client" or "user" will see/receive in those different conditions
• testing jobs and operations are limited to the scope of the functionality they provide so it shouldn't go beyond what the job/operation is doing. So it is a unit test, but feel free to access the database when needed; it should cover the entire spectrum of that functionality

So, let me summarize what I’ve understood so far.

• I must create a Service when I want to expose a Domain as an API

Prefer Domains over Services, as explained above, imagine a service being a Laravel installation (separate project) within your project. While a domain is a box of functionalities that you can share anywhere in your application but is limited to the corresponding domain.

• We can have several Services
• Each Service has its API
• Each Service uses Jobs and Operations, regardless of the domain that these Jobs and Operations are, to implement the steps of a Feature
• Each Job must do a domain task
• An Operation represents a set of Jobs and is used to replicate that set in several Services
• A Job should never call another Job
• An Operation must never call another Operation
• A Feature should never call another Feature
• I must avoid calling a Service within another Service, doing so through Jobs and Operations
• Foundation exists to serve as a "bridge" to the Laravel Framework and to reuse generic codes, such as traits, interfaces, constants and utility classes

Perfectly true 👍 all of the above

Sorry for so many questions, but I am perfecting myself in architecture to help my teammates!

Happy to hear that you've chosen Lucid. Ask away as much as you need! Happy to help 😄

We are developing a medium / large project and chose Lucid Architecture because we understand that it would help to organize the project, facilitate maintenance and standardize communication between team members.

Absolutely! That's what it did to us in the last 5 years and continues to do so until today.

This discussion is very valid for us not to go in the wrong direction and use the architecture in the right way.
Thanks for listening!

Pleasure to help you in the right direction! Keep in mind that much will change as you; nothing is absolute, especially from the first iteration.

I would love to hear your progress and what you're finding out, please keep us posted here!

[flavioafa]

Hello! Thanks for your attention! It was very enlightening. When I have news come here to share.