feat: update Docker configuration for SSL support and improve service registration (#26)

Reviewed-on: #26
Co-authored-by: Ron Rise <ron@siteworxpro.com>
Co-committed-by: Ron Rise <ron@siteworxpro.com>

.dev/docker-compose.yml

@@ -5,6 +5,12 @@ volumes:
 services:
 
   traefik:
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.traefik.entrypoints=web-secure"
+      - "traefik.http.routers.traefik.rule=Host(`127.0.0.1`) && (PathPrefix(`/dashboard`) || PathPrefix(`/api`))"
+      - "traefik.http.routers.traefik.tls=true"
+      - "traefik.http.routers.traefik.service=api@internal"
     image: traefik:latest
     container_name: traefik
     healthcheck:
@@ -15,15 +21,20 @@ services:
     ports:
       - "80:80"
       - "443:443"
+      - "9001:9001"
     volumes:
       - "/var/run/docker.sock:/var/run/docker.sock"
+      - "./ssl:/etc/ssl"
     restart: always
     command:
       - "--providers.docker=true"
+      - "--api.insecure=true"
       - "--ping"
+      - "--providers.file.filename=/etc/ssl/traefik.yml"
       - "--providers.docker.exposedByDefault=false"
       - "--entrypoints.web.address=:80"
       - "--entrypoints.web-secure.address=:443"
+      - "--entrypoints.grpc.address=:9001"
       - "--accesslog=true"
       - "--entrypoints.web.http.redirections.entryPoint.to=web-secure"
       - "--entrypoints.web.http.redirections.entryPoint.scheme=https"
@@ -31,16 +42,30 @@ services:
 
   composer-runtime:
     volumes:
-      - .:/app
+      - ..:/app
     image: siteworxpro/composer
     entrypoint: "/bin/sh -c 'while true; do sleep 30; done;'"
     environment:
       PHP_IDE_CONFIG: serverName=localhost
 
+  swagger-ui:
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.swagger-ui.entrypoints=web-secure"
+      - "traefik.http.routers.swagger-ui.rule=Host(`localhost`) && PathPrefix(`/docs`)"
+      - "traefik.http.routers.swagger-ui.tls=true"
+      - "traefik.http.routers.swagger-ui.service=swagger-ui"
+      - "traefik.http.services.swagger-ui.loadbalancer.server.port=8080"
+    image: swaggerapi/swagger-ui:latest
+    container_name: swagger-ui
+    environment:
+      BASE_URL: /docs
+      URL: /.well-known/swagger.yaml
+
   migration-container:
     volumes:
-      - ./db/migrations:/app/db/migrations
+      - ../db/migrations:/app/db/migrations
-      - ./bin:/app/bin
+      - ../bin:/app/bin
     image: siteworxpro/migrate:v4.18.3
     working_dir: /app
 #    entrypoint: "/bin/sh -c 'while true; do sleep 30; done;'"
@@ -65,12 +90,19 @@ services:
       - "traefik.http.services.api.loadbalancer.healthcheck.path=/healthz"
       - "traefik.http.services.api.loadbalancer.healthcheck.interval=5s"
       - "traefik.http.services.api.loadbalancer.healthcheck.timeout=60s"
+      - "traefik.tcp.services.api.loadbalancer.server.port=9001"
+      - "traefik.http.services.api.loadbalancer.server.port=9501"
+      - "traefik.tcp.routers.grpc.entrypoints=grpc"
+      - "traefik.tcp.routers.grpc.rule=HostSNI(`localhost`) || HostSNI(`127.0.0.1`)"
+      - "traefik.tcp.routers.grpc.tls=true"
+      - "traefik.tcp.routers.grpc.service=api"
+    container_name: dev-runtime
     volumes:
-      - .:/app
+      - ..:/app
     build:
       args:
         KAFKA_ENABLED: "1"
-      context: .
+      context: ..
       dockerfile: Dockerfile
     entrypoint: "/bin/sh -c 'while true; do sleep 30; done;'"
     depends_on:
@@ -89,9 +121,11 @@ services:
       QUEUE_BROKER: redis
       PHP_IDE_CONFIG: serverName=localhost
       WORKERS: 1
+      GRPC_WORKERS: 1
       DEBUG: 1
       REDIS_HOST: redis
       DB_HOST: postgres
+      DEV_MODE: 1
 
   ## Kafka and Zookeeper for local development
   kafka-ui:

.dev/ssl/localhost.crt

@@ -0,0 +1,83 @@
+-----BEGIN CERTIFICATE-----
+MIIEFzCCA52gAwIBAgIURfvF11Q9R3Ue38Tr0BzIoUe0TKQwCgYIKoZIzj0EAwMw
+MDEuMCwGA1UEAxMlU2l0ZXdvcnggSW50ZXJtZWRpYXRlIEVDMzg0IEF1dGhvcml0
+eTAeFw0yNTEyMDQxNjM1NTFaFw0yNjEyMDQxNjM2MjFaMHExCzAJBgNVBAYTAlVT
+MREwDwYDVQQIEwhWaXJnaW5pYTEVMBMGA1UEBxMMUHVyY2VsbHZpbGxlMSQwIgYD
+VQQKExtTaXRld29yeCBQcm9mZXNzaW9uYWxzLCBMTEMxEjAQBgNVBAMTCWxvY2Fs
+aG9zdDB2MBAGByqGSM49AgEGBSuBBAAiA2IABM+jXangYCOi01IMblAXJ6iFZE4v
+SBBOZKNQCwGz8kKi5jyXtVwz6U26DMlBSK+InhhOFQlCRcP9ow8LtlQdaY2XnGKr
+3X3zxdUZJVhLi/wog+I4igU3+xuyn1E/BgEZx6OCAjUwggIxMA4GA1UdDwEB/wQE
+AwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAMBgNVHRMBAf8EAjAAMB0GA1UdDgQW
+BBRAtanjiWMYAdpCCz0rEkyqf691bzAfBgNVHSMEGDAWgBQYBC15lPoGGGxbmwqY
+MWL7jjI6azBJBggrBgEFBQcBAQQ9MDswOQYIKwYBBQUHMAGGLWh0dHBzOi8vdmF1
+bHQuc2l0ZXdvcnhwcm8uY29tL3YxL3N3eF9pbnQvb2NzcDAaBgNVHREEEzARggls
+b2NhbGhvc3SHBH8AAAEwHAYDVR0gBBUwEzAIBgZngQwBAgIwBwYFZ4EMAQEwggE1
+BgNVHR8EggEsMIIBKDBioGCgXoZcaHR0cHM6Ly92YXVsdC5zaXRld29yeHByby5j
+b20vdjEvc3d4X2ludC9pc3N1ZXIvMjVmMWRiNTAtZDQxOS1kZWQ3LTZiZjktZWNh
+Y2E4NGEwMmY0L2NybC9wZW0wXqBcoFqGWGh0dHBzOi8vdmF1bHQuc2l0ZXdvcnhw
+cm8uY29tL3YxL3N3eF9pbnQvaXNzdWVyLzI1ZjFkYjUwLWQ0MTktZGVkNy02YmY5
+LWVjYWNhODRhMDJmNC9jcmwwYqBgoF6GXGh0dHBzOi8vdmF1bHQuc2l0ZXdvcnhw
+cm8uY29tL3YxL3N3eF9pbnQvaXNzdWVyLzI1ZjFkYjUwLWQ0MTktZGVkNy02YmY5
+LWVjYWNhODRhMDJmNC9jcmwvZGVyMAoGCCqGSM49BAMDA2gAMGUCMGxgZmKITQFu
+H6j3j/t9MOTxhVsfOuoD0q3pMlp9d1u4Lg0THKUOzN06BVuXwC1eagIxAL2I/2a1
+MMJmhky2EavzOsYt37Ae+1KGyELiwcWe5f/lActlw97pqRajpmqEmdo7PA==
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIEETCCAfmgAwIBAgIUIRpRFzFBITweYJETytgbPBgwbWgwDQYJKoZIhvcNAQEL
+BQAwgZ0xCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhWaXJnaW5pYTEVMBMGA1UEBwwM
+UHVyY2VsbHZpbGxlMSQwIgYDVQQKDBtTaXRld29yeCBQcm9mZXNzaW9uYWxzLCBM
+TEMxFDASBgNVBAMMC1NXWCBSb290IENBMSgwJgYJKoZIhvcNAQkBFhl3ZWJtYXN0
+ZXJAc2l0ZXdvcnhwcm8uY29tMB4XDTIzMDMyMTE2MzAxNVoXDTMzMDMxODE2MzA0
+NVowMDEuMCwGA1UEAxMlU2l0ZXdvcnggSW50ZXJtZWRpYXRlIEVDMzg0IEF1dGhv
+cml0eTB2MBAGByqGSM49AgEGBSuBBAAiA2IABIhlP1W1O1WjoDFGFi5XbE0zVy90
+76pQQ8VmSYtaZI9Jz5pAZTOQ073t/QkTWge8uhDaJ2J2uBhjQJGr5BPttvBcLJFI
+52X7hJuck4oL0aukXiHYA5gZbC5LhKVvCyZcWqNjMGEwDgYDVR0PAQH/BAQDAgEG
+MA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFBgELXmU+gYYbFubCpgxYvuOMjpr
+MB8GA1UdIwQYMBaAFHWCysIFrdsWYZJSjBO1pSQPETkTMA0GCSqGSIb3DQEBCwUA
+A4ICAQBbw5roegt0tUc+gu0IcHDt56cUoqChmIZXzla8gTgg820ww/+Wm+vNAl8W
+r3Y67LzK19CygoujD2o7M25syaByRiw9JdIfNGvBzklOOM+sus9DDmwSUBMCuljS
+KLBhWzIrXDZwemzklGEbj+RL4o2ZiL01nx8xygDF55eaudNS0VzRzd2Hv0C+rm2i
+nnwRNoKsL14YXc41rFBWwb5ViRuD2Wp0c9CivEOd4UNKgOnGyNxcNhjzNlY05t3c
+NEeskEXiz21sj0vnrwM7olKyXPXDFUCCKGb21Sn9sWKldicumU1i1HdDGA1w50uh
+NS4G4wqGQ8iZCq3h6JkpBMGPJPG3Dq6yuzrh8fmh56IqtKY4MxdKHb91MtFHnkw5
+jCrxqpTKShRyqcBSx8QmXRXpec5FEB88NQ3aKhtFlNqXYphNRAI9bLIyGkdxUF/r
+PCkZkKBhbsRvXT8Ii/K1PQHzliQqJxXhrrJEsIg2jiSQItBg52ZySzuw+Y6++h11
+73XMKJ53oOeLcxvp2qJRwMkNTwVfNxDmKC0tIRdI+KoJYbYeN0Ev/pEdPdYl+hjY
+uQhKMt1KtpUyYwPzTGPKGMnklKj/T3Qu7fmpsWxtAOuK7yLLMayBwXBlVBD23md+
+UAfPR3FfVX+aRqqsvT7WI+SnlycJuYXs41ZPxBjLq2aB7fhAwQ==
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIGIjCCBAqgAwIBAgIJAKU+Idu5bncNMA0GCSqGSIb3DQEBCwUAMIGdMQswCQYD
+VQQGEwJVUzERMA8GA1UECAwIVmlyZ2luaWExFTATBgNVBAcMDFB1cmNlbGx2aWxs
+ZTEkMCIGA1UECgwbU2l0ZXdvcnggUHJvZmVzc2lvbmFscywgTExDMRQwEgYDVQQD
+DAtTV1ggUm9vdCBDQTEoMCYGCSqGSIb3DQEJARYZd2VibWFzdGVyQHNpdGV3b3J4
+cHJvLmNvbTAeFw0yMDA5MDgxMjU3NTJaFw00MDA5MDMxMjU3NTJaMIGdMQswCQYD
+VQQGEwJVUzERMA8GA1UECAwIVmlyZ2luaWExFTATBgNVBAcMDFB1cmNlbGx2aWxs
+ZTEkMCIGA1UECgwbU2l0ZXdvcnggUHJvZmVzc2lvbmFscywgTExDMRQwEgYDVQQD
+DAtTV1ggUm9vdCBDQTEoMCYGCSqGSIb3DQEJARYZd2VibWFzdGVyQHNpdGV3b3J4
+cHJvLmNvbTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAN9JNyWot7VX
+ODvru8S5/o6gdFuynA1l5T0uXSzWhROMYHndmY+n7pwQCwf1R8iLL3aat9sDRxqM
+RRScD3nNW6UzC5xNz12wiuemf2KT82cTjmUBU3CvtjstbgkrQ/SrpR/Arvu2YwUe
+tmL9ft/xaoGvZXx8LKpyRMrHA1FlS2st+RFWBC0yXTU/nL4/7YQKVEcbc3YZvgCT
+P4/8pxH9u8W7kgnufQHHKEIZR9lxIUhQ7yvc61B3zMntbJsZV1N+0c7j5DXY5cfT
+6zXlfG2hSX1dbhM56y8O8KiCFaWaDRZ9mwkfZGM0W58gkhXUPXOrIOwewLmvl2Z4
+Vu43UkLfKhtQApxk6zodHRq1e2rNWSpBCGznT9XyoeO/spJ7yggNkleTa+SnnlmV
+rHJS/YUp3/jAvJY2bCHQKFu/mguMY3Ub2X6eEBsVZOmUqDMbya1TPP6GCVqh4gUu
+yip6qS9UksaTF6IN3IcrGhwtTyvp8BFqwVA0tMhgraf1rv6ZoXjY/NDuGjE1xXJg
+Hg+gg2pIIRcXjcsG1tXFXTgxDqoh127ADg/gtq9cIyarMx4LdNTjnR+CnhjqvRkT
+uiUBB1bwDc9pbX0ulfnR+VuIZtQ6PSuWwChnMdNBKmCgQT1J1AHWpQqnFTjg42NV
+5QAdFOQxAnsq2DxkurVFEz2J3euZx1ZdAgMBAAGjYzBhMB0GA1UdDgQWBBR1gsrC
+Ba3bFmGSUowTtaUkDxE5EzAfBgNVHSMEGDAWgBR1gsrCBa3bFmGSUowTtaUkDxE5
+EzAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjANBgkqhkiG9w0BAQsF
+AAOCAgEAZDjIlaAoMfRGdb3/i40s6nN18iWN2Chttd8dLXgV+/SZ8GrAU89JNJrK
+ODaLZT1wHeWVz0LP3miByuvfrnH4qzPEOI2L6zEy/FJr8SCivjm7aUExyb5kTSXp
+LkwVcOI9UfQb6lCy9Gs/rUEcWQjs5KS3dy6ZwBMaywq6sRj7MeXmhqXhj7aAyWFA
+psnQsuP2XweWa9OX6Z+u78sebfoiJlOEUvV9VRNHQYpLUd75p6sti1Dm9blWkZEO
+hyssi3kOJMH+g5pc9xNbD9gS+/pFUWxEVAhHOc0xdEIcHfV5oiiOUDD5EOIPi3xv
+/NYTV7o7pv2/QlH09vO2PHdsy07lhsg7NoM3U+zYq609Ox78/b4PNd+TkdtYKebO
+VumZ0xXab0lWbTVuno52k473ODQRA/v9YWHtuovW0Lzf5fDcBhVXTDeW21SmMJIx
+B+dgJDh7ql7ruZqjMj+kePjM9Mm+M5pDZ6vrEtgiR2yQj/IE+LoQh/bxFHpFkIK8
+I6AWoxABAvLZB+KHl1ufR5yOauJG2+SQRuzHNZvkAcdjmwpgfxcsB2mY7o0RbGmZ
+VWm97P4P9iJhje/W4C0cGwVY5wRAMAg6SI1BpcW7YghB14UrKaxpEzHCdZIeeT94
+GYzN2XNSSGW3s1anFedd5PQyRM7PlJIcloLYrqyWW6M7OwWnMXA=
+-----END CERTIFICATE-----

.dev/ssl/localhost.key

@@ -0,0 +1,6 @@
+-----BEGIN EC PRIVATE KEY-----
+MIGkAgEBBDBrpJYaCMqgu490fpZoIphGVspE33v3JwyD9B55HwSX/jykySs9NTOv
+68YndzE9LNCgBwYFK4EEACKhZANiAATPo12p4GAjotNSDG5QFyeohWROL0gQTmSj
+UAsBs/JCouY8l7VcM+lNugzJQUiviJ4YThUJQkXD/aMPC7ZUHWmNl5xiq91988XV
+GSVYS4v8KIPiOIoFN/sbsp9RPwYBGcc=
+-----END EC PRIVATE KEY-----

.dev/ssl/traefik.yml

@@ -0,0 +1,14 @@
+tls:
+  stores:
+    default:
+      defaultCertificate:
+        certFile: /etc/ssl/localhost.crt
+        keyFile: /etc/ssl/localhost.key
+
+  options:
+    default:
+      minVersion: VersionTLS13
+      preferServerCipherSuites: true
+
+    mintls13:
+      minVersion: VersionTLS13

.gitea/workflows/build.yml

@@ -26,6 +26,12 @@ jobs:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
 
+      - name: Write Version File
+        run: |
+          echo $GITEA_REF_NAME > VERSION
+          sed -i "s/dev-version/${GITEA_REF_NAME}/g" src/Helpers/Version.php
+      
+
       - name: 🏗️ 🔧 Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 

.rr.yaml

@@ -6,6 +6,17 @@ server:
 rpc:
   listen: tcp://127.0.0.1:6001
 
+grpc:
+  listen: "tcp://0.0.0.0:9001"
+  pool:
+    command: "php grpc-worker.php"
+    num_workers: ${GRPC_WORKERS:-4}
+    debug: ${DEBUG:-false}
+    reflection: ${GRPC_REFLECTION:-true}
+    destroy_timeout: 5s
+  proto:
+    - "protos/example.proto"
+
 http:
   pool:
     allocate_timeout: 5s

.run/ Compose Deployment.run.xml

@@ -1,8 +1,8 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name=" Compose Deployment" type="docker-deploy" factoryName="docker-compose.yml" server-name="Docker">
+  <configuration default="false" name=".dev: Compose Deployment" type="docker-deploy" factoryName="docker-compose.yml" server-name="Docker">
     <deployment type="docker-compose.yml">
       <settings>
-        <option name="sourceFilePath" value="docker-compose.yml" />
+        <option name="sourceFilePath" value=".dev/docker-compose.yml" />
       </settings>
     </deployment>
     <method v="2" />

Dockerfile

@@ -12,7 +12,7 @@ RUN composer install --optimize-autoloader --ignore-platform-reqs --no-dev
 
 
 # Use the official PHP CLI image with Alpine Linux for the second stage
-FROM php:8.4.14-alpine AS php
+FROM siteworxpro/php:8.5.0-cli-alpine AS php
 
 ARG KAFKA_ENABLED=0
 
@@ -26,6 +26,7 @@ RUN if [ "$KAFKA_ENABLED" -eq 1 ] ; then \
         echo "Kafka support enabled" ; \
         apk add autoconf g++ librdkafka-dev make --no-cache ; \
         pecl install rdkafka && docker-php-ext-enable rdkafka ; \
+        apk del autoconf g++ make ; \
     else \
         echo "Kafka support disabled" ; \
         exit 0 ; \
@@ -42,11 +43,18 @@ COPY --from=library /app/vendor /app/vendor
 
 # Copy the RoadRunner configuration file and source
 ADD src src/
-ADD server.php .
+ADD generated generated/
-ADD .rr.yaml .
+ADD protos protos/
-ADD config.php .
+ADD server.php cli.php grpc-worker.php .rr.yaml config.php ./
 
-EXPOSE 9501
+EXPOSE 9501 9001
+
+RUN addgroup -g 1000 appuser && adduser -D -u 1000 -G appuser appuser && chown -R appuser:appuser /app
+USER appuser
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \
+  CMD curl -f http://localhost:9501/healthz || exit 1
 
 # Entrypoint command to run the RoadRunner server with the specified configuration
-ENTRYPOINT ["rr",  "serve",  "-c",  ".rr.yaml", "-s"]
+ENTRYPOINT ["rr", "serve"]
+CMD ["-c", ".rr.yaml", "-s"]

README.md

@@ -2,55 +2,132 @@
 
 ![pipeline status](https://gitea.siteworxpro.com/siteworxpro/Php-Template/actions/workflows/tests.yml/badge.svg?branch=master&style=flat-square)
 
+## Overview
+
+This is a PHP project template that provides a structured development environment using Docker Compose and Make.
+It includes tools for code quality, testing, dependency management, and gRPC support.
+
 ## Dev Environment
 
-### Prerequisites
+This project uses Docker Compose and Make to manage the development environment. The `makefile` provides convenient
-- Docker
+commands for common development tasks.
-- Docker Compose
 
-### migrations
+## Prerequisites
 
-create a new migration
+- Docker and Docker Compose
-```shell
+- Make
-docker run --rm  -v $(PWD):/app siteworxpro/migrate:v4.18.3 create -ext sql -dir /app/db/migrations -seq create_users_table
+- protoc (Protocol Buffers compiler) - for gRPC code generation
+
+## Quick Start
+
+```bash
+# Install PHP dependencies
+make composer-install
+
+# Start the development container
+make start
+
+# Run the application server
+make run
 ```
 
-```text
+## Available Commands
-postgres://siteworxpro:password@localhost:5432/siteworxpro?sslmode=disable
+
+### Container Management
+
+- `make start` - Start the development runtime container
+- `make stop` - Stop and remove all containers
+- `make restart` - Restart the development container
+- `make rebuild` - Rebuild containers (use after Dockerfile changes)
+- `make sh` - Open a shell in the development container
+- `make ps` - Show running containers
+
+### Application
+
+- `make run` - Run the application server (RoadRunner)
+- `make migrate` - Run database migrations
+
+### Composer & Dependencies
+
+- `make composer-install` - Install PHP dependencies
+- `make composer-update` - Update PHP dependencies
+- `make composer-require package=vendor/package` - Add a new dependency
+- `make composer-require-dev package=vendor/package` - Add a new dev dependency
+
+### Code Quality
+
+- `make lint` - Run linters (phpcs and phpstan)
+- `make fmt` - Format code with php-cs-fixer
+- `make test` - Run the test suite (phpunit)
+- `make license-check` - Check license headers in source files
+
+### Debugging & Coverage
+
+- `make enable-debug` - Enable Xdebug for debugging
+- `make enable-coverage` - Enable PCOV for code coverage
+
+### gRPC
+
+- `make protoc` - Generate PHP gRPC code from `.proto` files
+
+### CI Workflow
+
+- `make ci` - Run the full CI pipeline locally (install, license check, lint, test)
+
+### Help
+
+- `make help` - Show all available commands with descriptions
+
+## Common Workflows
+
+### Starting Development
+
+```bash
+make composer-install
+make start
+make run
 ```
 
-```shell
+### Adding a New Package
-docker run --rm  -v $(PWD):/app siteworxpro/migrate:v4.18.3 -database "postgres://siteworxpro:password@localhost:5432/siteworxpro?sslmode=disable" -path /app/db/migrations up
+
+```bash
+make composer-require package=vendor/package-name
 ```
 
-### Starting the Runtime
+### Running Tests
-```shell
+
-docker-compose up -d
+```bash
-```
+make test
-### Start the server
-```shell
-docker exec -it template-dev-runtime-1 rr serve
 ```
 
-You can access the api at `http://localhost:9501/`
+### Code Quality Check
 
-### Xdebug
+```bash
-
+make lint
-xdebug needs to be built into the container before it will work
+make fmt
-```shell
- docker exec -it php-template-composer-runtime-1 bin/xdebug.sh
 ```
 
-### Install the dependencies
+### Debugging
-```shell
+
-docker run --rm  -v $(PWD):/app siteworxpro/composer install --ignore-platform-reqs
+```bash
+make enable-debug
+make run
 ```
 
-### Running all tests
+## Notes
-```shell
-docker run --rm  -v $(PWD):/app siteworxpro/composer run tests:all
-```
 
+- All commands run inside Docker containers, ensuring a consistent environment
+- The development runtime uses RoadRunner as the application server
+- Composer commands run in a separate `composer-runtime` container
+- Database migrations run in a dedicated `migration-container`
+
+## Additional Information
+
+### Accessing Services
+
+- You can access the api at [https://localhost](https://localhost)
+- Traefik dashboard is at [https://127.0.0.1/dashboard/](https://127.0.0.1/dashboard/)
+- the grpc server is at [tcp://localhost:9001](tcp://localhost:9001)
 
 ## License
 

bin/xdebug.sh

@@ -4,9 +4,9 @@ echo "Installing xDebug"
 
 apk add make gcc linux-headers autoconf alpine-sdk
 
-curl -sL https://github.com/xdebug/xdebug/archive/3.4.0.tar.gz -o 3.4.0.tar.gz
+curl -sL https://github.com/xdebug/xdebug/archive/3.5.0alpha3.tar.gz -o 3.5.0alpha3.tar.gz
-tar -xvf 3.4.0.tar.gz
+tar -xvf 3.5.0alpha3.tar.gz
-cd xdebug-3.4.0 || exit
+cd xdebug-3.5.0alpha3 || exit
 phpize
 ./configure --enable-xdebug
 make
@@ -20,5 +20,5 @@ xdebug.client_host = host.docker.internal
 " > /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
 
 cd ..
-rm -rf xdebug-3.4.0
+rm -rf xdebug-3.5.0alpha3
-rm -rf 3.4.0.tar.gz
+rm -rf 3.5.0alpha3.tar.gz

composer.json

@@ -4,11 +4,12 @@
   "autoload": {
     "psr-4": {
       "Siteworxpro\\App\\": "src/",
-      "Siteworxpro\\Tests\\": "tests/"
+      "Siteworxpro\\Tests\\": "tests/",
+      "GRPC\\": "generated/GRPC"
     }
   },
   "require": {
-    "php": "^8.4",
+    "php": "^8.5",
     "league/route": "^6.2.0",
     "illuminate/database": "^v12.34.0",
     "spiral/roadrunner-http": "^v3.6.0",
@@ -24,7 +25,9 @@
     "monolog/monolog": "^3.9",
     "react/promise": "^3",
     "react/async": "^4",
-    "guzzlehttp/guzzle": "^7.10"
+    "guzzlehttp/guzzle": "^7.10",
+    "zircote/swagger-php": "^5.7",
+    "spiral/roadrunner-grpc": "^3.5"
   },
   "require-dev": {
     "phpunit/phpunit": "^12.4",

composer.lock

@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "8c2444c3a25a3469cf369de1c085ad01",
+    "content-hash": "977f74570c671e4d59fd70d5e732c3d2",
     "packages": [
         {
             "name": "adhocore/cli",
@@ -298,6 +298,65 @@
             ],
             "time": "2025-08-10T19:31:58+00:00"
         },
+        {
+            "name": "google/common-protos",
+            "version": "4.12.4",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/googleapis/common-protos-php.git",
+                "reference": "0127156899af0df2681bd42024c60bd5360d64e3"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/googleapis/common-protos-php/zipball/0127156899af0df2681bd42024c60bd5360d64e3",
+                "reference": "0127156899af0df2681bd42024c60bd5360d64e3",
+                "shasum": ""
+            },
+            "require": {
+                "google/protobuf": "^4.31",
+                "php": "^8.1"
+            },
+            "require-dev": {
+                "phpunit/phpunit": "^9.6"
+            },
+            "type": "library",
+            "extra": {
+                "component": {
+                    "id": "common-protos",
+                    "path": "CommonProtos",
+                    "entry": "README.md",
+                    "target": "googleapis/common-protos-php.git"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Google\\Api\\": "src/Api",
+                    "Google\\Iam\\": "src/Iam",
+                    "Google\\Rpc\\": "src/Rpc",
+                    "Google\\Type\\": "src/Type",
+                    "Google\\Cloud\\": "src/Cloud",
+                    "GPBMetadata\\Google\\Api\\": "metadata/Api",
+                    "GPBMetadata\\Google\\Iam\\": "metadata/Iam",
+                    "GPBMetadata\\Google\\Rpc\\": "metadata/Rpc",
+                    "GPBMetadata\\Google\\Type\\": "metadata/Type",
+                    "GPBMetadata\\Google\\Cloud\\": "metadata/Cloud",
+                    "GPBMetadata\\Google\\Logging\\": "metadata/Logging"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "Apache-2.0"
+            ],
+            "description": "Google API Common Protos for PHP",
+            "homepage": "https://github.com/googleapis/common-protos-php",
+            "keywords": [
+                "google"
+            ],
+            "support": {
+                "source": "https://github.com/googleapis/common-protos-php/tree/v4.12.4"
+            },
+            "time": "2025-09-20T01:29:44+00:00"
+        },
         {
             "name": "google/protobuf",
             "version": "v4.33.1",
@@ -1559,6 +1618,64 @@
             },
             "time": "2018-02-13T20:26:39+00:00"
         },
+        {
+            "name": "nikic/php-parser",
+            "version": "v5.6.2",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/nikic/PHP-Parser.git",
+                "reference": "3a454ca033b9e06b63282ce19562e892747449bb"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/3a454ca033b9e06b63282ce19562e892747449bb",
+                "reference": "3a454ca033b9e06b63282ce19562e892747449bb",
+                "shasum": ""
+            },
+            "require": {
+                "ext-ctype": "*",
+                "ext-json": "*",
+                "ext-tokenizer": "*",
+                "php": ">=7.4"
+            },
+            "require-dev": {
+                "ircmaxell/php-yacc": "^0.0.7",
+                "phpunit/phpunit": "^9.0"
+            },
+            "bin": [
+                "bin/php-parse"
+            ],
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-master": "5.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "PhpParser\\": "lib/PhpParser"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-3-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Nikita Popov"
+                }
+            ],
+            "description": "A PHP parser written in PHP",
+            "keywords": [
+                "parser",
+                "php"
+            ],
+            "support": {
+                "issues": "https://github.com/nikic/PHP-Parser/issues",
+                "source": "https://github.com/nikic/PHP-Parser/tree/v5.6.2"
+            },
+            "time": "2025-10-21T19:32:17+00:00"
+        },
         {
             "name": "nyholm/psr7",
             "version": "1.8.2",
@@ -1637,6 +1754,53 @@
             ],
             "time": "2024-09-09T07:06:30+00:00"
         },
+        {
+            "name": "phpstan/phpdoc-parser",
+            "version": "2.3.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/phpstan/phpdoc-parser.git",
+                "reference": "1e0cd5370df5dd2e556a36b9c62f62e555870495"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/phpstan/phpdoc-parser/zipball/1e0cd5370df5dd2e556a36b9c62f62e555870495",
+                "reference": "1e0cd5370df5dd2e556a36b9c62f62e555870495",
+                "shasum": ""
+            },
+            "require": {
+                "php": "^7.4 || ^8.0"
+            },
+            "require-dev": {
+                "doctrine/annotations": "^2.0",
+                "nikic/php-parser": "^5.3.0",
+                "php-parallel-lint/php-parallel-lint": "^1.2",
+                "phpstan/extension-installer": "^1.0",
+                "phpstan/phpstan": "^2.0",
+                "phpstan/phpstan-phpunit": "^2.0",
+                "phpstan/phpstan-strict-rules": "^2.0",
+                "phpunit/phpunit": "^9.6",
+                "symfony/process": "^5.2"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "PHPStan\\PhpDocParser\\": [
+                        "src/"
+                    ]
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "description": "PHPDoc parser with support for nullable, intersection and generic types",
+            "support": {
+                "issues": "https://github.com/phpstan/phpdoc-parser/issues",
+                "source": "https://github.com/phpstan/phpdoc-parser/tree/2.3.0"
+            },
+            "time": "2025-08-30T15:50:23+00:00"
+        },
         {
             "name": "predis/predis",
             "version": "v3.2.0",
@@ -2838,6 +3002,87 @@
             ],
             "time": "2025-11-13T17:24:29+00:00"
         },
+        {
+            "name": "spiral/roadrunner-grpc",
+            "version": "v3.5.2",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/roadrunner-php/grpc.git",
+                "reference": "916c061de160d6b2f3efc82dcffac0360d84fab8"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/roadrunner-php/grpc/zipball/916c061de160d6b2f3efc82dcffac0360d84fab8",
+                "reference": "916c061de160d6b2f3efc82dcffac0360d84fab8",
+                "shasum": ""
+            },
+            "require": {
+                "ext-json": "*",
+                "google/common-protos": "^3.1|^4.0",
+                "google/protobuf": "^3.7 || ^4.0",
+                "php": ">=8.1",
+                "spiral/goridge": "^4.0",
+                "spiral/roadrunner": "^2024.3 || ^2025.1",
+                "spiral/roadrunner-worker": "^3.0",
+                "symfony/polyfill-php83": "*"
+            },
+            "require-dev": {
+                "jetbrains/phpstorm-attributes": "^1.0",
+                "mockery/mockery": "^1.4",
+                "phpunit/phpunit": "^10.0",
+                "spiral/code-style": "^2.2",
+                "spiral/dumper": "^3.3",
+                "vimeo/psalm": ">=5.8"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Spiral\\RoadRunner\\GRPC\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Anton Titov (wolfy-j)",
+                    "email": "wolfy-j@spiralscout.com"
+                },
+                {
+                    "name": "Pavel Buchnev (butschster)",
+                    "email": "pavel.buchnev@spiralscout.com"
+                },
+                {
+                    "name": "Aleksei Gagarin (roxblnfk)",
+                    "email": "alexey.gagarin@spiralscout.com"
+                },
+                {
+                    "name": "Maksim Smakouz (msmakouz)",
+                    "email": "maksim.smakouz@spiralscout.com"
+                },
+                {
+                    "name": "RoadRunner Community",
+                    "homepage": "https://github.com/spiral/roadrunner/graphs/contributors"
+                }
+            ],
+            "description": "High-Performance GRPC server for PHP applications",
+            "homepage": "https://roadrunner.dev/",
+            "support": {
+                "chat": "https://discord.gg/V6EK4he",
+                "docs": "https://docs.roadrunner.dev",
+                "forum": "https://forum.roadrunner.dev/",
+                "issues": "https://github.com/roadrunner-server/roadrunner/issues",
+                "source": "https://github.com/roadrunner-php/grpc/tree/v3.5.2"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/sponsors/roadrunner-server",
+                    "type": "github"
+                }
+            ],
+            "time": "2025-05-18T13:54:33+00:00"
+        },
         {
             "name": "spiral/roadrunner-http",
             "version": "v3.6.0",
@@ -3154,6 +3399,157 @@
             ],
             "time": "2024-09-25T14:21:43+00:00"
         },
+        {
+            "name": "symfony/finder",
+            "version": "v8.0.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/symfony/finder.git",
+                "reference": "7598dd5770580fa3517ec83e8da0c9b9e01f4291"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/symfony/finder/zipball/7598dd5770580fa3517ec83e8da0c9b9e01f4291",
+                "reference": "7598dd5770580fa3517ec83e8da0c9b9e01f4291",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=8.4"
+            },
+            "require-dev": {
+                "symfony/filesystem": "^7.4|^8.0"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Symfony\\Component\\Finder\\": ""
+                },
+                "exclude-from-classmap": [
+                    "/Tests/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Fabien Potencier",
+                    "email": "fabien@symfony.com"
+                },
+                {
+                    "name": "Symfony Community",
+                    "homepage": "https://symfony.com/contributors"
+                }
+            ],
+            "description": "Finds files and directories via an intuitive fluent interface",
+            "homepage": "https://symfony.com",
+            "support": {
+                "source": "https://github.com/symfony/finder/tree/v8.0.0"
+            },
+            "funding": [
+                {
+                    "url": "https://symfony.com/sponsor",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/fabpot",
+                    "type": "github"
+                },
+                {
+                    "url": "https://github.com/nicolas-grekas",
+                    "type": "github"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/symfony/symfony",
+                    "type": "tidelift"
+                }
+            ],
+            "time": "2025-11-05T14:36:47+00:00"
+        },
+        {
+            "name": "symfony/polyfill-ctype",
+            "version": "v1.33.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/symfony/polyfill-ctype.git",
+                "reference": "a3cc8b044a6ea513310cbd48ef7333b384945638"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/symfony/polyfill-ctype/zipball/a3cc8b044a6ea513310cbd48ef7333b384945638",
+                "reference": "a3cc8b044a6ea513310cbd48ef7333b384945638",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=7.2"
+            },
+            "provide": {
+                "ext-ctype": "*"
+            },
+            "suggest": {
+                "ext-ctype": "For best performance"
+            },
+            "type": "library",
+            "extra": {
+                "thanks": {
+                    "url": "https://github.com/symfony/polyfill",
+                    "name": "symfony/polyfill"
+                }
+            },
+            "autoload": {
+                "files": [
+                    "bootstrap.php"
+                ],
+                "psr-4": {
+                    "Symfony\\Polyfill\\Ctype\\": ""
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Gert de Pagter",
+                    "email": "BackEndTea@gmail.com"
+                },
+                {
+                    "name": "Symfony Community",
+                    "homepage": "https://symfony.com/contributors"
+                }
+            ],
+            "description": "Symfony polyfill for ctype functions",
+            "homepage": "https://symfony.com",
+            "keywords": [
+                "compatibility",
+                "ctype",
+                "polyfill",
+                "portable"
+            ],
+            "support": {
+                "source": "https://github.com/symfony/polyfill-ctype/tree/v1.33.0"
+            },
+            "funding": [
+                {
+                    "url": "https://symfony.com/sponsor",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/fabpot",
+                    "type": "github"
+                },
+                {
+                    "url": "https://github.com/nicolas-grekas",
+                    "type": "github"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/symfony/symfony",
+                    "type": "tidelift"
+                }
+            ],
+            "time": "2024-09-09T11:45:10+00:00"
+        },
         {
             "name": "symfony/polyfill-mbstring",
             "version": "v1.33.0",
@@ -3661,6 +4057,82 @@
             ],
             "time": "2025-07-15T13:41:35+00:00"
         },
+        {
+            "name": "symfony/yaml",
+            "version": "v7.4.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/symfony/yaml.git",
+                "reference": "6c84a4b55aee4cd02034d1c528e83f69ddf63810"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/symfony/yaml/zipball/6c84a4b55aee4cd02034d1c528e83f69ddf63810",
+                "reference": "6c84a4b55aee4cd02034d1c528e83f69ddf63810",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=8.2",
+                "symfony/deprecation-contracts": "^2.5|^3",
+                "symfony/polyfill-ctype": "^1.8"
+            },
+            "conflict": {
+                "symfony/console": "<6.4"
+            },
+            "require-dev": {
+                "symfony/console": "^6.4|^7.0|^8.0"
+            },
+            "bin": [
+                "Resources/bin/yaml-lint"
+            ],
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Symfony\\Component\\Yaml\\": ""
+                },
+                "exclude-from-classmap": [
+                    "/Tests/"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Fabien Potencier",
+                    "email": "fabien@symfony.com"
+                },
+                {
+                    "name": "Symfony Community",
+                    "homepage": "https://symfony.com/contributors"
+                }
+            ],
+            "description": "Loads and dumps YAML files",
+            "homepage": "https://symfony.com",
+            "support": {
+                "source": "https://github.com/symfony/yaml/tree/v7.4.0"
+            },
+            "funding": [
+                {
+                    "url": "https://symfony.com/sponsor",
+                    "type": "custom"
+                },
+                {
+                    "url": "https://github.com/fabpot",
+                    "type": "github"
+                },
+                {
+                    "url": "https://github.com/nicolas-grekas",
+                    "type": "github"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/symfony/symfony",
+                    "type": "tidelift"
+                }
+            ],
+            "time": "2025-11-16T10:14:42+00:00"
+        },
         {
             "name": "voku/portable-ascii",
             "version": "2.0.3",
@@ -3734,6 +4206,94 @@
                 }
             ],
             "time": "2024-11-21T01:49:47+00:00"
+        },
+        {
+            "name": "zircote/swagger-php",
+            "version": "5.7.5",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/zircote/swagger-php.git",
+                "reference": "9a37739401485b42d779495e70548309820d11d6"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/zircote/swagger-php/zipball/9a37739401485b42d779495e70548309820d11d6",
+                "reference": "9a37739401485b42d779495e70548309820d11d6",
+                "shasum": ""
+            },
+            "require": {
+                "ext-json": "*",
+                "nikic/php-parser": "^4.19 || ^5.0",
+                "php": ">=7.4",
+                "phpstan/phpdoc-parser": "^2.0",
+                "psr/log": "^1.1 || ^2.0 || ^3.0",
+                "symfony/deprecation-contracts": "^2 || ^3",
+                "symfony/finder": "^5.0 || ^6.0 || ^7.0 || ^8.0",
+                "symfony/yaml": "^5.4 || ^6.0 || ^7.0 || ^8.0"
+            },
+            "conflict": {
+                "symfony/process": ">=6, <6.4.14"
+            },
+            "require-dev": {
+                "composer/package-versions-deprecated": "^1.11",
+                "doctrine/annotations": "^2.0",
+                "friendsofphp/php-cs-fixer": "^3.62.0",
+                "phpstan/phpstan": "^1.6 || ^2.0",
+                "phpunit/phpunit": "^9.0",
+                "rector/rector": "^1.0 || ^2.0",
+                "vimeo/psalm": "^4.30 || ^5.0"
+            },
+            "suggest": {
+                "doctrine/annotations": "^2.0",
+                "radebatz/type-info-extras": "^1.0.2"
+            },
+            "bin": [
+                "bin/openapi"
+            ],
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-master": "5.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "OpenApi\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "Apache-2.0"
+            ],
+            "authors": [
+                {
+                    "name": "Robert Allen",
+                    "email": "zircote@gmail.com"
+                },
+                {
+                    "name": "Bob Fanger",
+                    "email": "bfanger@gmail.com",
+                    "homepage": "https://bfanger.nl"
+                },
+                {
+                    "name": "Martin Rademacher",
+                    "email": "mano@radebatz.net",
+                    "homepage": "https://radebatz.net"
+                }
+            ],
+            "description": "Generate interactive documentation for your RESTful API using PHP attributes (preferred) or PHPDoc annotations",
+            "homepage": "https://github.com/zircote/swagger-php",
+            "keywords": [
+                "api",
+                "json",
+                "rest",
+                "service discovery"
+            ],
+            "support": {
+                "issues": "https://github.com/zircote/swagger-php/issues",
+                "source": "https://github.com/zircote/swagger-php/tree/5.7.5"
+            },
+            "time": "2025-11-28T23:22:21+00:00"
         }
     ],
     "packages-dev": [
@@ -4027,64 +4587,6 @@
             ],
             "time": "2025-08-01T08:46:24+00:00"
         },
-        {
-            "name": "nikic/php-parser",
-            "version": "v5.6.2",
-            "source": {
-                "type": "git",
-                "url": "https://github.com/nikic/PHP-Parser.git",
-                "reference": "3a454ca033b9e06b63282ce19562e892747449bb"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/3a454ca033b9e06b63282ce19562e892747449bb",
-                "reference": "3a454ca033b9e06b63282ce19562e892747449bb",
-                "shasum": ""
-            },
-            "require": {
-                "ext-ctype": "*",
-                "ext-json": "*",
-                "ext-tokenizer": "*",
-                "php": ">=7.4"
-            },
-            "require-dev": {
-                "ircmaxell/php-yacc": "^0.0.7",
-                "phpunit/phpunit": "^9.0"
-            },
-            "bin": [
-                "bin/php-parse"
-            ],
-            "type": "library",
-            "extra": {
-                "branch-alias": {
-                    "dev-master": "5.x-dev"
-                }
-            },
-            "autoload": {
-                "psr-4": {
-                    "PhpParser\\": "lib/PhpParser"
-                }
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "license": [
-                "BSD-3-Clause"
-            ],
-            "authors": [
-                {
-                    "name": "Nikita Popov"
-                }
-            ],
-            "description": "A PHP parser written in PHP",
-            "keywords": [
-                "parser",
-                "php"
-            ],
-            "support": {
-                "issues": "https://github.com/nikic/PHP-Parser/issues",
-                "source": "https://github.com/nikic/PHP-Parser/tree/v5.6.2"
-            },
-            "time": "2025-10-21T19:32:17+00:00"
-        },
         {
             "name": "phar-io/manifest",
             "version": "2.0.4",
@@ -5821,89 +6323,6 @@
             ],
             "time": "2025-11-04T01:21:42+00:00"
         },
-        {
-            "name": "symfony/polyfill-ctype",
-            "version": "v1.33.0",
-            "source": {
-                "type": "git",
-                "url": "https://github.com/symfony/polyfill-ctype.git",
-                "reference": "a3cc8b044a6ea513310cbd48ef7333b384945638"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://api.github.com/repos/symfony/polyfill-ctype/zipball/a3cc8b044a6ea513310cbd48ef7333b384945638",
-                "reference": "a3cc8b044a6ea513310cbd48ef7333b384945638",
-                "shasum": ""
-            },
-            "require": {
-                "php": ">=7.2"
-            },
-            "provide": {
-                "ext-ctype": "*"
-            },
-            "suggest": {
-                "ext-ctype": "For best performance"
-            },
-            "type": "library",
-            "extra": {
-                "thanks": {
-                    "url": "https://github.com/symfony/polyfill",
-                    "name": "symfony/polyfill"
-                }
-            },
-            "autoload": {
-                "files": [
-                    "bootstrap.php"
-                ],
-                "psr-4": {
-                    "Symfony\\Polyfill\\Ctype\\": ""
-                }
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "license": [
-                "MIT"
-            ],
-            "authors": [
-                {
-                    "name": "Gert de Pagter",
-                    "email": "BackEndTea@gmail.com"
-                },
-                {
-                    "name": "Symfony Community",
-                    "homepage": "https://symfony.com/contributors"
-                }
-            ],
-            "description": "Symfony polyfill for ctype functions",
-            "homepage": "https://symfony.com",
-            "keywords": [
-                "compatibility",
-                "ctype",
-                "polyfill",
-                "portable"
-            ],
-            "support": {
-                "source": "https://github.com/symfony/polyfill-ctype/tree/v1.33.0"
-            },
-            "funding": [
-                {
-                    "url": "https://symfony.com/sponsor",
-                    "type": "custom"
-                },
-                {
-                    "url": "https://github.com/fabpot",
-                    "type": "github"
-                },
-                {
-                    "url": "https://github.com/nicolas-grekas",
-                    "type": "github"
-                },
-                {
-                    "url": "https://tidelift.com/funding/github/packagist/symfony/symfony",
-                    "type": "tidelift"
-                }
-            ],
-            "time": "2024-09-09T11:45:10+00:00"
-        },
         {
             "name": "symfony/polyfill-intl-grapheme",
             "version": "v1.33.0",
@@ -6370,7 +6789,7 @@
     "prefer-stable": false,
     "prefer-lowest": false,
     "platform": {
-        "php": "^8.4"
+        "php": "^8.5"
     },
     "platform-dev": {},
     "plugin-api-version": "2.9.0"

config.php

@@ -6,6 +6,7 @@ return [
 
     'app' => [
         'log_level' => Env::get('LOG_LEVEL', 'debug'),
+        'dev_mode' => Env::get('DEV_MODE', false, 'bool'),
     ],
 
     /**
@@ -13,7 +14,6 @@ return [
      */
     'server' => [
         'port' => Env::get('HTTP_PORT', 9501, 'int'),
-        'dev_mode' => Env::get('DEV_MODE', false, 'bool'),
     ],
 
     /**

generated/GRPC/GPBMetadata/Example.php

@@ -0,0 +1,25 @@
+<?php
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: protos/example.proto
+
+namespace GRPC\GPBMetadata;
+
+class Example
+{
+    public static $is_initialized = false;
+
+    public static function initOnce() {
+        $pool = \Google\Protobuf\Internal\DescriptorPool::getGeneratedPool();
+
+        if (static::$is_initialized == true) {
+          return;
+        }
+        $pool->internalAddGeneratedFile(
+            "\x0A\xE5\x01\x0A\x14protos/example.proto\x12\x0Ahelloworld\"\x1C\x0A\x0CHelloRequest\x12\x0C\x0A\x04name\x18\x01 \x01(\x09\"\x1D\x0A\x0AHelloReply\x12\x0F\x0A\x07message\x18\x01 \x01(\x092I\x0A\x07Greeter\x12>\x0A\x08SayHello\x12\x18.helloworld.HelloRequest\x1A\x16.helloworld.HelloReply\"\x00B1Z\x0Dproto/greeter\xCA\x02\x0CGRPC\\Greeter\xE2\x02\x10GRPC\\GPBMetadatab\x06proto3"
+        , true);
+
+        static::$is_initialized = true;
+    }
+}
+

generated/GRPC/Greeter/GreeterInterface.php

@@ -0,0 +1,22 @@
+<?php
+# Generated by the protocol buffer compiler (roadrunner-server/grpc). DO NOT EDIT!
+# source: protos/example.proto
+
+namespace GRPC\Greeter;
+
+use Spiral\RoadRunner\GRPC;
+
+interface GreeterInterface extends GRPC\ServiceInterface
+{
+    // GRPC specific service name.
+    public const NAME = "helloworld.Greeter";
+
+    /**
+    * @param GRPC\ContextInterface $ctx
+    * @param HelloRequest $in
+    * @return HelloReply
+    *
+    * @throws GRPC\Exception\InvokeException
+    */
+    public function SayHello(GRPC\ContextInterface $ctx, HelloRequest $in): HelloReply;
+}

generated/GRPC/Greeter/HelloReply.php

@@ -0,0 +1,61 @@
+<?php
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: protos/example.proto
+
+namespace GRPC\Greeter;
+
+use Google\Protobuf\Internal\GPBType;
+use Google\Protobuf\Internal\GPBUtil;
+use Google\Protobuf\RepeatedField;
+
+/**
+ * The response message containing the greetings
+ *
+ * Generated from protobuf message <code>helloworld.HelloReply</code>
+ */
+class HelloReply extends \Google\Protobuf\Internal\Message
+{
+    /**
+     * Generated from protobuf field <code>string message = 1;</code>
+     */
+    protected $message = '';
+
+    /**
+     * Constructor.
+     *
+     * @param array $data {
+     *     Optional. Data for populating the Message object.
+     *
+     *     @type string $message
+     * }
+     */
+    public function __construct($data = NULL) {
+        \GRPC\GPBMetadata\Example::initOnce();
+        parent::__construct($data);
+    }
+
+    /**
+     * Generated from protobuf field <code>string message = 1;</code>
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+
+    /**
+     * Generated from protobuf field <code>string message = 1;</code>
+     * @param string $var
+     * @return $this
+     */
+    public function setMessage($var)
+    {
+        GPBUtil::checkString($var, True);
+        $this->message = $var;
+
+        return $this;
+    }
+
+}
+

generated/GRPC/Greeter/HelloRequest.php

@@ -0,0 +1,61 @@
+<?php
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: protos/example.proto
+
+namespace GRPC\Greeter;
+
+use Google\Protobuf\Internal\GPBType;
+use Google\Protobuf\Internal\GPBUtil;
+use Google\Protobuf\RepeatedField;
+
+/**
+ * The request message containing the user's name.
+ *
+ * Generated from protobuf message <code>helloworld.HelloRequest</code>
+ */
+class HelloRequest extends \Google\Protobuf\Internal\Message
+{
+    /**
+     * Generated from protobuf field <code>string name = 1;</code>
+     */
+    protected $name = '';
+
+    /**
+     * Constructor.
+     *
+     * @param array $data {
+     *     Optional. Data for populating the Message object.
+     *
+     *     @type string $name
+     * }
+     */
+    public function __construct($data = NULL) {
+        \GRPC\GPBMetadata\Example::initOnce();
+        parent::__construct($data);
+    }
+
+    /**
+     * Generated from protobuf field <code>string name = 1;</code>
+     * @return string
+     */
+    public function getName()
+    {
+        return $this->name;
+    }
+
+    /**
+     * Generated from protobuf field <code>string name = 1;</code>
+     * @param string $var
+     * @return $this
+     */
+    public function setName($var)
+    {
+        GPBUtil::checkString($var, True);
+        $this->name = $var;
+
+        return $this;
+    }
+
+}
+

generated/README.md

@@ -0,0 +1,3 @@
+### Note to Developers
+Only generated files are allowed in this directory.
+Please do not add any other files here manually.

grpc-worker.php

@@ -0,0 +1,14 @@
+<?php
+
+use Siteworxpro\App\Grpc;
+
+require __DIR__ . '/vendor/autoload.php';
+
+try {
+    $server = new Grpc();
+    exit($server->start());
+} catch (\Exception $e) {
+    echo $e->getMessage();
+
+    exit(1);
+}

makefile

@@ -0,0 +1,162 @@
+# Makefile (enhanced)
+SHELL := /bin/sh
+.DEFAULT_GOAL := help
+
+# Docker Compose file
+COMPOSE_FILE := -f .dev/docker-compose.yml
+
+# Reusable vars
+DOCKER := docker compose $(COMPOSE_FILE)
+COMPOSER_RUNTIME := composer-runtime
+DEV_RUNTIME := dev-runtime
+MIGRATION_CONTAINER := migration-container
+
+PROTOC_GEN_DIR := ./protoc-gen-php-grpc-2025.1.5-darwin-arm64
+PROTOC_GEN := $(PROTOC_GEN_DIR)/protoc-gen-php-grpc
+PROTOC_URL := https://github.com/roadrunner-server/roadrunner/releases/download/v2025.1.5/protoc-gen-php-grpc-2025.1.5-darwin-arm64.tar.gz
+
+DEV := $(DOCKER) exec $(DEV_RUNTIME) sh -c
+COMPOSER := $(DOCKER) exec $(COMPOSER_RUNTIME) sh -c
+
+# Colors
+GREEN := \033[32m
+YELLOW := \033[33m
+RESET := \033[0m
+
+# Fancy emoji
+SPARK := ✨
+ROCKET := 🚀
+WARN := ⚠️
+MAGNIFY := 🔍
+BUG := 🐞
+COMPOSE := 🐳
+TRASH := 🧹
+PROTO := 🧩
+CHECK := ✅
+CROSS := ❌
+
+# Align width for help display
+HELP_COL_WIDTH := 26
+
+# Help: auto-generate from targets with "##" comments
+help: ## Show this help
+	@echo "$(SPARK) Available commands:"
+	@awk -F':|##' '/^[a-zA-Z0-9._-]+:.*##/ {printf "  %-$(HELP_COL_WIDTH)s - %s\n", $$1, $$3}' $(MAKEFILE_LIST) | sort
+
+start: ## Start the development runtime container
+	@printf "$(GREEN)$(ROCKET) Starting $(DEV_RUNTIME)$(RESET)\n"
+	$(DOCKER)  up $(DEV_RUNTIME) -d --no-recreate
+
+sh: ## Open a shell in the development runtime container
+	@$(MAKE) start
+	$(DOCKER) exec $(DEV_RUNTIME) sh
+
+run: ## Run the application server in the development runtime container
+	@$(MAKE) start
+	$(DEV) "rr serve"
+
+stop: ## Stop and remove the development runtime container
+	@printf "$(YELLOW)$(WARN) Stopping all containers$(RESET)\n"
+	$(DOCKER) down
+
+restart: ## Restart dev container (stop + start)
+	@$(MAKE) stop
+	@$(MAKE) start
+
+rebuild: ## Rebuild containers (useful after Dockerfile changes)
+	@printf "$(YELLOW)$(SPARK) Rebuilding containers$(RESET)\n"
+	@$(MAKE) stop
+	@printf "$(YELLOW)$(TRASH) Deleting all Docker resources$(RESET)\n"
+	docker system prune --all --volumes --force
+	@$(MAKE) start
+
+ps: ## Show docker compose ps
+	$(DOCKER) ps
+
+migrate: ## Run database migrations in the migration container
+	$(DOCKER) up $(MIGRATION_CONTAINER)
+
+# Composer helpers
+composer-install: ## Install PHP dependencies in the composer runtime container
+	@printf "$(COMPOSE) $(GREEN)Installing PHP dependencies in $(COMPOSER_RUNTIME)$(RESET)\n"
+	@$(DOCKER) up $(COMPOSER_RUNTIME) -d --no-recreate
+	$(COMPOSER) "composer install --no-interaction --prefer-dist --optimize-autoloader --ignore-platform-reqs"
+
+composer-require: ## Require a PHP package in the composer runtime container (usage: make composer-require package=vendor/package)
+ifndef package
+	$(error package variable is required: make composer-require package=vendor/package)
+endif
+	@printf "$(COMPOSE) $(MAGNIFY) Requiring package $(package) in $(COMPOSER_RUNTIME)$(RESET)\n"
+	@$(DOCKER) up $(COMPOSER_RUNTIME) -d --no-recreate
+	$(COMPOSER) "composer require $(package) --ignore-platform-reqs"
+
+composer-require-dev: ## Require a PHP package as dev in the composer runtime container (usage: make composer-require-dev package=vendor/package)
+ifndef package
+	$(error package variable is required: make composer-require-dev package=vendor/package)
+endif
+	@printf "$(COMPOSE) $(MAGNIFY) Requiring dev package $(package) in $(COMPOSER_RUNTIME)$(RESET)\n"
+	@$(DOCKER) up $(COMPOSER_RUNTIME) -d --no-recreate
+	$(COMPOSER) "composer require --dev $(package) --ignore-platform-reqs"
+
+composer-update: ## Update PHP dependencies in the composer runtime container
+	@printf "$(COMPOSE) $(MAGNIFY) Updating PHP dependencies$(RESET)\n"
+	@$(DOCKER) up $(COMPOSER_RUNTIME) -d --no-recreate
+	$(COMPOSER) "composer update --no-interaction --prefer-dist --optimize-autoloader --ignore-platform-reqs"
+
+enable-debug: ## Enable Xdebug in the development runtime container
+	@$(DOCKER) up $(DEV_RUNTIME) -d --no-recreate
+	@printf "$(GREEN)$(BUG) Enabling Xdebug in $(DEV_RUNTIME)$(RESET)\n"
+	$(DEV) "bin/xdebug.sh"
+
+enable-coverage: ## Enable PCOV code coverage in the composer runtime container
+	@printf "$(GREEN)$(MAGNIFY) Enabling PCOV in $(COMPOSER_RUNTIME)$(RESET)\n"
+	@$(DOCKER) up $(COMPOSER_RUNTIME) -d --no-recreate
+	$(COMPOSER) "bin/pcov.sh"
+
+protoc: ## Generate PHP gRPC code from .proto files
+	@printf "$(PROTO) $(GREEN)Setting up protoc-gen-php-grpc plugin$(RESET)\n"
+	@curl -LOs $(PROTOC_URL)
+	@tar -xzf protoc-gen-php-grpc-2025.1.5-darwin-arm64.tar.gz
+	@printf "$(PROTO) $(GREEN)Generating PHP gRPC code from .proto files$(RESET)\n"
+	@protoc --plugin=./protoc-gen-php-grpc-2025.1.5-darwin-arm64/protoc-gen-php-grpc \
+	       --php_out=./generated \
+	       --php-grpc_out=./generated \
+	       protos/example.proto
+	@printf "$(TRASH) $(GREEN)Cleaning up protoc-gen-php-grpc plugin files$(RESET)\n"
+	@rm -rf $(PROTOC_GEN_DIR) protoc-gen-php-grpc-2025.1.5-darwin-arm64.tar.gz
+
+license-check: ## Check license headers in source files
+	@printf "$(MAGNIFY) $(GREEN)Checking license headers$(RESET)\n"
+	@$(DOCKER) up $(COMPOSER_RUNTIME) -d --no-recreate
+	$(COMPOSER) "composer run-script tests:license || true"
+
+# Developer tasks
+lint: ## Run linting (phpcs/phpstan) in composer runtime
+	@printf "$(MAGNIFY) $(GREEN)Running linters$(RESET)\n"
+	@$(DOCKER) up $(COMPOSER_RUNTIME) -d --no-recreate
+	$(COMPOSER) "composer run-script tests:lint || true"
+	$(COMPOSER) "composer run-script tests:phpstan || true"
+
+fmt: ## Format code (php-cs-fixer)
+	@printf "$(MAGNIFY) $(GREEN)Formatting code$(RESET)\n"
+	@$(DOCKER)  up $(COMPOSER_RUNTIME) -d --no-recreate
+	$(COMPOSER) "composer run-script tests:lint:fix"
+
+test: ## Run test suite (phpunit)
+	@printf "$(CHECK) $(GREEN)Running unit tests$(RESET)\n"
+	@$(DOCKER) up $(COMPOSER_RUNTIME) -d
+	$(COMPOSER) "composer run-script tests:unit || true"
+
+test-coverage: ## Run test suite with coverage report
+	@printf "$(CHECK) $(GREEN)Running unit tests with coverage report$(RESET)\n"
+	@$(DOCKER) up $(COMPOSER_RUNTIME) -d
+	@$(MAKE) enable-coverage
+	$(COMPOSER) "composer run-script tests:unit:coverage || true"
+
+# Convenience aliases
+dev: run ## Alias for start
+ci: composer-install migrate license-check lint test ## CI-like local flow
+down: stop ## Alias for stop
+up: start ## Alias for start
+
+.PONY: help start sh run stop restart rebuild ps migrate composer-install composer-require composer-require-dev composer-update enable-debug enable-coverage protoc license-check lint fmt test test-coverage dev ci down up

protos/example.proto

@@ -0,0 +1,23 @@
+syntax = "proto3";
+
+option go_package = "proto/greeter";
+option php_namespace = "GRPC\\Greeter";
+option php_metadata_namespace = "GRPC\\GPBMetadata";
+
+package helloworld;
+
+// The greeting service definition.
+service Greeter {
+  // Sends a greeting
+  rpc SayHello (HelloRequest) returns (HelloReply) {}
+}
+
+// The request message containing the user's name.
+message HelloRequest {
+  string name = 1;
+}
+
+// The response message containing the greetings
+message HelloReply {
+  string message = 1;
+}

server.php

@@ -5,10 +5,7 @@ use Siteworxpro\App\Api;
 require __DIR__ . '/vendor/autoload.php';
 
 try {
-    // Instantiate the ExternalServer class
     $server = new Api();
-
-    // Start the server
     $server->startServer();
 } catch (JsonException $e) {
     echo $e->getMessage();

src/Api.php

@@ -6,17 +6,20 @@ 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 Siteworxpro\HttpStatus\CodesEnum;
 use Spiral\RoadRunner\Http\PSR7Worker;
 use Spiral\RoadRunner\Worker;
 
@@ -69,8 +72,14 @@ class Api
 
         $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());
@@ -104,28 +113,20 @@ class Api
                 $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(
+                    JsonResponseFactory::createJsonResponse(new NotFoundResponse($uri))
-                        ['status_code' => 404, 'reason_phrase' => 'Not Found'],
-                        CodesEnum::NOT_FOUND
-                    )
                 );
             } catch (\Throwable $e) {
                 Logger::error($e->getMessage());
                 Logger::error($e->getTraceAsString());
 
-                $json = ['status_code' => 500, 'reason_phrase' => 'Server Error'];
-                if (Config::get("server.dev_mode")) {
-                    $json = [
-                        'status_code' => 500,
-                        'reason_phrase' => 'Server Error',
-                        'message' => $e->getMessage(),
-                        'trace' => $e->getTraceAsString(),
-                    ];
-                }
-
                 $this->worker->respond(
-                    JsonResponseFactory::createJsonResponse($json, CodesEnum::INTERNAL_SERVER_ERROR)
+                    JsonResponseFactory::createJsonResponse(new ServerErrorResponse($e))
                 );
             }
         }

src/Cli/App.php

@@ -8,6 +8,7 @@ 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;
 
@@ -21,7 +22,7 @@ class App
     public function __construct()
     {
         Kernel::boot();
-        $this->app = new Application('Php-Template', Config::get('app.version') ?? 'dev-master');
+        $this->app = new Application('Php-Template', Version::VERSION);
 
         $this->app->add(new DemoCommand());
         $this->app->add(new Start());

src/Controllers/Controller.php

@@ -6,7 +6,9 @@ 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
@@ -15,6 +17,18 @@ use Psr\Http\Message\ResponseInterface;
  *
  * @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
 {
     /**

src/Controllers/HealthcheckController.php

@@ -8,9 +8,11 @@ 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\Models\Model;
 use Siteworxpro\App\Services\Facades\Redis;
 use Siteworxpro\HttpStatus\CodesEnum;
+use OpenApi\Attributes as OA;
 
 /**
  * Class HealthcheckController
@@ -22,8 +24,13 @@ use Siteworxpro\HttpStatus\CodesEnum;
 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 {
@@ -47,7 +54,7 @@ class HealthcheckController extends Controller
         }
 
         return JsonResponseFactory::createJsonResponse(
-            ['status_code' => 200, 'message' => 'Healthcheck OK']
+            new GenericResponse('Healthcheck OK', CodesEnum::OK->value)
         );
     }
 }

src/Controllers/IndexController.php

@@ -7,7 +7,11 @@ namespace Siteworxpro\App\Controllers;
 use Nyholm\Psr7\ServerRequest;
 use Psr\Http\Message\ResponseInterface;
 use Siteworxpro\App\Attributes\Guards;
+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;
 
 /**
  * Class IndexController
@@ -24,18 +28,34 @@ class IndexController extends Controller
     #[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
     {
-        return JsonResponseFactory::createJsonResponse(['status_code' => 200, 'message' => 'Server is running']);
+        return JsonResponseFactory::createJsonResponse(new GenericResponse('Server is running'));
     }
 
     /**
+     * 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(['status_code' => 200, 'message' => 'Server is running']);
+        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,26 @@
+<?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: 'status_code', type: 'integer', example: 401),
+                        new OA\Property(property: 'message', type: 'string', example: 'Unauthorized'),
+                    ]
+                )
+            )
+        );
+    }
+}

src/Events/Dispatcher.php

@@ -45,6 +45,16 @@ class Dispatcher implements DispatcherContract, Arrayable
         $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.
      *

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,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\GrpcHandlers;
+
+use GRPC\Greeter\GreeterInterface;
+use GRPC\Greeter\HelloReply;
+use GRPC\Greeter\HelloRequest;
+use Spiral\RoadRunner\GRPC;
+
+class GreeterHandler implements GreeterInterface
+{
+    public function SayHello(GRPC\ContextInterface $ctx, HelloRequest $in): HelloReply // phpcs:ignore
+    {
+        $reply = new HelloReply();
+        $reply->setMessage('Hello ' . $in->getName());
+
+        return $reply;
+    }
+}

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

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Siteworxpro\App\Http;
 
+use Illuminate\Contracts\Support\Arrayable;
 use Nyholm\Psr7\Response;
 use Siteworxpro\HttpStatus\CodesEnum;
 
@@ -17,13 +18,19 @@ class JsonResponseFactory
     /**
      * Create a JSON response with the given data and status code.
      *
-     * @param array $data The data to include in the response.
+     * @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 $data, CodesEnum $statusCode = CodesEnum::OK): Response
+    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: [

src/Http/Middleware/JwtMiddleware.php

@@ -6,7 +6,6 @@ namespace Siteworxpro\App\Http\Middleware;
 
 use Carbon\Carbon;
 use Carbon\WrapperClock;
-use GuzzleHttp\Client;
 use GuzzleHttp\Exception\GuzzleException;
 use Lcobucci\JWT\JwtFacade;
 use Lcobucci\JWT\Signer\Hmac\Sha256 as Hmac256;
@@ -28,6 +27,7 @@ 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;
 
@@ -133,21 +133,21 @@ class JwtMiddleware extends Middleware
                     }
 
                     return JsonResponseFactory::createJsonResponse([
-                        'status_code' => 401,
+                        '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' => 401,
+                        'status_code' => CodesEnum::UNAUTHORIZED->value,
                         'message' => 'Unauthorized: Invalid token',
                     ], CodesEnum::UNAUTHORIZED);
-                } catch (GuzzleException) {
+                } catch (GuzzleException | \RuntimeException) {
                     return JsonResponseFactory::createJsonResponse([
-                        'status_code' => 501,
+                        'status_code' => CodesEnum::INTERNAL_SERVER_ERROR->value,
-                        'message' => 'Token validation service unavailable',
+                        'message' => 'Token validation service unavailable or unknown error',
-                    ], CodesEnum::UNAUTHORIZED);
+                    ], CodesEnum::INTERNAL_SERVER_ERROR);
                 }
 
                 // Expose all token claims as request attributes for downstream consumers.
@@ -170,7 +170,6 @@ class JwtMiddleware extends Middleware
      * @return SignedWith Signature constraint used during JWT parsing.
      *
      * @throws \RuntimeException When no signing key is configured.
-     * @throws GuzzleException On JWKS key retrieval issues.
      * @throws \JsonException
      */
     private function getSignedWith(string $token): SignedWith
@@ -188,7 +187,7 @@ class JwtMiddleware extends Middleware
         } elseif (str_contains($keyConfig, '.well-known/')) {
             $jwt = explode('.', $token);
             if (count($jwt) !== 3) {
-                throw new \RuntimeException('Invalid JWT structure for JWKS key retrieval.');
+                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
@@ -205,9 +204,6 @@ class JwtMiddleware extends Middleware
         return new SignedWith(new Hmac256(), $key);
     }
 
-    /**
-     * @throws GuzzleException
-     */
     private function getJwksKey(string $url, string $keyId): Key
     {
         $cached = Redis::get('jwks_key_' . $keyId);
@@ -215,15 +211,14 @@ class JwtMiddleware extends Middleware
             return InMemory::plainText($cached);
         }
 
-        $client = new Client();
+        $openIdConfig = Guzzle::get($url);
-        $openIdConfig = $client->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 = $client->get($jwksUri);
+        $jwksResponse = Guzzle::get($jwksUri);
         $jwksBody = json_decode(
             $jwksResponse->getBody()->getContents(),
             true,
@@ -234,7 +229,7 @@ class JwtMiddleware extends Middleware
         $firstKey = array_filter(
             $jwksBody['keys'],
             fn($key) => $key['kid'] === $keyId
-        )[0] ?? null;
+        )[0] ?? $jwksBody['keys'][0] ?? null;
 
         if (empty($firstKey)) {
             throw new \RuntimeException('No matching key found in JWKS for key ID: ' . $keyId);

src/Http/Responses/GenericResponse.php

@@ -0,0 +1,32 @@
+<?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.'),
+        new OA\Property(property: 'status_code', type: 'integer', example: 200),
+    ]
+)]
+readonly class GenericResponse implements Arrayable
+{
+    public function __construct(
+        private string $message = '',
+        private int $statusCode = 200
+    ) {
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'message' => $this->message,
+            'status_code' => $this->statusCode,
+        ];
+    }
+}

src/Http/Responses/NotFoundResponse.php

@@ -0,0 +1,40 @@
+<?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: 'status_code', type: 'integer', example: 404),
+        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 [
+            'status_code' => CodesEnum::NOT_FOUND->value,
+            '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: 'status_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 [
+                'status_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 [
+            'status_code' => $this->e->getCode() != 0 ?
+                $this->e->getCode() :
+                CodesEnum::INTERNAL_SERVER_ERROR->value,
+            'message' => 'An internal server error occurred.',
+        ];
+    }
+}

src/Models/User.php

@@ -5,11 +5,13 @@ declare(strict_types=1);
 namespace Siteworxpro\App\Models;
 
 use Carbon\Carbon;
+use OpenApi\Attributes as OA;
+use Siteworxpro\App\Helpers\Ulid;
 
 /**
  * Class User
  *
- * @property string $id
+ * @property-read string $id
  * @property string $first_name
  * @property string $last_name
  * @property string $email
@@ -19,6 +21,23 @@ use Carbon\Carbon;
  * @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 = [
@@ -36,6 +55,12 @@ class User extends Model
         '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";

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;
+    }
+}

tests/Controllers/IndexControllerTest.php

@@ -20,7 +20,7 @@ class IndexControllerTest extends AbstractController
         $response = $controller->get($this->getMockRequest());
 
         $this->assertEquals(200, $response->getStatusCode());
-        $this->assertEquals('{"status_code":200,"message":"Server is running"}', (string)$response->getBody());
+        $this->assertEquals('{"message":"Server is running","status_code":200}', (string)$response->getBody());
     }
 
     /**
@@ -35,6 +35,6 @@ class IndexControllerTest extends AbstractController
         $response = $controller->post($this->getMockRequest());
 
         $this->assertEquals(200, $response->getStatusCode());
-        $this->assertEquals('{"status_code":200,"message":"Server is running"}', (string)$response->getBody());
+        $this->assertEquals('{"message":"POST request received","status_code":200}', (string)$response->getBody());
     }
 }

tests/Controllers/OpenApiControllerTest.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Controllers;
+
+use Siteworxpro\App\Controllers\OpenApiController;
+
+class OpenApiControllerTest extends ControllerTest
+{
+    public function testBuildsYaml(): void
+    {
+        $request = $this->getMockRequest('/.well-known/openapi.yaml');
+        $controller = new OpenApiController();
+
+        $response = $controller->get($request);
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $this->assertStringContainsString('openapi: 3.0.0', (string)$response->getBody());
+    }
+
+    public function testBuildsJson(): void
+    {
+        $request = $this->getMockRequest(uri: '/.well-known/openapi.json');
+        $controller = new OpenApiController();
+
+        $response = $controller->get($request);
+
+        $this->assertEquals(200, $response->getStatusCode());
+        $this->assertEquals('application/json', $response->getHeaderLine('Content-Type'));
+        $this->assertNotFalse(json_decode($response->getBody()->getContents()));
+    }
+}

tests/Events/DispatcherTest.php

@@ -0,0 +1,177 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Events;
+
+use Illuminate\Contracts\Container\BindingResolutionException;
+use Siteworxpro\Tests\Unit;
+
+class DispatcherTest extends Unit
+{
+    /**
+     * @throws \Throwable
+     * @throws BindingResolutionException
+     */
+    public function testRegistersListeners(): void
+    {
+        $dispatcher = $this->getContainer()->make('Siteworxpro\App\Events\Dispatcher');
+
+        $eventFired = false;
+        $dispatcher->listen('TestEvent', function ($event) use (&$eventFired) {
+            $this->assertEquals('TestEvent', $event);
+            $eventFired = true;
+        });
+
+        $dispatcher->dispatch('TestEvent');
+        $this->assertTrue($eventFired, 'The TestEvent listener was not fired.');
+    }
+
+    /**
+     * @throws BindingResolutionException
+     */
+    public function testPushesEvents()
+    {
+        $dispatcher = $this->getContainer()->make('Siteworxpro\App\Events\Dispatcher');
+
+        $eventsFired = 0;
+        $dispatcher->listen('PushedEvent1', function ($event) use (&$eventsFired) {
+            $eventsFired++;
+            $this->assertEquals('PushedEvent1', $event);
+        });
+
+        $dispatcher->listen('PushedEvent2', function ($event) use (&$eventsFired) {
+            $eventsFired++;
+            $this->assertEquals('PushedEvent2', $event);
+        });
+
+        $dispatcher->push('PushedEvent1');
+        $dispatcher->push('PushedEvent2');
+
+        unset($dispatcher); // Trigger destructor
+        $this->assertEquals(2, $eventsFired);
+    }
+
+    /**
+     * @throws BindingResolutionException
+     * @throws \Throwable
+     */
+    public function testFlushEvent(): void
+    {
+        $dispatcher = $this->getContainer()->make('Siteworxpro\App\Events\Dispatcher');
+
+        $eventFired = false;
+        $dispatcher->listen('FlushEvent', function ($event) use (&$eventFired) {
+            $this->assertEquals('FlushEvent', $event);
+            $eventFired = true;
+        });
+
+        $dispatcher->push('FlushEvent');
+        $dispatcher->flush('FlushEvent');
+
+        $this->assertTrue($eventFired, 'The FlushEvent listener was not fired.');
+    }
+
+    /**
+     * @throws BindingResolutionException
+     */
+    public function testHasListeners(): void
+    {
+        $dispatcher = $this->getContainer()->make('Siteworxpro\App\Events\Dispatcher');
+
+        $this->assertFalse(
+            $dispatcher->hasListeners(
+                'NonExistentEvent'
+            ),
+            'Expected no listeners for NonExistentEvent.'
+        );
+
+        $dispatcher->listen('ExistingEvent', function () {
+            // Listener logic
+        });
+
+        $this->assertTrue(
+            $dispatcher->hasListeners(
+                'ExistingEvent'
+            ),
+            'Expected listeners for ExistingEvent.'
+        );
+    }
+
+    /**
+     * @throws BindingResolutionException
+     * @throws \Throwable
+     */
+    public function testForgetEvent(): void
+    {
+        $dispatcher = $this->getContainer()->make('Siteworxpro\App\Events\Dispatcher');
+
+        $eventFired = false;
+        $dispatcher->listen('ForgetEvent', function ($event) use (&$eventFired) {
+            $this->assertEquals('ForgetEvent', $event);
+            $eventFired = true;
+        });
+
+        $dispatcher->push('ForgetEvent');
+        $dispatcher->forget('ForgetEvent');
+
+        unset($dispatcher); // Trigger destructor
+
+        $this->assertFalse($eventFired, 'The ForgetEvent listener was fired but should have been forgotten.');
+    }
+
+    /**
+     * @throws BindingResolutionException
+     */
+    public function testForgetPushed()
+    {
+        $this->expectNotToPerformAssertions();
+
+        $dispatcher = $this->getContainer()->make('Siteworxpro\App\Events\Dispatcher');
+
+        $dispatcher->listen('EventToForget', function () {
+            $this->fail('The EventToForget listener was fired but should have been forgotten.');
+        });
+
+        $dispatcher->push('EventToForget');
+        $dispatcher->forgetPushed();
+
+        unset($dispatcher); // Trigger destructor
+    }
+
+    /**
+     * @throws BindingResolutionException
+     */
+    public function testToArray(): void
+    {
+        $dispatcher = $this->getContainer()->make('Siteworxpro\App\Events\Dispatcher');
+
+        $dispatcher->listen('ArrayEvent', function () {
+            // Listener logic
+        });
+
+        $arrayRepresentation = $dispatcher->toArray();
+        $this->assertArrayHasKey('ArrayEvent', $arrayRepresentation);
+    }
+
+    /**
+     * @throws BindingResolutionException
+     * @throws \Throwable
+     */
+    public function testSubscriber()
+    {
+        $subscriber = $this->getMockBuilder('Siteworxpro\App\Events\Subscribers\Subscriber')
+            ->onlyMethods(['handle'])
+            ->getMock();
+
+        $subscriber->expects($this->once())
+            ->method('handle')
+            ->with('SubscribedEvent', [])
+            ->willReturn(null);
+
+        $dispatcher = $this->getContainer()->make('Siteworxpro\App\Events\Dispatcher');
+        $dispatcher->subscribe($subscriber);
+
+        $dispatcher->dispatch('SubscribedEvent');
+    }
+}

tests/Facades/GuzzleTest.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Facades;
+
+use GuzzleHttp\Client;
+use Siteworxpro\App\Services\Facades\Guzzle;
+
+class GuzzleTest extends AbstractFacade
+{
+    protected function getFacadeClass(): string
+    {
+        return Guzzle::class;
+    }
+
+    protected function getConcrete(): string
+    {
+        return Client::class;
+    }
+}

tests/Http/Middleware/JwtMiddlewareTest.php

@@ -15,12 +15,63 @@ use Nyholm\Psr7\ServerRequest;
 use Siteworxpro\App\Attributes\Guards\Jwt;
 use Siteworxpro\App\Http\Middleware\JwtMiddleware;
 use Siteworxpro\App\Services\Facades\Config;
+use Siteworxpro\App\Services\Facades\Guzzle;
+use Siteworxpro\App\Services\Facades\Redis;
 use Siteworxpro\HttpStatus\CodesEnum;
 
 class JwtMiddlewareTest extends Middleware
 {
     private const string TEST_SIGNING_KEY = 'test_signing_key_123456444478901234';
 
+    private const string TEST_RSA_PRIVATE_KEY = <<<EOD
+-----BEGIN RSA PRIVATE KEY-----
+MIIEpQIBAAKCAQEAqTheAdlelxJL0K15BqUEo0lBzY06P7J0PhMfPlg2fgIJH+ng
+ZmrpYFhBkj2L5Fnvxz0y58eu9WhhokwpS0GzgFIw+KfLV/WLX4PgionsQshrt0Pi
+XvthaSH1xuYtg2N13dVVTv3Au0BBFLUHMrQ+bO5hgvowHBNfFf0GaHLW2m0eZ2Um
+hWbtdv4HxrXBO5gI2N4UevyQ+inczN7RBZR6ZzyNoDO6Up6kS23/58zOruO+PGi7
+q9eb7hU+getpVgA29wEWMgT+N6c5n5AcENgM1sHxZK43GR5vhMGbVJqnrUsMGof7
+rT9Lxey3gjPS2r5nz2PNFcQ1i07QKDzvQHp2wwIDAQABAoIBAFMAC9QaWzP8TGWJ
+gNBKhnDU0MrSl5yAmlWMKYn52JiLxQ/7Ng7mJ5wTDe5986zIlDyEfwCCyAUk8qaZ
+drOsATBSoCSGoM1+6aKq26r4JYNILNVSHal64XegqZ2qbu6ADWMGbXZ2Ll9qD8Hp
+XSN4lxn0/q0wrAJJWh094zO+CDZP+zBbX9oHxb5JAVxjCaNW84sI6/6agXM5zzgK
+wcBt5Y0i8V8f7n9kg+CPNqY6BKg7o2ONFYTEVKuuEnVS/eupHQwBWExPCdxc85Tb
+YqFL0dmgehE0OTQ6FrEN7Xh6jE4GMJtWmTvBNpqhsMZ0i08tAZSPs+Us9rnppKkK
+T1SC2xECgYEA7yOv4C7dtHmFbn0YfnbBEfgvGAubv5jPDtZ5u6tUEhhU3rOcWexM
+Xhj7OFV4I8lbu2t7GY+2BR7Y2ikOLW9MrOGo6qWhsjTQuZs6QaRKObcPvl2s0LYY
+GxD1u84VjHPzID2pKVPqxaQ7KdcIaujAedWwAf4PV/uK2prKdGvzIksCgYEAtSau
+4Ml1UpXvKxiBcVKsHIoEO0g3NL1+wAbdStg8TFi+leCMJoPwZ01t64BTtHF+pgDP
+vn6VEgDSP3J4+W3dVhoajQeKBioT3MpDRP/qKDsImi2zJrg+hh9DMTlZd0Ab3EXv
+ycjw3FWRcpcU/1l261fA/m3QPwZikF2VlO/0cmkCgYEAvtefCuy718RHHObOPlZt
+O/bxNmJFOEEttOyql39iB1LNoDB8bTLruwh6q/lheEXAZDChO8P5gdqdOnUbMF0r
+Nqib0i6+fOYzUHw1oJ8I8UhLUyOUv7ciQ69kPC15+u2psCglMKscp/+pi3lk6VS4
+DkLfRKfI/PDsXgq72O8xSEMCgYEApukSnvngyQxvR1UYB7N19AHTLlA21bh4LjTk
+905QGMR4Lp6sY9yTyIsWabRe69bbK9d5kvsNHX52OpGeF6z8EJaSujklGtLwZDJV
+UyE9vn3OSkkrVdTTfz8U6Sj/XxpJ0Wb7LwCftVR+ZIgCh9kF8ohzwbqq8zdN39jq
+t0V1BWkCgYEA2Mk2gOdYAN8aZgydFYKhogY5UNK/CFpq7hhekEyt73uxzxguVpZn
+AJ9mq2L1CVJ5WqAUk2IzioeR7XAndntesbOafDuR4mhCUJhX+m/YQlKbTrs2dScR
+S88z05AnmQmr5eCbQmVULZGo9xeLDB+GDWvvjpQ+NWcha2uO0O0RTQY=
+-----END RSA PRIVATE KEY-----
+EOD;
+
+    private const string TEST_JWKS_JSON = <<<EOD
+{
+    "keys": [
+        {
+          "alg": "RS256",
+          "e": "AQAB",
+          "ext": true,
+          "key_ops": [
+            "verify"
+          ],
+          "kty": "RSA",
+          "n": "qTheAdlelxJL0K15BqUEo0lBzY06P7J0PhMfPlg2fgIJH-ngZmrpYFhBkj2L5Fnvxz0y58eu9WhhokwpS0GzgFIw-KfLV_WLX4PgionsQshrt0PiXvthaSH1xuYtg2N13dVVTv3Au0BBFLUHMrQ-bO5hgvowHBNfFf0GaHLW2m0eZ2UmhWbtdv4HxrXBO5gI2N4UevyQ-inczN7RBZR6ZzyNoDO6Up6kS23_58zOruO-PGi7q9eb7hU-getpVgA29wEWMgT-N6c5n5AcENgM1sHxZK43GR5vhMGbVJqnrUsMGof7rT9Lxey3gjPS2r5nz2PNFcQ1i07QKDzvQHp2ww",
+          "kid": "2o5IaHnjxYtkpNWEcdPlwnaRJnaCJ2k2LY2nR4z6cN4=",
+          "use": "sig"
+        }
+    ]
+}
+EOD;
+
     public function getClass(): object
     {
         return new class {
@@ -51,7 +102,7 @@ class JwtMiddlewareTest extends Middleware
         $class = new class {
             public function getCallable(): array
             {
-                return [ $this, 'index' ];
+                return [$this, 'index'];
             }
 
             public function index()
@@ -208,6 +259,91 @@ class JwtMiddlewareTest extends Middleware
         $this->assertEquals(CodesEnum::OK->value, $response->getStatusCode());
     }
 
+    /**
+     * @throws \JsonException
+     */
+    public function testJwtFromJwkEndpoint()
+    {
+        Config::set('jwt.audience', 'https://client-app.io');
+        Config::set('jwt.issuer', 'https://api.my-awesome-app.io');
+
+        Redis::partialMock()->shouldReceive('get')->andReturn(null);
+        Redis::shouldReceive('set')->andReturn('OK');
+        Guzzle::partialMock()->shouldReceive('get')
+            ->with('https://test.com/.well-known/openid-configuration')
+            ->andReturn(new Response(200, [], json_encode([
+                'jwks_uri' => 'https://test.com/keys'
+            ], JSON_THROW_ON_ERROR)));
+
+        Guzzle::shouldReceive('get')
+            ->with('https://test.com/keys')
+            ->andReturn(new Response(200, [], self::TEST_JWKS_JSON));
+
+        Config::set('jwt.signing_key', 'https://test.com/.well-known/openid-configuration');
+
+        $class = $this->getClass();
+
+        $handler = \Mockery::mock(Dispatcher::class);
+        $handler->shouldReceive('getMiddlewareStack')
+            ->andReturn([$class]);
+        $handler
+            ->shouldReceive('handle')
+            ->once()
+            ->andReturn(new Response(200));
+
+        $request = new ServerRequest('GET', '/');
+        $request = $request->withHeader('Authorization', 'Bearer ' . $this->getJwtRsa());
+        $middleware = new JwtMiddleware();
+        $response = $middleware->process($request, $handler);
+        $this->assertEquals(CodesEnum::OK->value, $response->getStatusCode());
+    }
+
+    /**
+     * @throws \JsonException
+     */
+    public function testCatchesInvalidJwksUrl()
+    {
+        Config::set('jwt.signing_key', 'https://test.com/.well-known/openid-configuration');
+        Redis::partialMock()->shouldReceive('get')->andReturn(null);
+        Redis::shouldReceive('set')->andReturn('OK');
+        Guzzle::partialMock()->shouldReceive('get')
+            ->with('https://test.com/.well-known/openid-configuration')
+            ->andReturn(new Response(200, [], json_encode([], JSON_THROW_ON_ERROR)));
+
+
+
+        $class = $this->getClass();
+
+        $handler = \Mockery::mock(Dispatcher::class);
+        $handler->shouldReceive('getMiddlewareStack')
+            ->andReturn([$class]);
+
+        $request = new ServerRequest('GET', '/');
+        $request = $request->withHeader('Authorization', 'Bearer ' . $this->getJwtRsa());
+        $middleware = new JwtMiddleware();
+        $response = $middleware->process($request, $handler);
+        $this->assertEquals(CodesEnum::INTERNAL_SERVER_ERROR->value, $response->getStatusCode());
+    }
+
+    private function getJwtRsa(): string
+    {
+        $key = InMemory::plainText(self::TEST_RSA_PRIVATE_KEY);
+        $signer = new \Lcobucci\JWT\Signer\Rsa\Sha256();
+        $token = new JwtFacade()->issue(
+            $signer,
+            $key,
+            static fn(
+                Builder $builder,
+                DateTimeImmutable $issuedAt
+            ): Builder => $builder
+                ->issuedBy('https://api.my-awesome-app.io')
+                ->permittedFor('https://client-app.io')
+                ->expiresAt($issuedAt->modify('+10 minutes'))
+        );
+
+        return $token->toString();
+    }
+
     private function getJwt(): string
     {
         $key = InMemory::plainText(self::TEST_SIGNING_KEY);
@@ -216,7 +352,7 @@ class JwtMiddlewareTest extends Middleware
         $token = new JwtFacade()->issue(
             $signer,
             $key,
-            static fn (
+            static fn(
                 Builder $builder,
                 DateTimeImmutable $issuedAt
             ): Builder => $builder

tests/Http/Responses/NotFoundResponseTest.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Siteworxpro\Tests\Http\Responses;
+
+use Siteworxpro\App\Http\Responses\NotFoundResponse;
+use Siteworxpro\Tests\Unit;
+
+class NotFoundResponseTest extends Unit
+{
+    public function testToArray(): void
+    {
+        $response = new NotFoundResponse('/api/resource', ['key' => 'value']);
+
+        $expected = [
+            'status_code' => 404,
+            'message' => 'The requested resource /api/resource was not found.',
+            'context' => ['key' => 'value'],
+        ];
+
+        $this->assertEquals($expected, $response->toArray());
+    }
+}

tests/Http/Responses/ServerErrorResponseTest.php

@@ -0,0 +1,89 @@
+<?php
+
+namespace Siteworxpro\Tests\Http\Responses;
+
+use Siteworxpro\App\Http\Responses\ServerErrorResponse;
+use Siteworxpro\App\Services\Facades\Config;
+use Siteworxpro\Tests\Unit;
+
+class ServerErrorResponseTest extends Unit
+{
+    public function testToArrayInDevMode(): void
+    {
+        Config::set('app.dev_mode', true);
+
+        try {
+            // Simulate an exception to generate a server error response
+            throw new \Exception('A Test Error occurred.');
+        } catch (\Exception $e) {
+            $response = new ServerErrorResponse($e, ['operation' => 'data_processing']);
+
+            $expected = [
+                'status_code' => 500,
+                'message' => 'A Test Error occurred.',
+                'context' => [
+                    'operation' => 'data_processing'
+                ],
+                'file' => $e->getFile(),
+                'line' => $e->getLine(),
+                'trace' => $e->getTrace(),
+            ];
+
+            $this->assertEquals($expected, $response->toArray());
+        }
+    }
+
+    public function testToArrayNotInDevMode(): void
+    {
+        try {
+            throw new \Exception('A Test Error occurred.');
+        } catch (\Exception $exception) {
+            $response = new ServerErrorResponse($exception);
+
+            $expected = [
+                'status_code' => 500,
+                'message' => 'An internal server error occurred.',
+            ];
+
+            $this->assertEquals($expected, $response->toArray());
+        }
+    }
+
+    public function testToArrayIfCodeIsSet(): void
+    {
+        try {
+            throw new \Exception('A Test Error occurred.', 1234);
+        } catch (\Exception $exception) {
+            $response = new ServerErrorResponse($exception);
+
+            $expected = [
+                'status_code' => 1234,
+                'message' => 'An internal server error occurred.',
+            ];
+
+            $this->assertEquals($expected, $response->toArray());
+        }
+    }
+
+    public function testToArrayIfCodeIsSetDevMode(): void
+    {
+        Config::set('app.dev_mode', true);
+
+        try {
+            throw new \Exception('A Test Error occurred.', 1234);
+        } catch (\Exception $exception) {
+            $response = new ServerErrorResponse($exception);
+
+            $expected = [
+                'status_code' => 1234,
+                'message' => 'A Test Error occurred.',
+                'file' => $exception->getFile(),
+                'line' =>  $exception->getLine(),
+                'trace' => $exception->getTrace(),
+                'context' => [],
+            ];
+
+            $this->assertEquals($expected, $response->toArray());
+        }
+    }
+}

tests/Models/UserTest.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\Models;
+
+use Siteworxpro\App\Models\User;
+use Siteworxpro\Tests\Unit;
+
+class UserTest extends Unit
+{
+    public function testFormatsName(): void
+    {
+        $user = new User();
+        $user->first_name = 'John';
+        $user->last_name = 'Doe';
+
+        $this->assertEquals('John Doe', $user->full_name);
+    }
+
+    public function testFormatsEmail(): void
+    {
+        $user = new User();
+        $user->first_name = 'Jane';
+        $user->last_name = 'Smith';
+        $user->email = 'jane.smith@email.com';
+
+        $this->assertEquals('Jane Smith <jane.smith@email.com>', $user->formatted_email);
+    }
+}

tests/ServiceProviders/DispatcherServiceProviderTest.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\Tests\ServiceProviders;
+
+use Siteworxpro\App\Services\ServiceProviders\DispatcherServiceProvider;
+
+class DispatcherServiceProviderTest extends AbstractServiceProvider
+{
+    protected function getProviderClass(): string
+    {
+        return DispatcherServiceProvider::class;
+    }
+}

tests/Unit.php

@@ -13,13 +13,25 @@ use Siteworxpro\App\Services\Facades\Config;
 
 abstract class Unit extends TestCase
 {
+    protected function getContainer(): Container
+    {
+        $container = Facade::getFacadeContainer();
+        if ($container === null) {
+            $container = new Container();
+            Facade::setFacadeContainer($container);
+
+            return $container;
+        }
+
+        return $container;
+    }
+
     /**
      * @throws \ReflectionException
      */
     protected function setUp(): void
     {
-        $container = new Container();
+        $container = $this->getContainer();
-        Facade::setFacadeContainer($container);
 
         $container->bind(SWConfig::class, function () {
             return SWConfig::load(__DIR__ . '/../config.php');