Benefits

What will you get when Lucid is your software architecture?

You are looking at the depricated version of the docs. See https://docs.lucidarch.dev for the latest documentation.

Human

Code Review

Lucid makes it easy to predict the impact of changes on the system as a whole, not only when working on the codebase but also when reviewing code, which we seek to facilitate with this architecture. In practice, it reduced time to review and feedback loops a significant amount for it sets the principles for mutual consensus and we spend our time on the most valuable elements of the code instead.

Debugging

A tedious task yet rewarding when resolved. The essence of Lucid is to isolate code into small interchangeable pieces of code which simplifies the process of pointing the culprit, especially with modern tracing, app monitoring and logging tools with which we can send "breadcrumbs" of code to trace back to the root of the problem, saving you time so that you're not late to the party or to join your family for dinner.

Onboarding & Hiring

We all know the pain of onboarding someone new in the team to the project(s) and the baggage of opinions they carry. We've been there too, gazing into a 1000 lines of a controller's method and trying to remember the name of the variable that was defined at line 3 then used at line 666, and we wanted to prevent this from happening ever again, for us and our fellow engineers.

Lucid has a steep learning curve, its concepts and principles are simple yet profound; after a week of practice you will be comfortable with whichever Lucid project you land on. Be it on a different project with the same team, a different team with a project that's a few years old or a different company altogether, it would only take the time to understand the intricacies of the features to get you ready to contribute code. It's as if you've eliminated a significant amount of time from the training period.

Efficiency

Being productive is about spending our time adding value to the project which is not the case when we spend it solving code conflicts when we merge our work. With the separation of concerns principle it is possible to disseminate work across the team and predicting possible conflicts that might occur due to the fact that everyone on the team is seeing a similar picture of how the code will look like (from the outside) when it's done.

Operational

Deployment & Infrastructure

When deploying large-scale applications the least we have is a bunch of servers running different services of our application, here’s a humble example of what it would look like:

Distributed hosting infrastructure

As you see in the figure above, our application consists of an API, Back Office (Admin) and a Web App (Frontend), each having its own infrastructure dependencies yet sharing Data and very likely to do so with business rules which is present in Domains on a logical level. For that reason our services declare their own dependencies in their own scope and our architecture strives to support such deployment design by providing the capability of dissecting our large application into small deployable services yet harnessing the power of shared data and logic. I know you may be thinking that this sounds a lot like Microservices and yes it does, but that is a different topic to be covered on its own, however, our Services within the monolith could later be decoupled into their own Lucid Microservice installation when needed.

Technical

Reusability — Lucid ♡ Sharing

Data and Domains are shared across services for a reason, as well as the Foundation providing common functionalities to encourage reusability whenever possible. As this humble illustration shows in one of the simplest cases, a single Job SaveToDoItemJob is shared in both features CreateToDoItemFeature and UpdateToDoItemFeature while preserving the distinctiveness of the features.

Reusability of Jobs in Operations, and both in Features

Refactoring & Technical Debt

We all want to go fast with the least amount of tech debt possible but it is inevitable to build debt along the way, and it is normal. What is most important is to keep it to a minimum by keeping the code contained with easily interchangeable pieces. This is core to Lucid, pick a Job or an Operation, replace it with a new one while keeping the signature (if possible) or revamp it from the inside without any other part of the code being affected, unless its signature or output were changed and require adaptation by the surrounding code, which still isn't a problem because it will be fairly easy to control the impact by simply finding where that Job or Operation is being used.

Replacing Jobs and Operations

Code refactoring is not a coincidence nor a treat, at a certain stage it becomes a must and when it does, we'd love the new smell and feel of the code without having to break everything or re-write it from scratch. Decided to migrate your data from one data store to another? no problem, just switch gears within Jobs and Operations and you're done!

Laravel - Solid Foundation

Finally, it is built on a solid foundation - Laravel. With all the power, simplicity and elegance provided by Laravel, it takes on where Laravel leaves off - bodies of controllers and commands. These are the areas that are not supposed to be covered by a framework yet are substantial to the well-being of our codebase, so we decided to fill them up with (hopefully) a matching degree of simplicity.