Lucid

<p align="center"><a href="https://lucidarch.site" target="_blank"><img src="github-readme-banner.svg" alt="Lucid Architecture"></a></p> <p align="center" style="margin-left: -20px"> <a href="https://docs.lucidarch.site"><img src="http://img.shields.io/badge/read_the-docs-blue" alt="Documentation"></a> <a href="https://discord.gg/j5xBhTa7"><img src="https://img.shields.io/discord/1041986899939700787?label=Discord&logo=discord" alt="Discord"/></a> <a href="https://github.com/lucidarch/lucid/actions?query=workflow%3Atests"><img src="https://img.shields.io/github/actions/workflow/status/lucidarch/lucid/tests" alt="Build Status"></a> <a href="https://packagist.org/packages/lucidarch/lucid"><img src="https://img.shields.io/packagist/v/lucidarch/lucid?label=composer&logo=composer" alt="Latest Stable Version"></a> <a href="https://github.com/lucidarch/lucid/blob/main/LICENSE"><img src="https://img.shields.io/packagist/l/lucidarch/lucid" alt="License"></a> </p>

---

• Install: https://docs.lucidarch.site/installation
• Website: https://lucidarch.site
• Documentation: https://docs.lucidarch.site
• Social: we share updates & interesting content from the web
  • Discord: Lucid
  • Twitter: @lucid_arch & #lucidarch
  • Reddit: /r/lucidarch

Table of Contents

• About Lucid
• Concept
  • Table of Contents
• Placement
• The Stack
  • Framework
  • Foundation
  • Domains
  • Services
  • Features
  • Operations
  • Data
• Benefits
  • Organization
  • Reuse & Replace
  • Boundaries
  • Multitenancy
• Contribute
  • Bug & Issue Reports
  • Support Questions
  • Core Development Discussion
  • Which Branch? And How To Contribute
    • Setup for Development
  • Security Vulnerabilities
  • Coding Style
    • PHPDoc
  • Code of Conduct

About Lucid

Lucid is a software architecture to build scalable Laravel projects. It incorporates Command Bus and Domain Driven Design at the core, upon which it builds a stack of directories and classes to organize business logic. It also derives from SOA (Service Oriented Architecture) the notion of encapsulating functionality within a service and enriches the concept with more than the service being a class.

Use Lucid to:

• Write clean code effortlessly
• Protect your code from deterioriting over time
• Review code in fractions of the time typically required
• Incorporate proven practices and patterns in your applications
• Navigate code and move between codebases without feeling astranged

Concept

This architecture is in an amalgamation of best practices, design patterns and proven methods.

• Command Bus: to dispatch units of work. In Lucid terminology these units will be a Feature, Job or Operation.
• Domain Driven Design: to organize the units of work by categorizing them according to the topic they belong to.
• Service Oriented Architecture: to encapsulate and manage functionalities of the same purpose with their required resources (routes, controllers, views, datatbase migrations etc.)

If you prefer a video, watch the announcement at Laracon EU 2016:

<p align="center"> <a href="http://www.youtube.com/watch?v=wSnM4JkyxPw"> <img src="http://img.youtube.com/vi/wSnM4JkyxPw/0.jpg"> </a> </p>

---

Table of Contents

• Placement in Laravel
• The Stack
  • Framework
  • Foundation
  • Domains
  • Services
  • Features
  • Data
• Benefits
  • Organization
  • Reuse & Replace
  • Boundaries
  • Multitenancy

Placement in Laravel

In a typical MVC application, Lucid will be the bond between the application's entrypoints and the units that do the work, securing code form meandring in drastic directions:

The Stack

At a glance...

Framework

Provides the "kernel" to do the heavy lifting of the tedious stuff such as request/response lifecycle, dependency injection, and other core functionalities.

Foundation

Extends the framework to provide higher level abstractions that are custom to the application and can be shared across the entire stack rather than being case-specific.

Examples of what could go into foundation are:

• DateTime a support class for common date and time functions
• JsonSerializableInterface that is used to identify an object to be serializable from and to JSON format

Domains

Provide separation to categorize jobs and corresponding classes that belong to the same topic. A domain operates in isolation from other domains and exposes its functionalities to features and operations through Lucid jobs only.

Consider the structure below for an example on what a domain may look like:

app/Domains/GitHub
├── GitHubClient
├── Jobs
│   ├── FetchGitHubRepoInfoJob
│   └── LoginWithGitHubJob
├── Exceptions
│   ├── InvalidTokenException
│   └── RepositoryNotFoundException
└── Tests
    └── GitHubClientTest
    └── Jobs
        ├── FetchGitHubReposJobTest
        └── LoginWithGitHubJobTest

documentation contains more details on working with domains.

Services

Are directories rich in functionality, used to separate a [Monolith]({{<ref "/micro-vs-monolith/#monolith">}}) into areas of focus in a multi-purpose application.

Consider the example of an application where we enter food recipes and would want our members to have discussions in a forum, we would have two services: 1) Kitchen, 2) Forum where the kitchen would manage all that's related to recipes, and forum is obvious:

app/Services
├── Forum
└── Kitchen

and following is a single service's structure, highlighted are the Lucid specific directories:

<pre> app/Services/Forum ├── Console │   └── Commands ├── <strong>Features</strong> ├── <strong>Operations</strong> ├── Http │   ├── Controllers │   └── Middleware ├── Providers │   ├── KitchenServiceProvider │   ├── BroadcastServiceProvider │   └── RouteServiceProvider ├── <strong>Tests</strong> │   └── <strong>Features</strong> │   └── <strong>Operations</strong> ├── database │   ├── factories │   ├── migrations │   └── seeds ├── resources │   ├── lang │   └── views └── routes ├── api ├── channels ├── console └── web </pre>

documentation has more examples of services and their contents.

Features

Represent a human-readable application feature in a class. It contains the logic that implements the feature but with the least amount of detail, by running jobs from domains and operations at the application or service level.

Serving the Feature class will be the only line in a controller's method (in MVC), consequently achieving the thinnest form of controllers.

class AddRecipeFeature extends Feature
{
    public function handle(AddRecipe $request)
    {
        $price = $this->run(CalculateRecipePriceOperation::class, [
            'ingredients' => $request->input('ingredients'),
        ]);

        $this->run(SaveRecipeJob::class, [
            'price' => $price,
            'user' => Auth::user(),
            'title' => $request->input('title'),
            'ingredients' => $request->input('ingredients'),
            'instructions' => $request->input('instructions'),
        ]);

        return $this->run(RedirectBackJob::class);
    }
}

documentation about features expands on how to serve them as classes from anywhere.

Operations

Their purpose is to increase the degree of code reusability by piecing jobs together to provide composite functionalities from across domains.

class NotifySubscribersOperation extends Operation
{
    private int $authorId;

    public function __construct(int $authorId)
    {
        $this->authorId = $authorId;
    }

    /**
     * Sends notifications to subscribers.
     *
     * @return int Number of notification jobs enqueued.
     */
    public function handle(): int
    {
        $author = $this->run(GetAuthorByIDJob::class, [
            'id' => $this->authorId,
        ]);

        do {

            $result = $this->run(PaginateSubscribersJob::class, [
                'authorId' => $this->authorId,
            ]);

            if ($result->subscribers->isNotEmpty()) {
                // it's a queueable job so it will be enqueued, no waiting time
                $this->run(SendNotificationJob::class, [
                    'from' => $author,
                    'to' => $result->subscribers,
                    'notification' => 'article.published',
                ]);
            }

        } while ($result->hasMorePages());

        return $result->total;
    }
}

documentation goes over this simple yet powerful concept.

Data

For a scalable set of interconnected data elements, we've created a place for them in app/Data, because most likely over time writing the application there could develop a nee