Initial commit

src/Api.php

@@ -0,0 +1,134 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App;
+
+use League\Route\Http\Exception\MethodNotAllowedException;
+use League\Route\Http\Exception\NotFoundException;
+use League\Route\RouteGroup;
+use League\Route\Router;
+use Nyholm\Psr7\Factory\Psr17Factory;
+use Siteworxpro\App\Controllers\HealthcheckController;
+use Siteworxpro\App\Controllers\IndexController;
+use Siteworxpro\App\Controllers\OpenApiController;
+use Siteworxpro\App\Http\JsonResponseFactory;
+use Siteworxpro\App\Http\Middleware\CorsMiddleware;
+use Siteworxpro\App\Http\Middleware\JwtMiddleware;
+use Siteworxpro\App\Http\Middleware\ScopeMiddleware;
+use Siteworxpro\App\Http\Responses\NotFoundResponse;
+use Siteworxpro\App\Http\Responses\ServerErrorResponse;
+use Siteworxpro\App\Services\Facades\Config;
+use Siteworxpro\App\Services\Facades\Logger;
+use Spiral\RoadRunner\Http\PSR7Worker;
+use Spiral\RoadRunner\Worker;
+
+/**
+ * Class Server
+ *
+ * This class represents the main server application.
+ * It handles incoming HTTP requests, routes them to the appropriate handlers,
+ * and manages the server lifecycle.
+ *
+ * @package Siteworxpro\App
+ */
+class Api
+{
+    /**
+     * @var Router The router instance for handling routes.
+     */
+    protected Router $router;
+
+    /**
+     * @var PSR7Worker The PSR-7 worker instance for handling HTTP requests.
+     */
+    protected PSR7Worker $worker;
+
+    /**
+     * @throws \ReflectionException
+     */
+    public function __construct()
+    {
+        Kernel::boot();
+        $this->registerRoutes();
+    }
+
+    /**
+     * Registers the routes for the server.
+     *
+     * This method is responsible for defining the routes that the server will handle.
+     * It should be implemented in subclasses to provide specific route definitions.
+     *
+     * @return void
+     */
+    public function registerRoutes(): void
+    {
+        $this->worker = new PSR7Worker(
+            Worker::create(),
+            new Psr17Factory(),
+            new Psr17Factory(),
+            new Psr17Factory()
+        );
+
+        $this->router = new Router();
+        $this->router->get('/', IndexController::class . '::get');
+        $this->router->post('/', IndexController::class . '::post');
+        $this->router->get('/healthz', HealthcheckController::class . '::get');
+
+        $this->router->group('/.well-known', function (RouteGroup $router) {
+            $router->get('/swagger.yaml', OpenApiController::class . '::get');
+            $router->get('/swagger.json', OpenApiController::class . '::get');
+        });
+
+        $this->router->middleware(new CorsMiddleware());
+        $this->router->middleware(new JwtMiddleware());
+        $this->router->middleware(new ScopeMiddleware());
+    }
+
+    /**
+     * Starts the server and handles incoming requests.
+     *
+     * This method enters an infinite loop to continuously handle incoming HTTP requests.
+     * It decodes the request body, routes the request, and sends the response. It also handles
+     * exceptions and ensures proper cleanup after each request.
+     *
+     * @throws \JsonException If there is an error decoding the JSON request body.
+     */
+    public function startServer(): void
+    {
+        Logger::info(sprintf('Server started: %s', microtime(true)));
+        Logger::info(sprintf('Server PID: %s', getmypid()));
+        Logger::info(sprintf('Server Listening on: 0.0.0.0:%s', Config::get('server.port')));
+
+        while (true) {
+            try {
+                $request = $this->worker->waitRequest();
+
+                if ($request === null) {
+                    break;
+                }
+
+                $request = $request->withParsedBody(json_decode($request->getBody()->getContents(), true));
+
+                $response = $this->router->handle($request);
+                $this->worker->respond($response);
+            } catch (MethodNotAllowedException | NotFoundException) {
+                $uri = '';
+                if (isset($request)) {
+                    $uri = $request->getUri()->getPath();
+                }
+
+                $this->worker->respond(
+                    JsonResponseFactory::createJsonResponse(new NotFoundResponse($uri))
+                );
+            } catch (\Throwable $e) {
+                Logger::error($e->getMessage());
+                Logger::error($e->getTraceAsString());
+
+                $this->worker->respond(
+                    JsonResponseFactory::createJsonResponse(new ServerErrorResponse($e))
+                );
+            }
+        }
+    }
+}

src/Async/Brokers/Broker.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Async\Brokers;
+
+abstract class Broker implements BrokerInterface
+{
+    public const array BROKER_TYPES = [
+        'redis' => Redis::class,
+        'rabbitmq' => RabbitMQ::class,
+        'kafka' => Kafka::class,
+        'sqs' => Sqs::class,
+    ];
+
+    public function __construct(protected $config = [])
+    {
+    }
+}

src/Async/Brokers/BrokerInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Async\Brokers;
+
+use Siteworxpro\App\Async\Queues\Queue;
+use Siteworxpro\App\Async\Messages\Message;
+
+interface BrokerInterface
+{
+    public function publish(Queue $queue, Message $message, ?int $delay = null): void;
+
+    public function consume(Queue $queue): Message | null;
+
+    public function acknowledge(Queue $queue, Message $message): void;
+
+    public function reject(Queue $queue, Message $message, bool $requeue = false): void;
+
+    public function purge(Queue $queue): void;
+}

src/Async/Brokers/Kafka.php

@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Async\Brokers;
+
+use RdKafka\Conf;
+use RdKafka\Exception;
+use RdKafka\KafkaConsumer;
+use RdKafka\Producer;
+use Siteworxpro\App\Async\Queues\Queue;
+use Siteworxpro\App\Async\Messages\Message;
+
+class Kafka extends Broker
+{
+    private Producer $producer;
+
+    private KafkaConsumer $consumer;
+
+    public function __construct($config = [])
+    {
+        parent::__construct($config);
+
+
+        $conf = new Conf();
+        $conf->set('bootstrap.servers', $config['brokers'] ?? 'localhost:9092');
+
+        $this->producer = new Producer($conf);
+        $this->producer->addBrokers($config['brokers'] ?? 'localhost:9092');
+
+        $conf->set('group.id', $config['consumerGroup'] ?? 'default');
+        $conf->set('auto.offset.reset', 'earliest');
+        $this->consumer = new KafkaConsumer($conf);
+    }
+
+    public function __destruct()
+    {
+        $this->producer->flush(1000);
+    }
+
+    /**
+     * @throws \Exception
+     */
+    public function publish(Queue $queue, Message $message, ?int $delay = null): void
+    {
+        $topic = $this->producer->newTopic($queue->queueName());
+        $topic->produce(RD_KAFKA_PARTITION_UA, 0, $message->serialize(), $message->getId());
+        $this->producer->flush(1000);
+    }
+
+    /**
+     * @throws Exception
+     */
+    public function consume(Queue $queue): Message|null
+    {
+        $this->consumer->subscribe([$queue->queueName()]);
+        $kafkaMessage = $this->consumer->consume(1000);
+
+        if ($kafkaMessage->err === RD_KAFKA_RESP_ERR__TIMED_OUT) {
+            return null;
+        }
+
+        if ($kafkaMessage->err === RD_KAFKA_RESP_ERR_UNKNOWN_TOPIC_OR_PART) {
+            throw new \RuntimeException(
+                "Topic '{$queue->queueName()}' or partition does not exist. Kafka does not auto-create topics" .
+                " unless configured to do so."
+            );
+        }
+
+        /** @var string | null $messageData */
+        $messageData = $kafkaMessage->payload;
+        if ($messageData !== null) {
+            /** @var Message $message */
+            $message = unserialize($messageData, ['allowed_classes' => true]);
+            $message->setId((string)$kafkaMessage->offset);
+
+            return $message;
+        }
+
+        return null;
+    }
+
+    public function acknowledge(Queue $queue, Message $message): void
+    {
+    }
+
+    public function reject(Queue $queue, Message $message, bool $requeue = false): void
+    {
+    }
+
+    public function purge(Queue $queue): void
+    {
+    }
+}

src/Async/Brokers/RabbitMQ.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Async\Brokers;
+
+use Siteworxpro\App\Async\Queues\Queue;
+use Siteworxpro\App\Async\Messages\Message;
+
+class RabbitMQ extends Broker
+{
+    public function publish(Queue $queue, Message $message, ?int $delay = null): void
+    {
+        // TODO: Implement publish() method.
+    }
+
+    public function consume(Queue $queue): Message | null
+    {
+        return null;
+    }
+
+    public function acknowledge(Queue $queue, Message $message): void
+    {
+        // TODO: Implement acknowledge() method.
+    }
+
+    public function reject(Queue $queue, Message $message, bool $requeue = false): void
+    {
+        // TODO: Implement reject() method.
+    }
+
+    public function purge(Queue $queue): void
+    {
+        // TODO: Implement purge() method.
+    }
+}

src/Async/Brokers/Redis.php

@@ -0,0 +1,190 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Async\Brokers;
+
+use Predis\Client;
+use Predis\Command\RawCommand;
+use Siteworxpro\App\Async\Messages\SayHelloMessage;
+use Siteworxpro\App\Async\Queues\Queue;
+use Siteworxpro\App\Async\Messages\Message;
+use Siteworxpro\App\Helpers\Ulid;
+
+class Redis extends Broker
+{
+    private Client $client;
+
+    private string $consumerId;
+
+    private string $consumerGroup;
+
+    private const string CONSUMER_ID_PREFIX = 'consumer-group:';
+    private const string QUEUE_PREFIX = 'queue:';
+
+    private array $queueNames = [];
+
+    public function __construct($config = [])
+    {
+        parent::__construct($config);
+
+        $this->client = \Siteworxpro\App\Services\Facades\Redis::getFacadeRoot();
+        $this->consumerId = php_uname('n') . ':' . getmypid();
+        $this->consumerGroup = $config['consumerGroup'] ?? 'default';
+    }
+
+    private function ensureQueue(string $queueName): void
+    {
+        if (in_array($queueName, $this->queueNames, true)) {
+            return;
+        }
+
+        try {
+            $this->client->executeCommand(
+                new RawCommand(
+                    'XGROUP',
+                    [
+                        'CREATE',
+                        self::QUEUE_PREFIX . $queueName,
+                        self::CONSUMER_ID_PREFIX . $this->consumerGroup,
+                        '$',
+                        'MKSTREAM'
+                    ]
+                )
+            );
+        } catch (\Exception) {
+            // If the group already exists, we catch the exception and ignore it
+            // This is because Redis will throw an error if the group already exists
+            // We can safely ignore this error as it means the group is already set up
+        }
+
+        $this->client->executeCommand(
+            new RawCommand(
+                'XGROUP',
+                [
+                    'CREATECONSUMER',
+                    self::QUEUE_PREFIX . $queueName,
+                    self::CONSUMER_ID_PREFIX . $this->consumerGroup,
+                    $this->consumerId
+                ]
+            )
+        );
+
+        $this->queueNames[] = $queueName;
+    }
+
+    public function __destruct()
+    {
+        foreach ($this->queueNames as $queueName) {
+            try {
+                $this->client->executeCommand(
+                    new RawCommand(
+                        'XGROUP',
+                        [
+                            'DELCONSUMER',
+                            self::QUEUE_PREFIX . $queueName,
+                            self::CONSUMER_ID_PREFIX . $this->consumerGroup,
+                            $this->consumerId
+                        ]
+                    )
+                );
+            } catch (\Exception) {
+                // Ignore exceptions during cleanup
+            }
+        }
+    }
+
+    /**
+     * @throws \Exception
+     */
+    public function publish(Queue $queue, Message $message, ?int $delay = null): void
+    {
+        $command = '%s * data %s';
+        $command = sprintf(
+            $command,
+            self::QUEUE_PREFIX .
+            $queue->queueName(),
+            base64_encode($message->serialize())
+        );
+
+        /** @var string $result */
+        $result = $this
+            ->client
+            ->executeCommand(
+                new RawCommand('XADD', explode(' ', $command)),
+            );
+
+        $message->setId($result);
+    }
+
+    public function consume(Queue $queue): Message|null
+    {
+        $this->ensureQueue($queue->queueName());
+
+        $command = 'GROUP %s %s COUNT 1 STREAMS %s >';
+        $command = sprintf(
+            $command,
+            self::CONSUMER_ID_PREFIX . $this->consumerGroup,
+            $this->consumerId,
+            self::QUEUE_PREFIX . $queue->queueName(),
+        );
+
+        /** @var array | null $response */
+        $response = $this
+            ->client
+            ->executeCommand(
+                new RawCommand(
+                    'XREADGROUP',
+                    explode(' ', $command)
+                )
+            );
+
+        if ($response === null || !isset($response[0][1][0][1][1])) {
+            return null;
+        }
+
+        $messageData = base64_decode($response[0][1][0][1][1]);
+        $messageId = $response[0][1][0][0];
+
+        if ($messageData === 'NOOP') {
+            // If the message is a NOOP, we return null to indicate no actual message
+            return null;
+        }
+
+        $value = unserialize($messageData, ['allowed_classes' => true]);
+        if (!$value instanceof Message) {
+            return null;
+        }
+
+        $value->setId($messageId);
+
+        return $value;
+    }
+
+    public function acknowledge(Queue $queue, Message $message): void
+    {
+        $response = $this
+            ->client
+            ->executeCommand(
+                new RawCommand(
+                    'XACK',
+                    [
+                        self::QUEUE_PREFIX . $queue->queueName(),
+                        self::CONSUMER_ID_PREFIX . $this->consumerGroup,
+                        $message->getId()
+                    ]
+                )
+            );
+    }
+
+    public function reject(Queue $queue, Message $message, bool $requeue = false): void
+    {
+        // TODO: Implement reject() method.
+    }
+
+    public function purge(Queue $queue): void
+    {
+
+        // TODO: Implement purge() method.
+    }
+}

src/Async/Brokers/Sqs.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Async\Brokers;
+
+use Siteworxpro\App\Async\Queues\Queue;
+use Siteworxpro\App\Async\Messages\Message;
+
+class Sqs extends Broker
+{
+    public function publish(Queue $queue, Message $message, ?int $delay = null): void
+    {
+        // TODO: Implement publish() method.
+    }
+
+    public function consume(Queue $queue): Message | null
+    {
+        return null;
+    }
+
+    public function acknowledge(Queue $queue, Message $message): void
+    {
+        // TODO: Implement acknowledge() method.
+    }
+
+    public function reject(Queue $queue, Message $message, bool $requeue = false): void
+    {
+        // TODO: Implement reject() method.
+    }
+
+    public function purge(Queue $queue): void
+    {
+        // TODO: Implement purge() method.
+    }
+}

src/Async/Consumer.php

@@ -0,0 +1,173 @@
+<?php
+
+declare(ticks=1);
+
+namespace Siteworxpro\App\Async;
+
+use Siteworxpro\App\Attributes\Async\HandlesMessage;
+use Siteworxpro\App\Async\Messages\Message;
+use Siteworxpro\App\Async\Queues\Queue;
+use Siteworxpro\App\Services\Facades\Broker;
+use Siteworxpro\App\Services\Facades\Logger;
+
+/**
+ * Long-running process that listens to queues, pops messages, and dispatches them to handlers.
+ */
+class Consumer
+{
+    private static bool $shutDown = false;
+
+    /** @var array<string,string> */
+    private const array QUEUES = [
+        'default' => Queues\DefaultQueue::class,
+    ];
+
+    /** @var Queue[] */
+    private array $queues = [];
+
+    /** @var array<string, string[]> message FQCN => handler FQCNs */
+    private array $handlers = [];
+
+    private const string HANDLER_NAMESPACE = 'Siteworxpro\\App\\Async\\Handlers\\';
+
+    /**
+     * @param string[] $queues Optional list of queue names (keys from self::QUEUES)
+     */
+    public function __construct(array $queues = [])
+    {
+        $queueClasses = $queues === []
+            ? array_values(self::QUEUES)
+            : array_map(
+                static function (string $name): string {
+                    if (!isset(self::QUEUES[$name])) {
+                        throw new \InvalidArgumentException("Queue '$name' is not defined.");
+                    }
+                    return self::QUEUES[$name];
+                },
+                $queues
+            );
+
+        foreach ($queueClasses as $class) {
+            $this->queues[] = new $class();
+        }
+
+        $this->registerHandlers();
+    }
+
+    /**
+     * Discover handler classes under `Handlers` and register them via HandlesMessage attributes.
+     */
+    private function registerHandlers(): void
+    {
+        $it = new \RecursiveIteratorIterator(
+            new \RecursiveDirectoryIterator(__DIR__ . '/Handlers/')
+        );
+
+        /** @var \SplFileInfo $file */
+        foreach ($it as $file) {
+            if (!$file->isFile() || $file->getExtension() !== 'php') {
+                continue;
+            }
+
+            $relative = str_replace(__DIR__ . '/Handlers/', '', $file->getPathname());
+            $class = self::HANDLER_NAMESPACE . str_replace('/', '\\', substr($relative, 0, -4));
+
+            if (!class_exists($class)) {
+                continue;
+            }
+
+            $ref = new \ReflectionClass($class);
+            foreach ($ref->getAttributes(HandlesMessage::class) as $attr) {
+                $messageClass = $attr->newInstance()->getMessageClass();
+                $this->handlers[$messageClass][] = $class;
+            }
+        }
+    }
+
+    /**
+     * Signal handler used to initiate graceful or immediate shutdown.
+     */
+    public static function handleSignal(int $signal): void
+    {
+        switch ($signal) {
+            case SIGINT:
+            case SIGTERM:
+            case SIGHUP:
+                self::$shutDown = true;
+                return;
+            case SIGKILL:
+                exit(9);
+        }
+    }
+
+    private function shouldShutDown(): bool
+    {
+        return self::$shutDown;
+    }
+
+    /**
+     * Start the consumer main loop.
+     */
+    public function start(): void
+    {
+        if (!\function_exists('pcntl_signal')) {
+            throw new \RuntimeException('The pcntl extension is required to handle signals.');
+        }
+
+        Logger::info('Starting queue consumer...');
+        Logger::info('Using Broker: ' . Broker::getFacadeRoot()::class);
+
+        foreach ([SIGINT, SIGTERM, SIGHUP] as $sig) {
+            \pcntl_signal($sig, [self::class, 'handleSignal']);
+        }
+
+        while (true) {
+            if ($this->shouldShutDown()) {
+                Logger::info('Shutting down queue consumer...');
+                break;
+            }
+
+            /** @var Queue $queue */
+            foreach ($this->queues as $queue) {
+                Logger::info('Listening to queue: ' . $queue->queueName());
+                $message = $queue->pop();
+                if (!$message) {
+                    continue;
+                }
+
+                Logger::info('Processing message of type: ' . get_class($message));
+
+                foreach ($this->getHandlersForMessage($message) as $handler) {
+                    $handler($message);
+                }
+
+                // Continue polling from the top of the loop after processing a message.
+                continue 2;
+            }
+
+            // Avoid busy-looping when no messages are available.
+            sleep(1);
+        }
+    }
+
+    /**
+     * @return callable[] Handler instances invokable with the message
+     */
+    private function getHandlersForMessage(Message $message): array
+    {
+        $messageClass = get_class($message);
+
+        if (!isset($this->handlers[$messageClass])) {
+            throw new \RuntimeException("No handler found for message class: $messageClass");
+        }
+
+        $callables = [];
+        foreach ($this->handlers[$messageClass] as $handlerClass) {
+            if (class_exists($handlerClass)) {
+                $callables[] = new $handlerClass();
+            }
+        }
+
+        return $callables;
+    }
+}

src/Async/Handlers/HandlerInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Async\Handlers;
+
+use Siteworxpro\App\Async\Messages\Message;
+
+interface HandlerInterface
+{
+    public function __invoke(Message $message): void;
+}

src/Async/Handlers/SayHelloHandler.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Async\Handlers;
+
+use Siteworxpro\App\Attributes\Async\HandlesMessage;
+use Siteworxpro\App\Async\Messages\Message;
+use Siteworxpro\App\Async\Messages\SayHelloMessage;
+use Siteworxpro\App\Services\Facades\Logger;
+
+#[HandlesMessage(SayHelloMessage::class)]
+class SayHelloHandler implements HandlerInterface
+{
+    public function __invoke(Message | SayHelloMessage $message): void
+    {
+        $name = $message->getPayload()['name'] ?? 'Guest';
+
+        Logger::info(sprintf("Hello, %s!", $name));
+    }
+}

src/Async/Messages/Message.php

@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Async\Messages;
+
+use Siteworxpro\App\Async\Queues\DefaultQueue;
+use Siteworxpro\App\Async\Queues\Queue;
+use Siteworxpro\App\Helpers\Ulid;
+
+abstract class Message implements \Serializable
+{
+    protected string $id = '';
+
+    protected string $uniqueId;
+
+    protected array $payload;
+
+    protected int $timestamp;
+
+    protected string $queue = '';
+
+    protected const string DEFAULT_QUEUE = DefaultQueue::class;
+
+    abstract public static function dispatch(...$args): void;
+
+    abstract public static function dispatchLater(int $delay, ...$args): void;
+
+    public function __construct()
+    {
+        $this->uniqueId = Ulid::generate();
+        $this->timestamp = time();
+    }
+
+    protected function getQueue(): Queue
+    {
+        if ($this->queue === '') {
+            $this->queue = static::DEFAULT_QUEUE;
+        }
+
+        return new $this->queue();
+    }
+
+    public function getId(): string
+    {
+        return $this->id;
+    }
+
+    /**
+     * @param string $id
+     */
+    public function setId(string $id): void
+    {
+        $this->id = $id;
+    }
+
+    public function getPayload(): array
+    {
+        return $this->payload;
+    }
+
+    public function getTimestamp(): int
+    {
+        return $this->timestamp;
+    }
+
+    public function __serialize(): array
+    {
+        return [
+            'id' => $this->id,
+            'payload' => $this->payload,
+            'timestamp' => $this->timestamp,
+            'queue' => $this->queue,
+        ];
+    }
+
+    public function __unserialize(array $data): void
+    {
+        $this->id = $data['id'];
+        $this->payload = $data['payload'];
+        $this->timestamp = $data['timestamp'];
+        $this->queue = $data['queue'];
+    }
+
+    public function serialize(): string
+    {
+        return serialize($this);
+    }
+
+    public function unserialize(string $data): Message
+    {
+        $unserializedData = unserialize($data, ['allowed_classes' => [Message::class]]);
+
+        $this->id = $unserializedData['id'];
+        $this->uniqueId = $unserializedData['uniqueId'];
+        $this->payload = $unserializedData['payload'];
+        $this->timestamp = $unserializedData['timestamp'];
+        $this->queue = $unserializedData['queue'];
+
+        return $this;
+    }
+}

src/Async/Messages/SayHelloMessage.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Async\Messages;
+
+use Siteworxpro\App\Services\Facades\Broker;
+
+class SayHelloMessage extends Message
+{
+    public static function dispatch(...$args): void
+    {
+        $name = $args[0] ?? 'World';
+        $message = new self($name);
+        Broker::publish(
+            $message->getQueue(),
+            $message
+        );
+    }
+
+    public static function dispatchLater(int $delay, ...$args): void
+    {
+        $name = $args[0] ?? 'World';
+        $message = new self($name);
+        Broker::publishLater(
+            $message->getQueue(),
+            $message,
+            $delay
+        );
+    }
+
+    private function __construct(
+        private readonly string $name
+    ) {
+        parent::__construct();
+
+        $this->payload = [
+            'name' => $this->name,
+        ];
+    }
+}

src/Async/Queues/DefaultQueue.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Async\Queues;
+
+readonly class DefaultQueue extends Queue
+{
+    public function queueName(): string
+    {
+        return 'default';
+    }
+}

src/Async/Queues/Queue.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Async\Queues;
+
+use Siteworxpro\App\Async\Messages\Message;
+use Siteworxpro\App\Services\Facades\Broker;
+
+readonly abstract class Queue
+{
+    abstract public function queueName(): string;
+
+    public function push(Message $message): void
+    {
+        Broker::publish($this, $message);
+    }
+
+    public function later(int $delay, Message $message): void
+    {
+        Broker::publish($this, $message, $delay);
+    }
+
+    public function pop(): Message | null
+    {
+        return Broker::consume($this);
+    }
+}

src/Attributes/Async/HandlesMessage.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Attributes\Async;
+
+use Attribute;
+
+/**
+ * Attribute to mark a class as a handler for a specific message class in an async workflow.
+ *
+ * Repeatable: attach multiple times to handle multiple message classes.
+ */
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+readonly class HandlesMessage
+{
+    /**
+     * Create a new HandlesMessage attribute.
+     *
+     * @param class-string $messageClass Fully-qualified class name of the message handled.
+     */
+    public function __construct(
+        public string $messageClass,
+    ) {
+    }
+
+    /**
+     * Get the fully-qualified message class this handler processes.
+     *
+     * @return class-string
+     */
+    public function getMessageClass(): string
+    {
+        return $this->messageClass;
+    }
+}

src/Attributes/CommandBus/HandlesCommand.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Attributes\CommandBus;
+
+use Attribute;
+
+/**
+ * Class HandlesCommand
+ * @package Siteworxpro\App\Attributes\CommandBus
+ */
+#[Attribute(Attribute::TARGET_CLASS)]
+readonly class HandlesCommand
+{
+    /**
+     * @param class-string $commandClass
+     */
+    public function __construct(public string $commandClass)
+    {
+    }
+}

src/Attributes/Events/ListensFor.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Attributes\Events;
+
+use Attribute;
+
+/**
+ * Attribute to mark a class as an event listener for a specific event class.
+ *
+ * Apply this attribute to classes that subscribe to domain or application events.
+ * Repeatable: can be attached multiple times to the same class to listen for multiple events.
+ *
+ * Targets: class only.
+ */
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+readonly class ListensFor
+{
+    /**
+     * Initialize the ListensFor attribute.
+     *
+     * @param class-string $eventClass Fully-qualified class name of the event to listen for.
+     */
+    public function __construct(public string $eventClass)
+    {
+    }
+}

src/Attributes/Guards/Jwt.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Attributes\Guards;
+
+use Attribute;
+use Siteworxpro\App\Services\Facades\Config;
+
+/**
+ * Attribute to guard classes or methods with JWT claim requirements.
+ *
+ * Apply this attribute to a class or method to declare the expected JWT issuer and/or audience.
+ * If either the issuer or audience is an empty string, the value will be resolved from configuration:
+ * - `jwt.issuer`
+ * - `jwt.audience`
+ *
+ * Targets: class or method.
+ */
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
+readonly class Jwt
+{
+    /**
+     * Initialize the Jwt attribute with optional overrides for expected JWT claims.
+     *
+     * @param string $issuer   Optional expected JWT issuer (`iss`). Empty string uses `Config::get('jwt.issuer')`.
+     * @param string $audience Optional expected JWT audience (`aud`). Empty string uses `Config::get('jwt.audience')`.
+     */
+    public function __construct(
+        private string $issuer = '',
+        private string $audience = '',
+    ) {
+    }
+
+    /**
+     * Get the expected audience for validation.
+     *
+     * Returns the constructor-provided audience when non-empty; otherwise falls back to `jwt.audience` config.
+     *
+     * @return string The audience value to enforce.
+     */
+    public function getAudience(): string
+    {
+        if ($this->audience === '') {
+            return Config::get('jwt.audience') ?? '';
+        }
+
+        return $this->audience;
+    }
+
+    /**
+     * Get the expected issuer for validation.
+     *
+     * Returns the constructor-provided issuer when non-empty; otherwise falls back to `jwt.issuer` config.
+     *
+     * @return string The issuer value to enforce.
+     */
+    public function getIssuer(): string
+    {
+        if ($this->issuer === '') {
+            return Config::get('jwt.issuer') ?? '';
+        }
+
+        return $this->issuer;
+    }
+}

src/Attributes/Guards/RequireAllScopes.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Attributes\Guards;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
+readonly class RequireAllScopes
+{
+}

src/Attributes/Guards/Scope.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Attributes\Guards;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+readonly class Scope
+{
+    /**
+     * @param array<int, string> $scopes the required scopes
+     * @param string $claim the claim to check for scopes
+     * @param string $separator the separator used to split scopes in the claim
+     */
+    public function __construct(
+        private array $scopes = [],
+        private string $claim = 'scope',
+        private string $separator = ' '
+    ) {
+    }
+
+    public function getScopes(): array
+    {
+        return $this->scopes;
+    }
+
+    public function getClaim(): string
+    {
+        return $this->claim;
+    }
+
+    public function getSeparator(): string
+    {
+        return $this->separator;
+    }
+}

src/Cli/App.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Cli;
+
+use Ahc\Cli\Application;
+use Siteworxpro\App\Cli\Commands\DemoCommand;
+use Siteworxpro\App\Cli\Commands\Queue\Start;
+use Siteworxpro\App\Cli\Commands\Queue\TestJob;
+use Siteworxpro\App\Helpers\Version;
+use Siteworxpro\App\Kernel;
+use Siteworxpro\App\Services\Facades\Config;
+
+class App
+{
+    private Application $app;
+
+    /**
+     * @throws \ReflectionException
+     */
+    public function __construct()
+    {
+        Kernel::boot();
+        $this->app = new Application('Php-Template', Version::VERSION);
+
+        $this->app->add(new DemoCommand());
+        $this->app->add(new Start());
+        $this->app->add(new TestJob());
+    }
+
+    public function run(): int
+    {
+        $this->app->logo(
+            <<<EOF
+ ▄▄▄▄▄  ▄    ▄ ▄▄▄▄▄        ▄▄▄▄▄▄▄                      ▀▀█             ▄                 
+ █   ▀█ █    █ █   ▀█          █     ▄▄▄   ▄▄▄▄▄  ▄▄▄▄     █     ▄▄▄   ▄▄█▄▄   ▄▄▄         
+ █▄▄▄█▀ █▄▄▄▄█ █▄▄▄█▀          █    █▀  █  █ █ █  █▀ ▀█    █    ▀   █    █    █▀  █        
+ █      █    █ █       ▀▀▀     █    █▀▀▀▀  █ █ █  █   █    █    ▄▀▀▀█    █    █▀▀▀▀        
+ █      █    █ █               █    ▀█▄▄▀  █ █ █  ██▄█▀    ▀▄▄  ▀▄▄▀█    ▀▄▄  ▀█▄▄▀        
+                                                  █                                        
+EOF
+        );
+        return $this->app->handle($_SERVER['argv']);
+    }
+}

src/Cli/Commands/CommandInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Cli\Commands;
+
+interface CommandInterface
+{
+    /**
+     * Execute the command.
+     *
+     * @return int
+     */
+    public function execute(): int;
+}

src/Cli/Commands/DemoCommand.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Cli\Commands;
+
+use Ahc\Cli\Input\Command;
+use Siteworxpro\App\CommandBus\Commands\ExampleCommand;
+use Siteworxpro\App\Services\Facades\CommandBus;
+
+class DemoCommand extends Command implements CommandInterface
+{
+    public function __construct()
+    {
+        parent::__construct('api:demo', 'A demo command to showcase the CLI functionality.');
+
+        $this->argument('[name]', 'Your name')
+             ->option('-g, --greet', 'Include a greeting message');
+    }
+
+    public function execute(): int
+    {
+        $pb = $this->progress(100);
+
+        for ($i = 0; $i < 100; $i += 10) {
+            usleep(100000); // Simulate work
+            $pb->advance(10);
+        }
+
+        $pb->finish();
+
+        $this->writer()->boldBlue("Demo Command Executed!\n");
+        $name = $this->values()['name'];
+        $greet = $this->values()['greet'] ?? false;
+
+        if ($greet) {
+            $this->writer()->green("Hello, $name! Welcome to the CLI demo.\n");
+        } else {
+            $exampleCommand = new ExampleCommand($name);
+            $this->writer()->yellow(CommandBus::handle($exampleCommand));
+        }
+
+        return 0;
+    }
+}

src/Cli/Commands/Queue/Start.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Cli\Commands\Queue;
+
+use Ahc\Cli\Input\Command;
+use Siteworxpro\App\Async\Consumer;
+use Siteworxpro\App\Async\Messages\SayHelloMessage;
+use Siteworxpro\App\Cli\Commands\CommandInterface;
+
+class Start extends Command implements CommandInterface
+{
+    public function __construct()
+    {
+        parent::__construct('queue:start', 'Start the queue consumer to process messages.');
+        $this->argument('[queues]', 'The name of the queue to consume from. ex. "first_queue,second_queue"');
+    }
+
+    public function execute(): int
+    {
+        $queues = [];
+        if ($this->values()['queues'] !== null) {
+            $queues = explode(',', $this->values()['queues']);
+        }
+
+        $consumer = new Consumer($queues);
+        $consumer->start();
+
+        return 0;
+    }
+}

src/Cli/Commands/Queue/TestJob.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Cli\Commands\Queue;
+
+use Ahc\Cli\Input\Command;
+use Siteworxpro\App\Async\Messages\SayHelloMessage;
+use Siteworxpro\App\Cli\Commands\CommandInterface;
+
+/**
+ * Class TestJob
+ *
+ * A CLI command to schedule a demo job that dispatches a SayHelloMessage.
+ */
+class TestJob extends Command implements CommandInterface
+{
+    public function __construct()
+    {
+        parent::__construct('queue:demo', 'Schedule a demo job.');
+    }
+
+    /**
+     * Execute the command to dispatch a SayHelloMessage.
+     *
+     * @return int Exit code
+     */
+    public function execute(): int
+    {
+        SayHelloMessage::dispatch('World from TestJob Command!');
+
+        return 0;
+    }
+}

src/CommandBus/AttributeLocator.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\CommandBus;
+
+use League\Tactician\Exception\CanNotInvokeHandlerException;
+use League\Tactician\Handler\Locator\HandlerLocator;
+use Siteworxpro\App\Attributes\CommandBus\HandlesCommand;
+
+class AttributeLocator implements HandlerLocator
+{
+    private const string HANDLER_NAMESPACE = 'Siteworxpro\\App\\CommandBus\\Handlers\\';
+
+    private array $handlers;
+
+    public function __construct()
+    {
+        $directory = __DIR__ . '/Handlers';
+        $files = scandir($directory);
+        foreach ($files as $file) {
+            if (pathinfo($file, PATHINFO_EXTENSION) === 'php') {
+                $className = pathinfo($file, PATHINFO_FILENAME);
+                $fullClassName = self::HANDLER_NAMESPACE . $className;
+
+                if (class_exists($fullClassName)) {
+                    $reflectionClass = new \ReflectionClass($fullClassName);
+                    $attributes = $reflectionClass->getAttributes(HandlesCommand::class);
+
+                    foreach ($attributes as $attribute) {
+                        $instance = $attribute->newInstance();
+                        $commandClass = $instance->commandClass;
+                        $this->handlers[$commandClass] = $fullClassName;
+                    }
+                }
+            }
+        }
+    }
+
+    public function getHandlerForCommand($commandName)
+    {
+        if (isset($this->handlers[$commandName])) {
+            $handlerClass = $this->handlers[$commandName];
+            return new $handlerClass();
+        }
+
+        throw new CanNotInvokeHandlerException("No handler found for command: " . $commandName);
+    }
+}

src/CommandBus/Commands/Command.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\CommandBus\Commands;
+
+readonly abstract class Command
+{
+}

src/CommandBus/Commands/ExampleCommand.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\CommandBus\Commands;
+
+readonly class ExampleCommand extends Command
+{
+    public function __construct(
+        private string $name
+    ) {
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+}

src/CommandBus/Handlers/CommandHandler.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\CommandBus\Handlers;
+
+abstract class CommandHandler implements CommandHandlerInterface
+{
+}

src/CommandBus/Handlers/CommandHandlerInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\CommandBus\Handlers;
+
+use Siteworxpro\App\CommandBus\Commands\Command;
+
+interface CommandHandlerInterface
+{
+    public function __invoke(Command $command): mixed;
+}

src/CommandBus/Handlers/ExampleHandler.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\CommandBus\Handlers;
+
+use Siteworxpro\App\Attributes\CommandBus\HandlesCommand;
+use Siteworxpro\App\CommandBus\Commands\Command;
+use Siteworxpro\App\CommandBus\Commands\ExampleCommand;
+use Siteworxpro\App\Services\Facades\Logger;
+
+#[HandlesCommand(ExampleCommand::class)]
+class ExampleHandler extends CommandHandler
+{
+    /**
+     * @param Command|ExampleCommand $command
+     * @return string
+     */
+    public function __invoke(Command|ExampleCommand $command): string
+    {
+        if (!method_exists($command, 'getName')) {
+            throw new \TypeError('Invalid command type provided to ExampleHandler.');
+        }
+
+        $name = $command->getName();
+        Logger::info('Handling ExampleCommand for name: ' . $name);
+
+        return 'Hello, ' . $name . '!';
+    }
+}

src/Controllers/Controller.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Controllers;
+
+use League\Route\Http\Exception\NotFoundException;
+use Nyholm\Psr7\ServerRequest;
+use OpenApi\Attributes as OA;
+use Psr\Http\Message\ResponseInterface;
+use Siteworxpro\App\Helpers\Version;
+
+/**
+ * Class Controller
+ *
+ * An abstract base controller providing default implementations for HTTP methods.
+ *
+ * @package Siteworxpro\App\Controllers
+ */
+#[OA\Info(
+    version: Version::VERSION,
+    description: "This is a template API built using Siteworxpro framework.",
+    title: "Siteworxpro Template API",
+    contact: new OA\Contact(
+        name: "Siteworxpro",
+        url: "https://www.siteworxpro.com",
+        email: "support@siteworxpro.com"
+    ),
+    license: new OA\License('MIT', 'https://opensource.org/licenses/MIT')
+)]
+#[OA\Server(url: "https://localhost", description: "Local Server")]
+abstract class Controller implements ControllerInterface
+{
+    /**
+     * @param ServerRequest $request
+     * @return ResponseInterface
+     * @throws NotFoundException
+     */
+    public function get(ServerRequest $request): ResponseInterface
+    {
+        throw new NotFoundException("not found");
+    }
+
+    /**
+     * @throws NotFoundException
+     */
+    public function post(ServerRequest $request): ResponseInterface
+    {
+        throw new NotFoundException("not found");
+    }
+
+    /**
+     * @throws NotFoundException
+     */
+    public function put(ServerRequest $request): ResponseInterface
+    {
+        throw new NotFoundException("not found");
+    }
+
+    /**
+     * @throws NotFoundException
+     */
+    public function delete(ServerRequest $request): ResponseInterface
+    {
+        throw new NotFoundException("not found");
+    }
+
+    /**
+     * @throws NotFoundException
+     */
+    public function patch(ServerRequest $request): ResponseInterface
+    {
+        throw new NotFoundException("not found");
+    }
+}

src/Controllers/ControllerInterface.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Controllers;
+
+use Nyholm\Psr7\ServerRequest;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Interface ControllerInterface
+ *
+ * Defines the contract for handling HTTP requests in a controller.
+ */
+interface ControllerInterface
+{
+    /**
+     * Handle the request and return a response.
+     *
+     * @param ServerRequest $request The request data.
+     * @return ResponseInterface The response data.
+     */
+    public function get(ServerRequest $request): ResponseInterface;
+
+    /**
+     * Handle the request and return a response.
+     *
+     * @param ServerRequest $request The request data.
+     * @return ResponseInterface The response data.
+     */
+    public function post(ServerRequest $request): ResponseInterface;
+
+    /**
+     * Handle the request and return a response.
+     *
+     * @param ServerRequest $request The request data.
+     * @return ResponseInterface The response data.
+     */
+    public function put(ServerRequest $request): ResponseInterface;
+
+    /**
+     * Handle the request and return a response.
+     *
+     * @param ServerRequest $request The request data.
+     * @return ResponseInterface The response data.
+     */
+    public function delete(ServerRequest $request): ResponseInterface;
+
+    /**
+     * Handle the request and return a response.
+     *
+     * @param ServerRequest $request The request data.
+     * @return ResponseInterface The response data.
+     */
+    public function patch(ServerRequest $request): ResponseInterface;
+}

src/Controllers/HealthcheckController.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Controllers;
+
+use Illuminate\Database\PostgresConnection;
+use Nyholm\Psr7\ServerRequest;
+use Psr\Http\Message\ResponseInterface;
+use Siteworxpro\App\Http\JsonResponseFactory;
+use Siteworxpro\App\Http\Responses\GenericResponse;
+use Siteworxpro\App\Http\Responses\ServerErrorResponse;
+use Siteworxpro\App\Models\Model;
+use Siteworxpro\App\Services\Facades\Logger;
+use Siteworxpro\App\Services\Facades\Redis;
+use Siteworxpro\HttpStatus\CodesEnum;
+use OpenApi\Attributes as OA;
+
+/**
+ * Class HealthcheckController
+ *
+ * Handles health check requests to verify database and cache connectivity.
+ *
+ * @package Siteworxpro\App\Controllers
+ */
+class HealthcheckController extends Controller
+{
+    /**
+     * Handles the GET request for health check.
+     *
+     * @throws \JsonException
+     */
+    #[OA\Get(path: '/healthz', tags: ['Healthcheck'])]
+    #[OA\Response(response: '200', description: 'Healthcheck OK')]
+    #[OA\Response(response: '503', description: 'Healthcheck Failed')]
+    public function get(ServerRequest $request): ResponseInterface
+    {
+        try {
+            /** @var PostgresConnection $conn */
+            $conn = Model::getConnectionResolver()->connection();
+            $conn->getPdo()->exec('SELECT 1');
+
+            $response = Redis::ping();
+            if ($response->getPayload() !== 'PONG') {
+                throw new \Exception('Redis ping failed');
+            }
+        } catch (\Exception $e) {
+            Logger::emergency(
+                'Healthcheck failed: ' . $e->getMessage(),
+                ['exception' => $e]
+            );
+
+            return JsonResponseFactory::createJsonResponse(
+                new ServerErrorResponse($e),
+                CodesEnum::SERVICE_UNAVAILABLE
+            );
+        }
+
+        return JsonResponseFactory::createJsonResponse(
+            new GenericResponse('Healthcheck OK')
+        );
+    }
+}

src/Controllers/IndexController.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Controllers;
+
+use Nyholm\Psr7\ServerRequest;
+use Psr\Http\Message\ResponseInterface;
+use Siteworxpro\App\Attributes\Guards;
+use Siteworxpro\App\CommandBus\Commands\ExampleCommand;
+use Siteworxpro\App\Docs\TokenSecurity;
+use Siteworxpro\App\Docs\UnauthorizedResponse;
+use Siteworxpro\App\Http\JsonResponseFactory;
+use OpenApi\Attributes as OA;
+use Siteworxpro\App\Http\Responses\GenericResponse;
+use Siteworxpro\App\Services\Facades\CommandBus;
+
+/**
+ * Class IndexController
+ *
+ * This class handles the index route of the application.
+ */
+class IndexController extends Controller
+{
+    /**
+     * Handles the GET request for the index route.
+     *
+     * @throws \JsonException
+     */
+    #[Guards\Jwt]
+    #[Guards\Scope(['get.index', 'status.check'])]
+    #[Guards\RequireAllScopes]
+    #[OA\Get(path: '/', security: [new TokenSecurity()], tags: ['Examples'])]
+    #[OA\Response(
+        response: '200',
+        description: 'An Example Response',
+        content: new OA\JsonContent(ref: '#/components/schemas/GenericResponse')
+    )]
+    #[UnauthorizedResponse]
+    public function get(ServerRequest $request): ResponseInterface
+    {
+        $command = new ExampleCommand($request->getQueryParams()['name'] ?? 'Guest');
+        $greeting = CommandBus::handle($command);
+
+        return JsonResponseFactory::createJsonResponse(new GenericResponse('Server is running. ' . $greeting));
+    }
+
+    /**
+     * Handles the POST request for the index route.
+     *
+     * @throws \JsonException
+     */
+    #[Guards\Jwt]
+    #[Guards\Scope(['post.index'])]
+    #[OA\Post(path: '/', security: [new TokenSecurity()], tags: ['Examples'])]
+    #[OA\Response(
+        response: '200',
+        description: 'An Example Response',
+        content: new OA\JsonContent(ref: '#/components/schemas/GenericResponse')
+    )]
+    #[UnauthorizedResponse]
+    public function post(ServerRequest $request): ResponseInterface
+    {
+        return JsonResponseFactory::createJsonResponse(new GenericResponse('POST request received'));
+    }
+}

src/Controllers/OpenApiController.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Controllers;
+
+use Nyholm\Psr7\Response;
+use Nyholm\Psr7\ServerRequest;
+use OpenApi\Generator;
+use Psr\Http\Message\ResponseInterface;
+
+class OpenApiController extends Controller
+{
+    /**
+     * Handles the GET request to generate and return the OpenAPI specification.
+     *
+     * @param ServerRequest $request
+     * @return ResponseInterface
+     */
+    public function get(ServerRequest $request): ResponseInterface
+    {
+        $openapi = new Generator()->generate([
+            __DIR__ . '/../Controllers',
+            __DIR__ . '/../Models',
+            __DIR__ . '/../Http/Responses',
+        ]);
+
+        $response = new Response();
+
+        if (
+            $request->getHeaderLine('Accept') === 'application/json' ||
+            str_contains($request->getUri()->getPath(), '.json')
+        ) {
+            $response->getBody()->write($openapi->toJson());
+            return $response->withHeader('Content-Type', 'application/json');
+        }
+
+        $response->getBody()->write($openapi->toYaml());
+        return $response->withHeader('Content-Type', 'application/x-yaml');
+    }
+}

src/Docs/TokenSecurity.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Siteworxpro\App\Docs;
+
+use OpenApi\Attributes as OA;
+
+class TokenSecurity extends OA\SecurityScheme
+{
+    public function __construct()
+    {
+        parent::__construct(
+            securityScheme: 'bearerAuth',
+            type: 'http',
+            description: 'JWT based authentication using Bearer tokens.',
+            bearerFormat: 'JWT',
+            scheme: 'bearer'
+        );
+    }
+}

src/Docs/UnauthorizedResponse.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Siteworxpro\App\Docs;
+
+use OpenApi\Attributes as OA;
+
+#[\Attribute]
+class UnauthorizedResponse extends OA\Response
+{
+    public function __construct()
+    {
+        parent::__construct(
+            response: '401',
+            description: 'Unauthorized - Authentication is required and has failed or has not yet been provided.',
+            content: new OA\MediaType(
+                mediaType: 'application/json',
+                schema: new OA\Schema(
+                    properties: [
+                        new OA\Property(property: 'message', type: 'string', example: 'Unauthorized'),
+                    ]
+                )
+            )
+        );
+    }
+}

src/Events/Dispatcher.php

@@ -0,0 +1,246 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Events;
+
+use Illuminate\Contracts\Events\Dispatcher as DispatcherContract;
+use Illuminate\Contracts\Support\Arrayable;
+use Illuminate\Support\Collection;
+use Siteworxpro\App\Attributes\Events\ListensFor;
+
+use function React\Async\await;
+use function React\Async\coroutine;
+
+/**
+ * Class Dispatcher
+ *
+ * A custom event dispatcher that automatically registers event listeners
+ * based on the ListensFor attribute.
+ *
+ * @package Siteworxpro\App\Events
+ */
+class Dispatcher implements DispatcherContract, Arrayable
+{
+    /**
+     * @var array $listeners Registered event listeners
+     */
+    private array $listeners = [];
+
+    /**
+     * @var Collection $pushed Pushed events collection
+     */
+    private Collection $pushed;
+
+    private array $subscribers = [];
+
+    /**
+     * @var string LISTENERS_NAMESPACE The namespace where listeners are located
+     */
+    private const string LISTENERS_NAMESPACE = 'Siteworxpro\\App\\Events\\Listeners\\';
+
+    public function __construct()
+    {
+        $this->pushed = new Collection();
+        $this->registerListeners();
+    }
+
+    /**
+     * @throws \Throwable
+     */
+    public function __destruct()
+    {
+        foreach ($this->pushed as $event => $payload) {
+            $this->dispatch($event, $payload);
+        }
+    }
+
+    /**
+     * Register event listeners based on the ListensFor attribute.
+     *
+     * @return void
+     */
+    private function registerListeners(): void
+    {
+        // traverse the Listeners directory and register all listeners
+        $listenersPath = __DIR__ . '/Listeners';
+        $iterator = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($listenersPath));
+
+        foreach ($iterator as $file) {
+            if ($file->isFile() && $file->getExtension() === 'php') {
+                $relativePath = str_replace($listenersPath . '/', '', $file->getPathname());
+                $className = self::LISTENERS_NAMESPACE . str_replace(['/', '.php'], ['\\', ''], $relativePath);
+                if (class_exists($className)) {
+                    $reflectionClass = new \ReflectionClass($className);
+                    $attributes = $reflectionClass->getAttributes(ListensFor::class);
+                    foreach ($attributes as $attribute) {
+                        $instance = $attribute->newInstance();
+                        $eventClass = $instance->eventClass;
+                        $this->listen($eventClass, new $className());
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * Register a listener for the given events.
+     *
+     * @param $events
+     * @param $listener
+     * @return void
+     */
+    public function listen($events, $listener = null): void
+    {
+        $this->listeners[$events][] = $listener;
+    }
+
+    /**
+     * Check if there are listeners for the given event.
+     *
+     * @param $eventName
+     * @return bool
+     */
+    public function hasListeners($eventName): bool
+    {
+        return isset($this->listeners[$eventName]) && !empty($this->listeners[$eventName]);
+    }
+
+    /**
+     * Subscribe a subscriber to the dispatcher.
+     *
+     * @param Arrayable $subscriber
+     * @return void
+     */
+    public function subscribe($subscriber): void
+    {
+        $this->subscribers[] = $subscriber;
+    }
+
+    /**
+     * Dispatch an event and halt on the first non-null response.
+     *
+     * @param $event
+     * @param array $payload
+     * @return array|null
+     * @throws \Throwable
+     */
+    public function until($event, $payload = []): array|null
+    {
+        return $this->dispatch($event, $payload, true);
+    }
+
+    /**
+     * Dispatch an event to its listeners.
+     *
+     * @param $event
+     * @param array $payload
+     * @param bool $halt
+     * @return array|null
+     * @throws \Throwable
+     */
+    public function dispatch($event, $payload = [], $halt = false): array|null
+    {
+        if (is_object($event)) {
+            $eventClass = get_class($event);
+        } else {
+            $eventClass = $event;
+        }
+
+        // Handle subscribers as a coroutine
+        $promise = coroutine(function () use ($event, $payload, $halt, $eventClass, &$responses) {
+            foreach ($this->subscribers as $subscriber) {
+                if (method_exists($subscriber, 'handle')) {
+                    $response = $subscriber->handle($event, $payload);
+                    $responses[$eventClass] = $response;
+
+                    if ($halt && $response !== null) {
+                        return $responses;
+                    }
+                }
+            }
+
+            return null;
+        });
+
+        $listeners = $this->listeners[$eventClass] ?? null;
+
+        // If no listeners, just await the subscriber promise
+        if ($listeners === null) {
+            return await($promise);
+        }
+
+        $responses = [];
+        foreach ($listeners as $listener) {
+            $response = $listener($event, $payload);
+            $responses[$eventClass] = $response;
+
+            if ($halt && $response !== null) {
+                return $response;
+            }
+        }
+
+        // Await the subscriber promise and merge responses
+        $promiseResponses = await($promise);
+
+        if (is_array($promiseResponses)) {
+            $responses = array_merge($responses, $promiseResponses);
+        }
+
+        return $responses;
+    }
+
+    /**
+     * Push an event to be dispatched later.
+     *
+     * @param $event
+     * @param array $payload
+     * @return void
+     */
+    public function push($event, $payload = []): void
+    {
+        $this->pushed->put($event, $payload);
+    }
+
+    /**
+     * Flush a pushed event, dispatching it if it exists.
+     *
+     * @param $event
+     * @return void
+     * @throws \Throwable
+     */
+    public function flush($event): void
+    {
+        if ($this->pushed->has($event)) {
+            $payload = $this->pushed->get($event);
+            $this->dispatch($event, $payload);
+            $this->pushed->forget([$event]);
+        }
+    }
+
+    /**
+     * Forget a pushed event without dispatching it.
+     *
+     * @param $event
+     * @return void
+     */
+    public function forget($event): void
+    {
+        $this->pushed->forget([$event]);
+    }
+
+    /**
+     * Forget all pushed events.
+     *
+     * @return void
+     */
+    public function forgetPushed(): void
+    {
+        $this->pushed = new Collection();
+    }
+
+    public function toArray(): array
+    {
+        return $this->listeners;
+    }
+}

src/Events/Listeners/Database/Connected.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Events\Listeners\Database;
+
+use Illuminate\Database\Events\ConnectionEstablished;
+use Illuminate\Database\Events\ConnectionEvent;
+use Siteworxpro\App\Attributes\Events\ListensFor;
+use Siteworxpro\App\Events\Listeners\Listener;
+use Siteworxpro\App\Services\Facades\Logger;
+
+/**
+ * Class Connected
+ * @package Siteworxpro\App\Events\Listeners\Database
+ */
+#[ListensFor(ConnectionEstablished::class)]
+class Connected extends Listener
+{
+    /**
+     * @param mixed $event
+     * @param array $payload
+     * @return null
+     */
+    public function __invoke(mixed $event, array $payload = []): null
+    {
+        if (!($event instanceof ConnectionEvent)) {
+            throw new \TypeError("Invalid event type passed to listener " . static::class);
+        }
+
+        Logger::info("Database connection event", [get_class($event), $event->connectionName]);
+
+        return null;
+    }
+}

src/Events/Listeners/Listener.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Events\Listeners;
+
+/**
+ * Class Listener
+ *
+ * @package Siteworxpro\App\Events\Listeners
+ */
+abstract class Listener implements ListenerInterface
+{
+}

src/Events/Listeners/ListenerInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Events\Listeners;
+
+/**
+ * Interface ListenerInterface
+ * @package Siteworxpro\App\Events\Listeners
+ */
+interface ListenerInterface
+{
+    /**
+     * @param mixed $event
+     * @param array $payload
+     * @return mixed
+     */
+    public function __invoke(mixed $event, array $payload = []): mixed;
+}

src/Events/Subscribers/Subscriber.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Events\Subscribers;
+
+use Illuminate\Contracts\Support\Arrayable;
+
+abstract class Subscriber implements SubscriberInterface, Arrayable
+{
+    public function toArray(): array
+    {
+        return get_object_vars($this);
+    }
+}

src/Events/Subscribers/SubscriberInterface.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Events\Subscribers;
+
+interface SubscriberInterface
+{
+    public function handle(string $eventName, mixed $payload): mixed;
+}

src/Grpc.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App;
+
+use GRPC\Greeter\GreeterInterface;
+use Siteworxpro\App\GrpcHandlers\GreeterHandler;
+use Siteworxpro\App\Services\Facades\Config;
+use Spiral\RoadRunner\GRPC\Invoker;
+use Spiral\RoadRunner\GRPC\Server;
+use Spiral\RoadRunner\Worker;
+
+/**
+ * Class Grpc
+ *
+ * starts a gRPC server using RoadRunner
+ *
+ * @package Siteworxpro\App
+ */
+class Grpc
+{
+    private const array SERVICES = [
+        GreeterInterface::class => GreeterHandler::class,
+    ];
+
+    /**
+     * @throws \ReflectionException
+     */
+    public function __construct()
+    {
+        Kernel::boot();
+    }
+
+    /**
+     * Starts the gRPC server
+     *
+     * @return int
+     */
+    public function start(): int
+    {
+        $server = new Server(new Invoker(), [
+            'debug' => Config::get('app.dev_mode'),
+        ]);
+
+        foreach (self::SERVICES as $interface => $handler) {
+            $server->registerService($interface, new $handler());
+        }
+
+        $server->serve(Worker::create());
+
+        return 0;
+    }
+}

src/GrpcHandlers/GreeterHandler.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\GrpcHandlers;
+
+use GRPC\Greeter\GreeterInterface;
+use GRPC\Greeter\HelloReply;
+use GRPC\Greeter\HelloRequest;
+use Siteworxpro\App\CommandBus\Commands\ExampleCommand;
+use Siteworxpro\App\Services\Facades\CommandBus;
+use Spiral\RoadRunner\GRPC;
+
+class GreeterHandler implements GreeterInterface
+{
+    public function SayHello(GRPC\ContextInterface $ctx, HelloRequest $in): HelloReply // phpcs:ignore
+    {
+        $command = new ExampleCommand($in->getName());
+
+        $reply = new HelloReply();
+        $reply->setMessage(CommandBus::handle($command));
+
+        return $reply;
+    }
+}

src/Helpers/Env.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Helpers;
+
+/**
+ * Class Env
+ * @package Siteworxpro\App\Helpers
+ */
+abstract class Env
+{
+    /**
+     * @param string $key
+     * @param null $default
+     * @param string $castTo
+     * @return float|bool|int|string
+     */
+    public static function get(string $key, $default = null, string $castTo = 'string'): float | bool | int | string
+    {
+        $env = getenv($key) !== false ? getenv($key) : $default;
+
+        return match ($castTo) {
+            'bool', 'boolean' => (bool) $env,
+            'int', 'integer' => (int) $env,
+            'float' => (float) $env,
+            default => (string) $env,
+        };
+    }
+}

src/Helpers/Ulid.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Helpers;
+
+/**
+ * Class Ulid
+ * @package Siteworxpro\App\Helpers
+ */
+class Ulid
+{
+    /**
+     * Generate a ULID string
+     *
+     * @return string
+     */
+    public static function generate(): string
+    {
+        return \Ulid\Ulid::generate()->getRandomness();
+    }
+}

src/Helpers/Version.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Helpers;
+
+class Version
+{
+    public const string VERSION = 'dev-master';
+}

src/Http/JsonResponseFactory.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Http;
+
+use Illuminate\Contracts\Support\Arrayable;
+use Nyholm\Psr7\Response;
+use Siteworxpro\HttpStatus\CodesEnum;
+
+/**
+ * Class JsonResponseFactory
+ *
+ * A factory class for creating JSON responses.
+ */
+class JsonResponseFactory
+{
+    /**
+     * Create a JSON response with the given data and status code.
+     *
+     * @param array|Arrayable $data The data to include in the response.
+     * @param CodesEnum $statusCode The HTTP status code for the response.
+     * @return Response The JSON response.
+     * @throws \JsonException
+     */
+    public static function createJsonResponse(
+        array|Arrayable $data,
+        CodesEnum $statusCode = CodesEnum::OK
+    ): Response {
+        if ($data instanceof Arrayable) {
+            $data = $data->toArray();
+        }
+
+        return new Response(
+            status: $statusCode->value,
+            headers: [
+                'Content-Type' => 'application/json',
+            ],
+            body: json_encode($data, JSON_THROW_ON_ERROR)
+        );
+    }
+}

src/Http/Middleware/CorsMiddleware.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Http\Middleware;
+
+use Nyholm\Psr7\Response;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use Siteworxpro\App\Services\Facades\Config;
+
+/**
+ * Class CorsMiddleware
+ *
+ * Middleware to handle CORS (Cross-Origin Resource Sharing) requests.
+ * It checks the origin of the request and sets appropriate CORS headers
+ * in the response.
+ */
+class CorsMiddleware implements MiddlewareInterface
+{
+    /**
+     * Process the incoming request and add CORS headers to the response.
+     *
+     * @param ServerRequestInterface $request The incoming request.
+     * @param RequestHandlerInterface $handler The request handler.
+     * @return ResponseInterface The response with CORS headers.
+     */
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
+    {
+        $origin = $request->getHeaderLine('Origin');
+        $allowedOrigins = array_map(
+            'trim',
+            explode(
+                ',',
+                Config::get('cors.allowed_origins')
+            )
+        );
+
+        $allowOrigin = in_array($origin, $allowedOrigins, true)
+            ? $origin
+            : null;
+
+        if ($request->getMethod() === 'OPTIONS') {
+            $response = new Response(204);
+        } else {
+            $response = $handler->handle($request);
+        }
+
+        if ($allowOrigin === null) {
+            return $response; // Do not add CORS headers if origin is not allowed.
+        }
+
+        $response = $response
+            ->withHeader('Access-Control-Allow-Origin', $allowOrigin)
+            ->withHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS')
+            ->withHeader(
+                'Access-Control-Allow-Headers',
+                $request->getHeaderLine('Access-Control-Request-Headers')
+                    ?: 'Content-Type, Authorization'
+            );
+
+        if (Config::get('cors.allow_credentials') === true) {
+            $response = $response->withHeader('Access-Control-Allow-Credentials', 'true');
+        }
+
+        $maxAge = Config::get('cors.max_age') ?: '86400'; // Use correct configuration key.
+
+        return $response->withHeader('Access-Control-Max-Age', $maxAge);
+    }
+}

src/Http/Middleware/JwtMiddleware.php

@@ -0,0 +1,322 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Http\Middleware;
+
+use Carbon\Carbon;
+use Carbon\WrapperClock;
+use GuzzleHttp\Exception\GuzzleException;
+use Lcobucci\JWT\JwtFacade;
+use Lcobucci\JWT\Signer\Hmac\Sha256 as Hmac256;
+use Lcobucci\JWT\Signer\Key;
+use Lcobucci\JWT\Signer\Key\InMemory;
+use Lcobucci\JWT\Signer\Rsa\Sha256;
+use Lcobucci\JWT\Token\InvalidTokenStructure;
+use Lcobucci\JWT\Validation\Constraint\IssuedBy;
+use Lcobucci\JWT\Validation\Constraint\LooseValidAt;
+use Lcobucci\JWT\Validation\Constraint\PermittedFor;
+use Lcobucci\JWT\Validation\Constraint\SignedWith;
+use Lcobucci\JWT\Validation\Constraint\StrictValidAt;
+use Lcobucci\JWT\Validation\RequiredConstraintsViolated;
+use League\Route\Dispatcher;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use Siteworxpro\App\Attributes\Guards\Jwt;
+use Siteworxpro\App\Controllers\Controller;
+use Siteworxpro\App\Http\JsonResponseFactory;
+use Siteworxpro\App\Services\Facades\Config;
+use Siteworxpro\App\Services\Facades\Guzzle;
+use Siteworxpro\App\Services\Facades\Redis;
+use Siteworxpro\HttpStatus\CodesEnum;
+
+/**
+ * JWT authorization middleware.
+ *
+ * Applies JWT validation to controller actions annotated with `Jwt` attribute.
+ * Flow:
+ * - Resolve the targeted controller and method for the current route.
+ * - If the method has `Jwt`, read the `Authorization` header and parse the Bearer token.
+ * - Validate signature, time constraints, issuer\(\) and audience\(\) based on attribute and config.
+ * - On success, attach all token claims to the request as attributes.
+ * - On failure, return a 401 JSON response with validation errors.
+ *
+ * Configuration:
+ * - `jwt.signing_key`: key material or `file://` path to key.
+ * - `jwt.strict_validation`: bool toggling strict vs loose time validation.
+ */
+class JwtMiddleware extends Middleware
+{
+    /**
+     * Process the incoming request.
+     *
+     * If the matched controller method is annotated with `Jwt`, validates the token and
+     * augments the request with claims on success. Otherwise, just delegates to the next handler.
+     *
+     * @param ServerRequestInterface $request PSR-7 request instance.
+     * @param RequestHandlerInterface|Dispatcher $handler Next middleware or route dispatcher.
+     *
+     * @return ResponseInterface Response produced by the next handler or a 401 JSON response.
+     *
+     * @throws \JsonException On JSON error response encoding issues.
+     * @throws \Exception On unexpected reflection or JWT parsing issues.
+     */
+    public function process(
+        ServerRequestInterface $request,
+        RequestHandlerInterface|Dispatcher $handler
+    ): ResponseInterface {
+
+        // Resolve the callable \[Controller, method] for the current route.
+        $callable = $this->extractRouteCallable($handler);
+        if ($callable === null) {
+            return $handler->handle($request);
+        }
+
+        /** @var Controller $class */
+        [$class, $method] = $callable;
+
+        if (class_exists($class::class)) {
+            $reflectionClass = new \ReflectionClass($class);
+
+            if ($reflectionClass->hasMethod($method)) {
+                $reflectionMethod = $reflectionClass->getMethod($method);
+                // Read `Jwt` attribute on the controller method.
+                $attributes = $reflectionMethod->getAttributes(Jwt::class);
+
+                // If no `Jwt` attribute, do not enforce auth here.
+                if (empty($attributes)) {
+                    return $handler->handle($request);
+                }
+
+                // Extract Bearer token from Authorization header.
+                $token = str_replace('Bearer ', '', $request->getHeaderLine('Authorization'));
+
+                if (empty($token)) {
+                    return JsonResponseFactory::createJsonResponse([
+                        'status_code' => 401,
+                        'message' => 'Unauthorized: Missing token',
+                    ], CodesEnum::UNAUTHORIZED);
+                }
+
+                // Aggregate required issuers and audience from attributes.
+                $requiredIssuers = [];
+                $requiredAudience = '';
+
+                foreach ($attributes as $attribute) {
+                    /** @var Jwt $jwtInstance */
+                    $jwtInstance = $attribute->newInstance();
+
+                    if ($jwtInstance->getAudience() !== '') {
+                        $requiredAudience = $jwtInstance->getAudience();
+                    }
+
+                    $requiredIssuers[] = $jwtInstance->getIssuer();
+                }
+
+                try {
+                    // Parse and validate the token with signature, time, issuer and audience constraints.
+                    $jwt = new JwtFacade()->parse(
+                        $token,
+                        $this->getSignedWith($token),
+                        Config::get('jwt.strict_validation') ?
+                            new StrictValidAt(new WrapperClock(Carbon::now())) :
+                            new LooseValidAt(new WrapperClock(Carbon::now())),
+                        new IssuedBy(...$requiredIssuers),
+                        new PermittedFor($requiredAudience)
+                    );
+                } catch (RequiredConstraintsViolated $exception) {
+                    // Collect human-readable violations to return to the client.
+                    $violations = [];
+                    foreach ($exception->violations() as $violation) {
+                        $violations[] = $violation->getMessage();
+                    }
+
+                    return JsonResponseFactory::createJsonResponse([
+                        'status_code' => CodesEnum::UNAUTHORIZED->value,
+                        'message' => 'Unauthorized: Invalid token',
+                        'errors' => $violations
+                    ], CodesEnum::UNAUTHORIZED);
+                } catch (InvalidTokenStructure) {
+                    // Token could not be parsed due to malformed structure.
+                    return JsonResponseFactory::createJsonResponse([
+                        'status_code' => CodesEnum::UNAUTHORIZED->value,
+                        'message' => 'Unauthorized: Invalid token',
+                    ], CodesEnum::UNAUTHORIZED);
+                } catch (GuzzleException | \RuntimeException) {
+                    return JsonResponseFactory::createJsonResponse([
+                        'status_code' => CodesEnum::INTERNAL_SERVER_ERROR->value,
+                        'message' => 'Token validation service unavailable or unknown error',
+                    ], CodesEnum::INTERNAL_SERVER_ERROR);
+                }
+
+                // Expose all token claims as request attributes for downstream consumers.
+                foreach ($jwt->claims()->all() as $item => $value) {
+                    $request = $request->withAttribute($item, $value);
+                }
+            }
+        }
+
+        return $handler->handle($request);
+    }
+
+    /**
+     * Build the signature validation constraint from configured key.
+     *
+     * - If the configured key content includes the string `PUBLIC KEY`, use RSA SHA-256.
+     * - Otherwise assume an HMAC SHA-256 shared secret.
+     * - Supports raw key strings or `file://` paths.
+     *
+     * @return SignedWith Signature constraint used during JWT parsing.
+     *
+     * @throws \RuntimeException When no signing key is configured.
+     * @throws \JsonException
+     */
+    private function getSignedWith(string $token): SignedWith
+    {
+        $keyConfig = Config::get('jwt.signing_key');
+
+        if ($keyConfig === null) {
+            throw new \RuntimeException('JWT signing key is not configured.');
+        }
+
+        // file:// path to key
+        if (str_starts_with($keyConfig, 'file://')) {
+            $key = InMemory::file(substr($keyConfig, 7));
+            // openid jwks url
+        } elseif (str_contains($keyConfig, '.well-known/')) {
+            $jwt = explode('.', $token);
+            if (count($jwt) !== 3) {
+                throw new InvalidTokenStructure('Invalid JWT structure for JWKS key retrieval.');
+            }
+            $header = json_decode(base64_decode($jwt[0]), true, 512, JSON_THROW_ON_ERROR);
+            $keyId = $header['kid'] ?? '0'; // Default to '0' if no kid present
+            $key = $this->getJwksKey($keyConfig, $keyId);
+        } else {
+            $key = InMemory::plainText($keyConfig);
+        }
+
+        // Heuristic: if PEM public key content is detected, use RSA; otherwise use HMAC.
+        if (str_contains($key->contents(), 'PUBLIC KEY')) {
+            return new SignedWith(new Sha256(), $key);
+        }
+
+        return new SignedWith(new Hmac256(), $key);
+    }
+
+    private function getJwksKey(string $url, string $keyId): Key
+    {
+        $cached = Redis::get('jwks_key_' . $keyId);
+        if ($cached !== null) {
+            return InMemory::plainText($cached);
+        }
+
+        $openIdConfig = Guzzle::get($url);
+        $body = json_decode($openIdConfig->getBody()->getContents(), true, JSON_THROW_ON_ERROR);
+        $jwksUri = $body['jwks_uri'] ?? '';
+        if (empty($jwksUri)) {
+            throw new \RuntimeException('JWKS URI not found in OpenID configuration.');
+        }
+
+        $jwksResponse = Guzzle::get($jwksUri);
+        $jwksBody = json_decode(
+            $jwksResponse->getBody()->getContents(),
+            true,
+            JSON_THROW_ON_ERROR
+        );
+
+        // For simplicity, we take the first key in the JWKS.
+        $firstKey = array_filter(
+            $jwksBody['keys'],
+            fn($key) => $key['kid'] === $keyId
+        )[0] ?? $jwksBody['keys'][0] ?? null;
+
+        if (empty($firstKey)) {
+            throw new \RuntimeException('No matching key found in JWKS for key ID: ' . $keyId);
+        }
+
+        $n = $firstKey['n'];
+        $e = $firstKey['e'];
+        $publicKeyPem = "-----BEGIN PUBLIC KEY-----\n" .
+            chunk_split(base64_encode($this->convertJwkToPem($n, $e)), 64) .
+            "-----END PUBLIC KEY-----\n";
+
+        Redis::set('jwks_key_' . $keyId, $publicKeyPem, 'EX', 3600);
+
+        return InMemory::plainText($publicKeyPem);
+    }
+
+    /**
+     * Build a DER-encoded SubjectPublicKeyInfo from JWK 'n' and 'e'.
+     * Returns raw DER bytes; caller base64-encodes and wraps with PEM headers.
+     */
+    private function convertJwkToPem(string $n, string $e): string
+    {
+        $modulus = $this->base64UrlDecode($n);
+        $exponent = $this->base64UrlDecode($e);
+
+        $derN = $this->derEncodeInteger($modulus);
+        $derE = $this->derEncodeInteger($exponent);
+
+        // RSAPublicKey (PKCS#1): SEQUENCE { n INTEGER, e INTEGER }
+        $rsaPublicKey = $this->derEncodeSequence($derN . $derE);
+
+        // AlgorithmIdentifier for rsaEncryption: 1.2.840.113549.1.1.1 with NULL
+        $algId = hex2bin('300d06092a864886f70d0101010500');
+
+        // SubjectPublicKey (SPKI) BIT STRING, 0 unused bits + RSAPublicKey
+        $subjectPublicKey = $this->derEncodeBitString($rsaPublicKey);
+
+        // SubjectPublicKeyInfo: SEQUENCE { algorithm AlgorithmIdentifier, subjectPublicKey BIT STRING }
+        return $this->derEncodeSequence($algId . $subjectPublicKey);
+    }
+
+    private function base64UrlDecode(string $data): string
+    {
+        $data = strtr($data, '-_', '+/');
+        $pad = strlen($data) % 4;
+        if ($pad) {
+            $data .= str_repeat('=', 4 - $pad);
+        }
+        return base64_decode($data);
+    }
+
+    private function derEncodeLength(int $len): string
+    {
+        if ($len < 0x80) {
+            return chr($len);
+        }
+        $bytes = '';
+        while ($len > 0) {
+            $bytes = chr($len & 0xFF) . $bytes;
+            $len >>= 8;
+        }
+        return chr(0x80 | strlen($bytes)) . $bytes;
+    }
+
+    private function derEncodeInteger(string $bytes): string
+    {
+        // Remove leading zeroes
+        $bytes = ltrim($bytes, "\x00");
+        if ($bytes === '') {
+            $bytes = "\x00";
+        }
+        // Ensure positive INTEGER (prepend 0x00 if MSB set)
+        if ((ord($bytes[0]) & 0x80) !== 0) {
+            $bytes = "\x00" . $bytes;
+        }
+        return "\x02" . $this->derEncodeLength(strlen($bytes)) . $bytes;
+    }
+
+    private function derEncodeSequence(string $bytes): string
+    {
+        return "\x30" . $this->derEncodeLength(strlen($bytes)) . $bytes;
+    }
+
+    private function derEncodeBitString(string $bytes): string
+    {
+        // 0 unused bits + data
+        $payload = "\x00" . $bytes;
+        return "\x03" . $this->derEncodeLength(strlen($payload)) . $payload;
+    }
+}

src/Http/Middleware/Middleware.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Http\Middleware;
+
+use League\Route\Dispatcher;
+use League\Route\Route;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+
+/**
+ * Base middleware helper for extracting route callables.
+ *
+ * This abstract middleware provides a utility method to inspect a League\Route
+ * dispatcher and obtain the underlying route callable as a [class, method] tuple.
+ *
+ * @package Siteworxpro\App\Http\Middleware
+ */
+abstract class Middleware implements MiddlewareInterface
+{
+    /**
+     * Extract the route callable [class, method] from a League\Route dispatcher.
+     *
+     * When the provided handler is a League\Route\Dispatcher, this inspects its
+     * middleware stack, looks at the last segment (the resolved Route), and
+     * attempts to normalize its callable into a [class, method] pair.
+     *
+     * Supported callable forms:
+     * - array callable: [object|class-string, method-string]
+     * - string callable: "ClassName::methodName"
+     *
+     * Returns null when the handler is not a Dispatcher, the stack is empty,
+     * or the callable cannot be parsed.
+     *
+     * @param RequestHandlerInterface|Dispatcher $handler The downstream handler or dispatcher.
+     *
+     * @return array{0: class-string|object|null, 1: string|null}|null Tuple of [class|object, method] or null.
+     */
+    protected function extractRouteCallable(
+        RequestHandlerInterface|Dispatcher $handler
+    ): array|null {
+        // Only proceed if this is a League\Route dispatcher.
+        if (!$handler instanceof Dispatcher) {
+            return null;
+        }
+
+        /** @var Route | null $lastSegment */
+        // Retrieve the last middleware in the stack, which should be the Route.
+        $lastSegment = array_last($handler->getMiddlewareStack());
+
+        if ($lastSegment === null) {
+            return null;
+        }
+
+        // Obtain the callable associated with the route.
+        $callable = $lastSegment->getCallable();
+        $class = null;
+        $method = null;
+
+        // Handle array callable: [object|class-string, 'method']
+        if (is_array($callable) && count($callable) === 2) {
+            [$class, $method] = $callable;
+        } elseif (is_string($callable)) {
+            // Handle string callable: 'ClassName::methodName'
+            [$class, $method] = explode('::', $callable);
+        }
+
+        return [$class, $method];
+    }
+}

src/Http/Middleware/ScopeMiddleware.php

@@ -0,0 +1,117 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Http\Middleware;
+
+use League\Route\Dispatcher;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use Siteworxpro\App\Attributes\Guards\RequireAllScopes;
+use Siteworxpro\App\Attributes\Guards\Scope;
+use Siteworxpro\App\Controllers\Controller;
+use Siteworxpro\App\Http\JsonResponseFactory;
+use Siteworxpro\HttpStatus\CodesEnum;
+
+/**
+ * Middleware that enforces scope-based access control on controller actions.
+ *
+ * It inspects PHP 8 attributes of type \`Scope\` applied to the resolved controller method,
+ * compares the required scopes with the user scopes provided on the request attribute \`scopes\`,
+ * and returns a 403 JSON response when any required scope is missing.
+ *
+ * If the route callable cannot be resolved, or no scope is required, the request is passed through.
+ *
+ * @see Scope
+ */
+class ScopeMiddleware extends Middleware
+{
+    /**
+     * Resolve the route callable, read any \`Scope\` attributes, and enforce required scopes.
+     *
+     * Expected user scopes are provided on the request under the attribute name \`scopes\`
+     * as an array of strings.
+     *
+     * @param ServerRequestInterface $request Incoming PSR-7 request (expects \`scopes\` attribute).
+     * @param RequestHandlerInterface|Dispatcher $handler Next handler or League\Route dispatcher.
+     *
+     * @return ResponseInterface A 403 JSON response when scopes are insufficient; otherwise the handler response.
+     *
+     * @throws \JsonException       If encoding the JSON error response fails.
+     * @throws \ReflectionException If reflection on the controller or method fails.
+     */
+    public function process(
+        ServerRequestInterface $request,
+        RequestHandlerInterface|Dispatcher $handler
+    ): ResponseInterface {
+        // Attempt to resolve the route's callable [Controller instance, method name].
+        $callable = $this->extractRouteCallable($handler);
+        if ($callable === null) {
+            // If no callable is available, delegate to the next handler.
+            return $handler->handle($request);
+        }
+
+        /** @var Controller $class Controller instance resolved from the route. */
+        [$class, $method] = $callable;
+
+        // Ensure the controller exists and the method is defined before reflecting.
+        if (class_exists($class::class)) {
+            $reflectionClass = new \ReflectionClass($class);
+
+            if ($reflectionClass->hasMethod($method)) {
+                $reflectionMethod = $reflectionClass->getMethod($method);
+
+                // Fetch all Scope attributes declared on the method.
+                $attributes = $reflectionMethod->getAttributes(Scope::class);
+                $requireAllAttributes = $reflectionMethod->getAttributes(RequireAllScopes::class);
+
+                if (empty($attributes)) {
+                    // No scope attributes; delegate to the next handler.
+                    return $handler->handle($request);
+                }
+
+                $requiredScopes = [];
+                $userScopes = [];
+                $requireAll = false;
+
+                foreach ($attributes as $attribute) {
+                    /** @var Scope $scopeInstance Concrete Scope attribute instance. */
+                    $scopeInstance = $attribute->newInstance();
+                    $requiredScopes = array_merge($requiredScopes, $scopeInstance->getScopes());
+
+                    // If any attribute requires all scopes, set the flag.
+                    $requireAll = $requireAll || !empty($requireAllAttributes);
+
+                    $scopes = $request->getAttribute($scopeInstance->getClaim());
+                    if (!is_array($scopes)) {
+                        // If user scopes are not an array, treat as no scopes provided.
+                        $scopes = explode($scopeInstance->getSeparator(), (string) $scopes);
+                    }
+
+                    $userScopes = array_merge(
+                        $userScopes,
+                        $scopes
+                    );
+                }
+
+                $userScopes = array_unique($userScopes);
+
+                // Deny if any required scope is missing from the user's scopes.
+                if (
+                    (!$requireAll && array_intersect($userScopes, $requiredScopes) === []) ||
+                    ($requireAll && array_diff($requiredScopes, $userScopes) !== [])
+                ) {
+                    return JsonResponseFactory::createJsonResponse([
+                        'error' => 'insufficient_scope',
+                        'error_description' =>
+                            'The request requires higher privileges than provided by the access token.'
+                    ], CodesEnum::FORBIDDEN);
+                }
+            }
+        }
+
+        // All checks passed; continue down the middleware pipeline.
+        return $handler->handle($request);
+    }
+}

src/Http/Responses/GenericResponse.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Http\Responses;
+
+use Illuminate\Contracts\Support\Arrayable;
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'GenericResponse',
+    properties: [
+        new OA\Property(property: 'message', type: 'string', example: 'Operation completed successfully.'),
+    ]
+)]
+readonly class GenericResponse implements Arrayable
+{
+    public function __construct(
+        private string $message = '',
+    ) {
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'message' => $this->message,
+        ];
+    }
+}

src/Http/Responses/NotFoundResponse.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Siteworxpro\App\Http\Responses;
+
+use Illuminate\Contracts\Support\Arrayable;
+use Siteworxpro\HttpStatus\CodesEnum;
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'NotFoundResponse',
+    properties: [
+        new OA\Property(
+            property: 'message',
+            type: 'string',
+            example: 'The requested resource /api/resource was not found.'
+        ),
+        new OA\Property(
+            property: 'context',
+            description: 'Additional context about the not found error.',
+            type: 'object',
+            example: '{}'
+        ),
+    ]
+)]
+readonly class NotFoundResponse implements Arrayable
+{
+    public function __construct(private string $uri, private array $context = [])
+    {
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'message' => 'The requested resource ' . $this->uri . ' was not found.',
+            'context' => $this->context,
+        ];
+    }
+}

src/Http/Responses/ServerErrorResponse.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Siteworxpro\App\Http\Responses;
+
+use Illuminate\Contracts\Support\Arrayable;
+use Siteworxpro\App\Services\Facades\Config;
+use Siteworxpro\HttpStatus\CodesEnum;
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'ServerErrorResponse',
+    properties: array(
+        new OA\Property(property: 'message', type: 'string', example: 'An internal server error occurred.'),
+        new OA\Property(property: 'code', type: 'integer', example: 500),
+        new OA\Property(
+            property: 'file',
+            type: 'string',
+            example: '/var/www/html/app/Http/Controllers/ExampleController.php'
+        ),
+        new OA\Property(property: 'line', type: 'integer', example: 42),
+        new OA\Property(
+            property: 'trace',
+            type: 'array',
+            items: new OA\Items(type: 'string'),
+        )
+    )
+)]
+readonly class ServerErrorResponse implements Arrayable
+{
+    public function __construct(private \Throwable $e, private array $context = [])
+    {
+    }
+
+    public function toArray(): array
+    {
+        if (Config::get('app.dev_mode')) {
+            return [
+                'code' => $this->e->getCode() != 0 ?
+                    $this->e->getCode() :
+                    CodesEnum::INTERNAL_SERVER_ERROR->value,
+                'message' => $this->e->getMessage(),
+                'file' => $this->e->getFile(),
+                'line' => $this->e->getLine(),
+                'trace' => $this->e->getTrace(),
+                'context' => $this->context,
+            ];
+        }
+
+        return [
+            'code' => $this->e->getCode() != 0 ?
+                $this->e->getCode() :
+                CodesEnum::INTERNAL_SERVER_ERROR->value,
+            'message' => 'An internal server error occurred.',
+        ];
+    }
+}

src/Kernel.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace Siteworxpro\App;
+
+use Illuminate\Container\Container;
+use Illuminate\Database\Capsule\Manager;
+use Illuminate\Support\ServiceProvider;
+use Siteworx\Config\Config as SWConfig;
+use Siteworxpro\App\Services\Facade;
+use Siteworxpro\App\Services\Facades\Config;
+use Siteworxpro\App\Services\Facades\Dispatcher;
+use Siteworxpro\App\Services\ServiceProviders\BrokerServiceProvider;
+use Siteworxpro\App\Services\ServiceProviders\CommandBusProvider;
+use Siteworxpro\App\Services\ServiceProviders\DispatcherServiceProvider;
+use Siteworxpro\App\Services\ServiceProviders\LoggerServiceProvider;
+use Siteworxpro\App\Services\ServiceProviders\RedisServiceProvider;
+
+/**
+ * Class Kernel
+ *
+ * The Kernel class is responsible for bootstrapping the application by
+ * initializing service providers and setting up the database connection.
+ *
+ * @package Siteworxpro\App
+ */
+class Kernel
+{
+    /**
+     * List of service providers to be registered during bootstrapping.
+     *
+     * @var array
+     */
+    private static array $serviceProviders = [
+        LoggerServiceProvider::class,
+        RedisServiceProvider::class,
+        DispatcherServiceProvider::class,
+        BrokerServiceProvider::class,
+        CommandBusProvider::class,
+    ];
+
+    /**
+     * Bootstraps the server by initializing the PSR-7 worker and router.
+     *
+     * This method sets up the PSR-7 worker and router instances, and registers
+     * the routes for the server. It should be called in the constructor of
+     * subclasses to ensure proper initialization.
+     *
+     * @return void
+     * @throws \ReflectionException
+     */
+    public static function boot(): void
+    {
+        $container = new Container();
+        Facade::setFacadeContainer($container);
+
+        // Bind the container to the Config facade first so that it can be used by service providers
+        $container->bind(SWConfig::class, function () {
+            return SWConfig::load(__DIR__ . '/../config.php');
+        });
+
+        foreach (self::$serviceProviders as $serviceProvider) {
+            if (class_exists($serviceProvider)) {
+                $provider = new $serviceProvider($container);
+                if ($provider instanceof ServiceProvider) {
+                    $provider->register();
+                } else {
+                    throw new \RuntimeException(sprintf(
+                        'Service provider %s is not an instance of ServiceProvider.',
+                        $serviceProvider
+                    ));
+                }
+            } else {
+                throw new \RuntimeException(sprintf('Service provider %s not found.', $serviceProvider));
+            }
+        }
+
+        self::bootModelCapsule();
+    }
+
+    /**
+     * Bootstraps the model capsule for database connections.
+     *
+     * This method sets up the database connection using the Eloquent ORM.
+     * It retrieves the database configuration from the Config facade and
+     * initializes the Eloquent capsule manager.
+     *
+     * @return void
+     */
+    private static function bootModelCapsule(): void
+    {
+        $capsule = new Manager();
+        $capsule->setEventDispatcher(Dispatcher::getFacadeRoot());
+        $capsule->addConnection(Config::get('db'));
+        $capsule->setAsGlobal();
+        $capsule->bootEloquent();
+    }
+}

src/Log/Logger.php

@@ -0,0 +1,236 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Log;
+
+use Monolog\Formatter\JsonFormatter;
+use Monolog\Handler\StreamHandler;
+use Psr\Container\ContainerExceptionInterface;
+use Psr\Container\NotFoundExceptionInterface;
+use Psr\Log\LoggerInterface;
+use Psr\Log\LogLevel;
+use RoadRunner\Logger\Logger as RRLogger;
+use Siteworxpro\App\Services\Facades\RoadRunnerLogger;
+
+/**
+ * Logger implementation that conforms to PSR-3 (`Psr\Log\LoggerInterface`).
+ *
+ * Behavior:
+ * - If environment indicates RoadRunner RPC (`$_SERVER['RR_RPC']`), logs are forwarded
+ *   to a RoadRunner RPC logger (`RoadRunner\Logger\Logger`) created via Goridge RPC.
+ * - Otherwise, logs are written to `php://stdout` using Monolog with a JSON formatter.
+ * - Messages below the configured threshold are ignored (level filtering).
+ *
+ * Supported PSR-3 levels are mapped to an internal numeric ordering in `$levels`.
+ * When using the RPC logger, levels are translated to the respective RPC methods
+ * (debug, info, warning, error). When using Monolog, the numeric mapping is used
+ * as the numeric level passed to Monolog's `log` method.
+ */
+class Logger implements LoggerInterface
+{
+    /**
+     * RoadRunner RPC logger instance when running under RoadRunner.
+     *
+     * @var RRLogger | LoggerInterface | null
+     */
+    private RRLogger | LoggerInterface | null $rpcLogger = null;
+
+    /**
+     * Monolog logger used as a fallback to write JSON-formatted logs to stdout.
+     *
+     * @var \Monolog\Logger
+     */
+    private \Monolog\Logger $monologLogger;
+
+    /**
+     * Numeric ordering for PSR-3 log levels.
+     *
+     * Lower numbers represent higher severity. This mapping is used for filtering
+     * messages according to the configured minimum level and for Monolog numeric level.
+     *
+     * @var array<string,int>
+     */
+    private array $levels = [
+        LogLevel::EMERGENCY => 0,
+        LogLevel::ALERT     => 1,
+        LogLevel::CRITICAL  => 2,
+        LogLevel::ERROR     => 3,
+        LogLevel::WARNING   => 4,
+        LogLevel::NOTICE    => 5,
+        LogLevel::INFO      => 6,
+        LogLevel::DEBUG     => 7,
+    ];
+
+    /**
+     * Create a new Logger.
+     *
+     * @param string $level Minimum level to log (PSR-3 level string). Messages with
+     *                      a higher numeric value in `$levels` will be ignored.
+     *
+     * @param resource | null $streamOutput Optional stream handler for Monolog.
+     *
+     * The default is `LogLevel::DEBUG` (log everything).
+     *
+     * If `$_SERVER['RR_RPC']` is set, an RPC connection will be attempted at
+     *  $_SERVER['RR_RPC'] and a RoadRunner RPC logger will be used.
+     *
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public function __construct(
+        private readonly string $level = LogLevel::DEBUG,
+        $streamOutput = null,
+    ) {
+        if (isset($_SERVER['RR_RPC'])) {
+            $this->rpcLogger = RoadRunnerLogger::getFacadeRoot();
+        }
+
+        $this->monologLogger = new \Monolog\Logger('app_logger');
+        $formatter = new JsonFormatter();
+        $stream = $streamOutput ?? 'php://stdout';
+        $this->monologLogger->pushHandler(new StreamHandler($stream)->setFormatter($formatter));
+    }
+
+    /**
+     * System is unusable.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
+    public function emergency(\Stringable|string $message, array $context = []): void
+    {
+        $this->log(LogLevel::EMERGENCY, $message, $context);
+    }
+
+    /**
+     * Action must be taken immediately.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
+    public function alert(\Stringable|string $message, array $context = []): void
+    {
+        $this->log(LogLevel::ALERT, $message, $context);
+    }
+
+    /**
+     * Critical conditions.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
+    public function critical(\Stringable|string $message, array $context = []): void
+    {
+        $this->log(LogLevel::CRITICAL, $message, $context);
+    }
+
+    /**
+     * Runtime errors that do not require immediate action but should typically be logged and monitored.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
+    public function error(\Stringable|string $message, array $context = []): void
+    {
+        $this->log(LogLevel::ERROR, $message, $context);
+    }
+
+    /**
+     * Exceptional occurrences that are not errors.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
+    public function warning(\Stringable|string $message, array $context = []): void
+    {
+        $this->log(LogLevel::WARNING, $message, $context);
+    }
+
+    /**
+     * Normal but significant events.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
+    public function notice(\Stringable|string $message, array $context = []): void
+    {
+        $this->log(LogLevel::NOTICE, $message, $context);
+    }
+
+    /**
+     * Interesting events.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
+    public function info(\Stringable|string $message, array $context = []): void
+    {
+        $this->log(LogLevel::INFO, $message, $context);
+    }
+
+    /**
+     * Detailed debug information.
+     *
+     * @param \Stringable|string $message
+     * @param array $context
+     */
+    public function debug(\Stringable|string $message, array $context = []): void
+    {
+        $this->log(LogLevel::DEBUG, $message, $context);
+    }
+
+    /**
+     * Logs with an arbitrary level.
+     *
+     * Behavior details:
+     * - If the provided `$level` maps to a numeric value greater than the configured
+     *   minimum level, the message is discarded (filtered).
+     * - If an RPC logger is available, the message is forwarded to the RPC logger
+     *   using a method chosen by level (debug, info, warning, error).
+     * - Otherwise, the message is written to Monolog using the numeric mapping.
+     *
+     * Notes:
+     * - `$level` should be a PSR-3 level string (values defined in `Psr\Log\LogLevel`).
+     * - If an unknown level string is passed, accessing `$this->levels[$level]` may
+     *   trigger a PHP notice or undefined index. Ensure callers use valid PSR-3 levels.
+     *
+     * @param mixed $level PSR-3 log level (string)
+     * @param \Stringable|string $message
+     * @param array $context
+     */
+    public function log($level, \Stringable|string $message, array $context = []): void
+    {
+        if (isset($this->levels[$level]) && $this->levels[$level] > $this->levels[$this->level]) {
+            return;
+        }
+
+        if ($this->rpcLogger) {
+            switch ($level) {
+                case LogLevel::DEBUG:
+                    $this->rpcLogger->debug((string)$message, $context);
+                    break;
+                case LogLevel::NOTICE:
+                case LogLevel::INFO:
+                    $this->rpcLogger->info((string)$message, $context);
+                    break;
+                case LogLevel::WARNING:
+                    $this->rpcLogger->warning((string)$message, $context);
+                    break;
+                case LogLevel::CRITICAL:
+                case LogLevel::ERROR:
+                case LogLevel::ALERT:
+                case LogLevel::EMERGENCY:
+                    $this->rpcLogger->error((string)$message, $context);
+                    break;
+                default:
+                    $this->rpcLogger->log($level, (string)$message, $context);
+                    break;
+            }
+
+            return;
+        }
+
+        $this->monologLogger->log($this->levels[$level], (string)$message, $context);
+    }
+}

src/Models/Model.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Models;
+
+use Illuminate\Database\Eloquent\Model as ORM;
+
+/**
+ * Class Model
+ *
+ * @package Siteworxpro\App\Models
+ */
+abstract class Model extends ORM
+{
+    protected $dateFormat = 'Y-m-d H:i:s';
+}

src/Models/User.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Models;
+
+use Carbon\Carbon;
+use OpenApi\Attributes as OA;
+use Siteworxpro\App\Helpers\Ulid;
+
+/**
+ * Class User
+ *
+ * @property-read string $id
+ * @property string $first_name
+ * @property string $last_name
+ * @property string $email
+ * @property string $password
+ * @property Carbon $created_at
+ *
+ * @property-read string $full_name
+ * @property-read string $formatted_email
+ */
+#[OA\Schema(
+    schema: "User",
+    properties: [
+        new OA\Property(
+            property: "id",
+            description: "Unique identifier for the user",
+            type: "string",
+            format: "ulid",
+            readOnly: true,
+            example: '01KBD5WPZKYD77BYM2QD9NKG99'
+        ),
+        new OA\Property(property: "first_name", type: "string"),
+        new OA\Property(property: "last_name", type: "string"),
+        new OA\Property(property: "email", type: "string", format: "email"),
+        new OA\Property(property: "created_at", type: "string", format: "date-time"),
+    ]
+)]
+class User extends Model
+{
+    protected $casts = [
+        'created_at' => 'datetime',
+    ];
+
+    protected $hidden = [
+        'password',
+    ];
+
+    protected $fillable = [
+        'first_name',
+        'last_name',
+        'email',
+        'password',
+    ];
+
+    public function __construct(array $attributes = [])
+    {
+        parent::__construct($attributes);
+        $this->attributes['id'] = $this->attributes['id'] ?? Ulid::generate();
+    }
+
+    public function getFullNameAttribute(): string
+    {
+        return "$this->first_name $this->last_name";
+    }
+
+    public function getFormattedEmailAttribute(): string
+    {
+        return sprintf(
+            '%s <%s>',
+            $this->getFullNameAttribute(),
+            strtolower($this->email)
+        );
+    }
+}

src/Services/Facade.php

@@ -0,0 +1,278 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services;
+
+use Illuminate\Contracts\Container\Container;
+use Illuminate\Support\HigherOrderTapProxy;
+use Illuminate\Support\Testing\Fakes\Fake;
+use Mockery;
+use Mockery\Expectation;
+use Mockery\ExpectationInterface;
+use Mockery\LegacyMockInterface;
+use Mockery\MockInterface;
+
+class Facade
+{
+    /**
+     * The application instance being facaded.
+     *
+     * @var Container | null
+     */
+    protected static ?Container $container = null;
+
+    /**
+     * The resolved object instances.
+     *
+     * @var array
+     */
+    protected static array $resolvedInstance;
+
+    /**
+     * Indicates if the resolved instance should be cached.
+     *
+     * @var bool
+     */
+    protected static bool $cached = true;
+
+    /**
+     * Run a Closure when the facade has been resolved.
+     *
+     * @param  \Closure  $callback
+     * @return void
+     */
+    public static function resolved(\Closure $callback): void
+    {
+        $accessor = static::getFacadeAccessor();
+
+        if (static::$container->resolved($accessor) === true) {
+            $callback(static::getFacadeRoot(), static::$container);
+        }
+
+        static::$container->afterResolving($accessor, function ($service, $app) use ($callback) {
+            $callback($service, $app);
+        });
+    }
+
+    /**
+     * Initiate a partial mock on the facade.
+     *
+     * @return MockInterface
+     */
+    public static function partialMock(): MockInterface
+    {
+        $name = static::getFacadeAccessor();
+
+        $mock = static::isMock()
+            ? static::$resolvedInstance[$name]
+            : static::createFreshMockInstance();
+
+        return $mock->makePartial();
+    }
+
+    /**
+     * Initiate a mock expectation on the facade.
+     *
+     * @return Expectation|ExpectationInterface
+     */
+    public static function shouldReceive(): Mockery\Expectation | Mockery\ExpectationInterface
+    {
+        $name = static::getFacadeAccessor();
+
+        $mock = static::isMock()
+            ? static::$resolvedInstance[$name]
+            : static::createFreshMockInstance();
+
+        return $mock->shouldReceive(...func_get_args());
+    }
+
+    /**
+     * Initiate a mock expectation on the facade.
+     *
+     * @return Expectation|ExpectationInterface
+     */
+    public static function expects(): Mockery\Expectation | Mockery\ExpectationInterface
+    {
+        $name = static::getFacadeAccessor();
+
+        $mock = static::isMock()
+            ? static::$resolvedInstance[$name]
+            : static::createFreshMockInstance();
+
+        return $mock->expects(...func_get_args());
+    }
+
+    /**
+     * Create a fresh mock instance for the given class.
+     *
+     * @return MockInterface|LegacyMockInterface
+     */
+    protected static function createFreshMockInstance(): MockInterface | LegacyMockInterface
+    {
+        return tap(static::createMock(), function ($mock) {
+            static::swap($mock);
+
+            $mock->shouldAllowMockingProtectedMethods();
+        });
+    }
+
+    /**
+     * Create a fresh mock instance for the given class.
+     *
+     * @return MockInterface
+     */
+    protected static function createMock(): MockInterface
+    {
+        $class = static::getMockableClass();
+
+        return $class ? Mockery::mock($class) : Mockery::mock();
+    }
+
+    /**
+     * Determines whether a mock is set as the instance of the facade.
+     *
+     * @return bool
+     */
+    protected static function isMock(): bool
+    {
+        $name = static::getFacadeAccessor();
+
+        return isset(static::$resolvedInstance[$name]) &&
+            static::$resolvedInstance[$name] instanceof LegacyMockInterface;
+    }
+
+    /**
+     * Get the mockable class for the bound instance.
+     *
+     * @return string|null
+     */
+    protected static function getMockableClass(): ?string
+    {
+        if ($root = static::getFacadeRoot()) {
+            return get_class($root);
+        }
+
+        return null;
+    }
+
+    /**
+     * Hotswap the underlying instance behind the facade.
+     *
+     * @param  mixed  $instance
+     * @return void
+     */
+    public static function swap(mixed $instance): void
+    {
+        static::$resolvedInstance[static::getFacadeAccessor()] = $instance;
+
+        if (isset(static::$container)) {
+            static::$container->instance(static::getFacadeAccessor(), $instance);
+        }
+    }
+
+    /**
+     * Get the root object behind the facade.
+     *
+     * @return mixed
+     */
+    public static function getFacadeRoot(): mixed
+    {
+        return static::resolveFacadeInstance(static::getFacadeAccessor());
+    }
+
+    /**
+     * Get the registered name of the component.
+     *
+     * @return string
+     *
+     * @throws \RuntimeException
+     */
+    protected static function getFacadeAccessor(): string
+    {
+        throw new \RuntimeException('Facade does not implement getFacadeAccessor method.');
+    }
+
+    /**
+     * Resolve the facade root instance from the container.
+     *
+     * @param string $name
+     * @return mixed
+     */
+    protected static function resolveFacadeInstance(string $name): mixed
+    {
+        if (isset(static::$resolvedInstance[$name])) {
+            return static::$resolvedInstance[$name];
+        }
+
+        if (static::$container) {
+            if (static::$cached) {
+                return static::$resolvedInstance[$name] = static::$container[$name];
+            }
+
+            return static::$container[$name];
+        }
+
+        return null;
+    }
+
+    /**
+     * Clear a resolved facade instance.
+     *
+     * @param string $name
+     * @return void
+     */
+    public static function clearResolvedInstance(string $name): void
+    {
+        unset(static::$resolvedInstance[$name]);
+    }
+
+    /**
+     * Clear all of the resolved instances.
+     *
+     * @return void
+     */
+    public static function clearResolvedInstances(): void
+    {
+        static::$resolvedInstance = [];
+    }
+
+    /**
+     * Get the application instance behind the facade.
+     */
+    public static function getFacadeContainer(): ?Container
+    {
+        return static::$container;
+    }
+
+    /**
+     * Set the application instance.
+     *
+     * @param Container | null $container
+     * @return void
+     */
+    public static function setFacadeContainer(Container | null $container): void
+    {
+        static::$container = $container;
+    }
+
+    /**
+     * Handle dynamic, static calls to the object.
+     *
+     * @param string $method
+     * @param array $args
+     * @return mixed
+     *
+     * @throws \RuntimeException
+     */
+    public static function __callStatic(string $method, array $args)
+    {
+        $instance = static::getFacadeRoot();
+
+        if (! $instance) {
+            throw new \RuntimeException('A facade root has not been set.');
+        }
+
+        return $instance->$method(...$args);
+    }
+}

src/Services/Facades/Broker.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\Facades;
+
+use Siteworxpro\App\Async\Messages\Message;
+use Siteworxpro\App\Async\Queues\Queue;
+use Siteworxpro\App\Services\Facade;
+
+/**
+ * Broker Facade
+ *
+ * @method static void publish(Queue $queue, Message $message, int $delay = 0)
+ * @method static void publishLater(Queue $queue, Message $message, int $delay)
+ * @method static Message|null consume(Queue $queue)
+ */
+class Broker extends Facade
+{
+    /**
+     * Get the registered name of the component.
+     *
+     * @return string The name of the component.
+     */
+    protected static function getFacadeAccessor(): string
+    {
+        return \Siteworxpro\App\Async\Brokers\Broker::class;
+    }
+}

src/Services/Facades/CommandBus.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\Facades;
+
+use Siteworxpro\App\CommandBus\Commands\Command;
+use Siteworxpro\App\Services\Facade;
+
+/**
+ * Broker Facade
+ *
+ * @package Siteworxpro\App\Services\Facades
+ * @method static mixed handle(Command $command)
+ */
+class CommandBus extends Facade
+{
+    /**
+     * Get the registered name of the component.
+     *
+     * @return string The name of the component.
+     */
+    protected static function getFacadeAccessor(): string
+    {
+        return \League\Tactician\CommandBus::class;
+    }
+}

src/Services/Facades/Config.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\Facades;
+
+use Siteworx\Config\Config as SwConfig;
+use Siteworxpro\App\Services\Facade;
+
+/**
+ * Class Config
+ *
+ * This class serves as a facade for the configuration settings of the application.
+ * It extends the Facade class from the Illuminate\Support\Facades namespace.
+ *
+ * @method static array | bool | string | int | null  get(string $key) Retrieve the configuration value for the given key. // @codingStandardsIgnoreStart
+ * @method static void                             set(string $key, mixed $value) Set the configuration value for the given key. // @codingStandardsIgnoreEnd
+ *
+ * @package Siteworx\App\Facades
+ */
+class Config extends Facade
+{
+    /**
+     * Get the registered name of the component.
+     *
+     * @return string The name of the component.
+     */
+    protected static function getFacadeAccessor(): string
+    {
+        return SwConfig::class;
+    }
+}

src/Services/Facades/Dispatcher.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\Facades;
+
+use Siteworxpro\App\Events\Dispatcher as DispatcherConcrete;
+use Siteworxpro\App\Services\Facade;
+
+/**
+ * Class Dispatcher
+ *
+ * A facade for the event dispatcher.
+ *
+ * @package Siteworxpro\App\Services\Facades
+ *
+ * @method static void listen(string $event, callable|string $listener)
+ * @method static void dispatch(object|string $event, array $payload = [], bool $halt = false)
+ * @method static void push(object|string $event, array $payload = [])
+ * @method static array|null until(object|string $event, array $payload = [])
+ * @method static bool hasListeners(string $eventName)
+ * @method static void subscribe(mixed $subscriber)
+ */
+class Dispatcher extends Facade
+{
+    /**
+     * Get the registered name of the component.
+     *
+     * @return string The name of the component.
+     */
+    protected static function getFacadeAccessor(): string
+    {
+        return DispatcherConcrete::class;
+    }
+}

src/Services/Facades/Guzzle.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\Facades;
+
+use GuzzleHttp\Client;
+use GuzzleHttp\Promise\PromiseInterface;
+use GuzzleHttp\Psr7\Response;
+use Siteworxpro\App\Services\Facade;
+
+/**
+ * @method static Response get(string $uri, array $options = [])
+ * @method static Response post(string $uri, array $options = [])
+ * @method static Response put(string $uri, array $options = [])
+ * @method static Response delete(string $uri, array $options = [])
+ * @method static Response patch(string $uri, array $options = [])
+ * @method static Response head(string $uri, array $options = [])
+ * @method static PromiseInterface sendAsync(\Psr\Http\Message\RequestInterface $request, array $options = [])
+ * @method static PromiseInterface requestAsync(string $method, string $uri, array $options = [])
+ */
+class Guzzle extends Facade
+{
+    protected static function getFacadeAccessor(): string
+    {
+        return Client::class;
+    }
+}

src/Services/Facades/Logger.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\Facades;
+
+use Siteworxpro\App\Services\Facade;
+
+/**
+ * Class Logger
+ *
+ * This class serves as a facade for the Monolog logger.
+ * It extends the Facade class from the Illuminate\Support\Facades namespace.
+ *
+ * @method static debug(\Stringable|string $message, array $context = []) Log an informational message.
+ * @method static info(\Stringable|string $message, array $context = []) Log an informational message.
+ * @method static error(\Stringable|string $message, array $context = []) Log an error message.
+ * @method static warning(\Stringable|string $message, array $context = []) Log a warning message.
+ * @method static critical(\Stringable|string $message, array $context = []) Log a critical error message.
+ * @method static alert(\Stringable|string $message, array $context = []) Log an alert message.
+ * @method static emergency(\Stringable|string $message, array $context = []) Log an emergency message.
+ *
+ * @package Siteworxpro\App\Facades
+ */
+class Logger extends Facade
+{
+    /**
+     * Get the registered name of the component.
+     *
+     * @return string The name of the component.
+     */
+    protected static function getFacadeAccessor(): string
+    {
+        return \Siteworxpro\App\Log\Logger::class;
+    }
+}

src/Services/Facades/Redis.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\Facades;
+
+use Predis\Client;
+use Predis\Response\Status;
+use Siteworxpro\App\Services\Facade;
+
+/**
+ * Facade for the Redis client.
+ *
+ * This class provides a static interface to interact with the Redis client.
+ *
+ * @method static array scan($cursor, ?array $options = null)
+ * @method static string|null get(string $key)
+ * @method static Status|null set(string $key, $value, $expireResolution = null, $expireTTL = null, $flag = null)
+ * @method static array keys(string $pattern)
+ * @method static int del(string $key)
+ * @method static Status ping()
+ */
+class Redis extends Facade
+{
+    /**
+     * Get the registered name of the component.
+     *
+     * @return string The name of the component.
+     */
+    protected static function getFacadeAccessor(): string
+    {
+        return Client::class;
+    }
+}

src/Services/Facades/RoadRunnerLogger.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\Facades;
+
+use Psr\Container\ContainerExceptionInterface;
+use Psr\Container\NotFoundExceptionInterface;
+use RoadRunner\Logger\Logger;
+use Siteworxpro\App\Services\Facade;
+use Spiral\Goridge\RPC\RPC;
+
+class RoadRunnerLogger extends Facade
+{
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    public static function getFacadeRoot(): mixed
+    {
+        $container = static::getFacadeContainer();
+        if ($container && $container->has(Logger::class) === false) {
+            $rpc = RPC::create($_SERVER['RR_RPC']);
+            $logger = new Logger($rpc);
+            $container->bind(static::getFacadeAccessor(), function () use ($logger) {
+                return $logger;
+            });
+
+            return $logger;
+        }
+
+        return $container->get(Logger::class);
+    }
+
+    protected static function getFacadeAccessor(): string
+    {
+        return Logger::class;
+    }
+}

src/Services/ServiceProviders/BrokerServiceProvider.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\ServiceProviders;
+
+use Illuminate\Support\ServiceProvider;
+use Siteworxpro\App\Async\Brokers\Broker;
+use Siteworxpro\App\Async\Brokers\Kafka;
+use Siteworxpro\App\Async\Brokers\RabbitMQ;
+use Siteworxpro\App\Async\Brokers\Redis;
+use Siteworxpro\App\Async\Brokers\Sqs;
+use Siteworxpro\App\Services\Facades\Config;
+
+/**
+ * Class BrokerServiceProvider
+ *
+ * This service provider is responsible for binding the Broker implementation
+ * to the Laravel service container based on configuration settings.
+ *
+ * @package Siteworxpro\App\Services\ServiceProviders
+ */
+class BrokerServiceProvider extends ServiceProvider
+{
+    public function provides(): array
+    {
+        return [Kafka::class, RabbitMQ::class, Redis::class, Sqs::class];
+    }
+
+    /**
+     * Register services.
+     *
+     * This method binds the Broker interface to a specific implementation
+     * based on the configuration defined in 'queue.broker' and 'queue.broker_config'.
+     *
+     * @return void
+     * @throws \RuntimeException if the specified broker class does not exist.
+     */
+    public function register(): void
+    {
+        $this->app->singleton(Broker::class, function (): Broker {
+            $configName = Config::get('queue.broker');
+            $brokerConfig = Config::get('queue.broker_config.' . $configName) ?? [];
+
+            $brokerClass = Broker::BROKER_TYPES[$configName] ?? null;
+
+            if ($brokerClass && class_exists($brokerClass)) {
+                return new $brokerClass($brokerConfig);
+            }
+
+            throw new \RuntimeException("Broker class $brokerClass does not exist.");
+        });
+    }
+}

src/Services/ServiceProviders/CommandBusProvider.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\ServiceProviders;
+
+use Illuminate\Support\ServiceProvider;
+use League\Tactician\CommandBus;
+use League\Tactician\Handler\CommandHandlerMiddleware;
+use League\Tactician\Handler\CommandNameExtractor\ClassNameExtractor;
+use League\Tactician\Handler\MethodNameInflector\InvokeInflector;
+use Siteworxpro\App\CommandBus\AttributeLocator;
+
+/**
+ * Class CommandBusProvider
+ *
+ * @package Siteworxpro\App\Services\ServiceProviders
+ */
+class CommandBusProvider extends ServiceProvider
+{
+    public function provides(): array
+    {
+        return [CommandBus::class];
+    }
+
+    public function register(): void
+    {
+        $this->app->singleton(CommandBus::class, function () {
+            return new CommandBus([
+                new CommandHandlerMiddleware(
+                    new ClassNameExtractor(),
+                    new AttributeLocator(),
+                    new InvokeInflector()
+                ),
+            ]);
+        });
+    }
+}

src/Services/ServiceProviders/DispatcherServiceProvider.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\ServiceProviders;
+
+use Illuminate\Support\ServiceProvider;
+use Siteworxpro\App\Events\Dispatcher;
+
+/**
+ * Class DispatcherServiceProvider
+ *
+ * @package Siteworxpro\App\Services\ServiceProviders
+ */
+class DispatcherServiceProvider extends ServiceProvider
+{
+    public function provides(): array
+    {
+        return [Dispatcher::class];
+    }
+
+    public function register(): void
+    {
+        $this->app->singleton(Dispatcher::class, function () {
+            return new Dispatcher();
+        });
+    }
+}

src/Services/ServiceProviders/LoggerServiceProvider.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\ServiceProviders;
+
+use Illuminate\Support\ServiceProvider;
+use Siteworxpro\App\Log\Logger;
+use Siteworxpro\App\Services\Facades\Config;
+
+/**
+ * Class LoggerServiceProvider
+ *
+ * @package Siteworxpro\App\Services\ServiceProviders
+ */
+class LoggerServiceProvider extends ServiceProvider
+{
+    public function provides(): array
+    {
+        return [Logger::class];
+    }
+
+    public function register(): void
+    {
+        $this->app->singleton(Logger::class, function () {
+            return new Logger(Config::get('app.log_level'));
+        });
+    }
+}

src/Services/ServiceProviders/RedisServiceProvider.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Services\ServiceProviders;
+
+use Illuminate\Support\ServiceProvider;
+use Predis\Client;
+use Siteworxpro\App\Services\Facades\Config;
+
+/**
+ * Class RedisServiceProvider
+ *
+ * This service provider registers a Redis client as a singleton in the application container.
+ *
+ * @package Siteworxpro\App\Services\ServiceProviders
+ */
+class RedisServiceProvider extends ServiceProvider
+{
+    public function provides(): array
+    {
+        return [Client::class];
+    }
+
+    public function register(): void
+    {
+        $this->app->singleton(Client::class, function () {
+            return new Client([
+                'scheme' => 'tcp',
+                'host' => Config::get('redis.host'),
+                'port' => Config::get('redis.port'),
+                'database' => Config::get('redis.database'),
+                'password' => Config::get('redis.password'),
+            ]);
+        });
+    }
+}