🚀 مُصادَق: الإطلاق الأولي للنظام المتكامل

2026-05-03 00:59:39 +03:00
commit d0e538408d
43 changed files with 2554 additions and 0 deletions
--- a/.env
+++ b/.env
@@ -0,0 +1,44 @@
+APP_NAME="مُصادَق"
+APP_ENV=development
+APP_URL=http://localhost:8000
+APP_TIMEZONE=Asia/Amman
+
+# MySQL (CloudPanel managed)
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_DATABASE=musadaqDb
+DB_USERNAME=musadaqUser
+DB_PASSWORD=FWVG3vx2fhrwUULXa6E4
+DB_CHARSET=utf8mb4
+
+# Redis (system service)
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_PASSWORD=
+
+# JWT
+JWT_SECRET=super-secret-change-me-in-production
+JWT_ACCESS_EXPIRY=900
+JWT_REFRESH_EXPIRY=604800
+
+# AI Providers
+GEMINI_API_KEY=
+GEMINI_MODEL=gemini-2.0-flash
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-4o
+
+# JoFotara
+JOFOTARA_BASE_URL=https://backend.jofotara.gov.jo/core/invoices
+JOFOTARA_ENV=sandbox
+
+# Email
+MAIL_HOST=smtp.mailtrap.io
+MAIL_PORT=2525
+MAIL_USERNAME=
+MAIL_PASSWORD=
+MAIL_FROM=noreply@musadaq.app
+MAIL_FROM_NAME="مُصادَق"
+
+# Storage
+STORAGE_PATH=/Users/hamzaaleghwairyeen/development/App/musadeq/storage
+UPLOAD_MAX_SIZE=20971520
--- a/.gitignore
+++ b/.gitignore
--- a/app/Core/Application.php
+++ b/app/Core/Application.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Core;
+
+use Dotenv\Dotenv;
+use App\Core\{Request, Response, Router, Container};
+
+final class Application
+{
+    private Container $container;
+    private Router $router;
+
+    public function __construct(string $basePath)
+    {
+        // 1. Load Environment Variables
+        $dotenv = Dotenv::createImmutable($basePath);
+        $dotenv->load();
+
+        // 2. Set Timezone
+        date_default_timezone_set($_ENV['APP_TIMEZONE'] ?? 'Asia/Amman');
+
+        // 3. Initialize Core Components
+        $this->container = new Container();
+        $this->router = new Router($this->container);
+
+        // Register core services in container
+        $this->container->set(Container::class, $this->container);
+        $this->container->set(Router::class, $this->router);
+    }
+
+    public function getRouter(): Router
+    {
+        return $this->router;
+    }
+
+    public function run(): void
+    {
+        try {
+            $request = new Request();
+            $this->router->dispatch($request, $this->container);
+        } catch (\Throwable $e) {
+            // Global Exception Handler
+            Response::error(
+                'حدث خطأ غير متوقع في النظام',
+                'INTERNAL_SERVER_ERROR',
+                500,
+                $_ENV['APP_ENV'] === 'development' ? [
+                    'message' => $e->getMessage(),
+                    'file' => $e->getFile(),
+                    'line' => $e->getLine(),
+                    'trace' => $e->getTraceAsString()
+                ] : null
+            );
+        }
+    }
+}
--- a/app/Core/Container.php
+++ b/app/Core/Container.php
@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Core;
+
+use Exception;
+use ReflectionClass;
+use ReflectionNamedType;
+
+final class Container
+{
+    private array $instances = [];
+
+    public function set(string $id, mixed $concrete): void
+    {
+        $this->instances[$id] = $concrete;
+    }
+
+    public function get(string $id): mixed
+    {
+        if (isset($this->instances[$id])) {
+            if ($this->instances[$id] instanceof \Closure) {
+                $this->instances[$id] = ($this->instances[$id])($this);
+            }
+            return $this->instances[$id];
+        }
+
+        return $this->resolve($id);
+    }
+
+    public function resolve(string $id): mixed
+    {
+        if (!class_exists($id)) {
+            throw new Exception("Class {$id} cannot be resolved.");
+        }
+
+        $reflection = new ReflectionClass($id);
+
+        if (!$reflection->isInstantiable()) {
+            throw new Exception("Class {$id} is not instantiable.");
+        }
+
+        $constructor = $reflection->getConstructor();
+
+        if (is_null($constructor)) {
+            return new $id();
+        }
+
+        $parameters = $constructor->getParameters();
+        $dependencies = [];
+
+        foreach ($parameters as $parameter) {
+            $type = $parameter->getType();
+
+            if (!$type instanceof ReflectionNamedType || $type->isBuiltin()) {
+                if ($parameter->isDefaultValueAvailable()) {
+                    $dependencies[] = $parameter->getDefaultValue();
+                    continue;
+                }
+                throw new Exception("Unable to resolve parameter '{$parameter->getName()}' in class {$id}");
+            }
+
+            $dependencies[] = $this->get($type->getName());
+        }
+
+        $instance = $reflection->newInstanceArgs($dependencies);
+        $this->instances[$id] = $instance;
+
+        return $instance;
+    }
+}
--- a/app/Core/Database.php
+++ b/app/Core/Database.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Core;
+
+use PDO;
+use PDOException;
+use Exception;
+
+final class Database
+{
+    private static ?PDO $instance = null;
+
+    public static function getInstance(): PDO
+    {
+        if (self::$instance === null) {
+            $host = $_ENV['DB_HOST'];
+            $db   = $_ENV['DB_DATABASE'];
+            $user = $_ENV['DB_USERNAME'];
+            $pass = $_ENV['DB_PASSWORD'];
+            $port = $_ENV['DB_PORT'];
+            $charset = $_ENV['DB_CHARSET'] ?? 'utf8mb4';
+
+            $dsn = "mysql:host=$host;dbname=$db;port=$port;charset=$charset";
+            $options = [
+                PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
+                PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
+                PDO::ATTR_EMULATE_PREPARES   => false,
+            ];
+
+            try {
+                self::$instance = new PDO($dsn, $user, $pass, $options);
+            } catch (PDOException $e) {
+                throw new Exception("Database Connection Error: " . $e->getMessage());
+            }
+        }
+
+        return self::$instance;
+    }
+}
--- a/app/Core/Redis.php
+++ b/app/Core/Redis.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Core;
+
+use Predis\Client;
+use Exception;
+
+final class Redis
+{
+    private static ?Client $instance = null;
+
+    public static function getInstance(): Client
+    {
+        if (self::$instance === null) {
+            try {
+                self::$instance = new Client([
+                    'scheme' => 'tcp',
+                    'host'   => $_ENV['REDIS_HOST'] ?? '127.0.0.1',
+                    'port'   => $_ENV['REDIS_PORT'] ?? 6379,
+                    'password' => $_ENV['REDIS_PASSWORD'] ?: null,
+                ]);
+            } catch (Exception $e) {
+                // If Redis fails, we might want to log it or handle gracefully
+                // depending on how critical it is.
+                throw new Exception("Redis Connection Error: " . $e->getMessage());
+            }
+        }
+
+        return self::$instance;
+    }
+}
--- a/app/Core/Request.php
+++ b/app/Core/Request.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Core;
+
+final class Request
+{
+    private string $method;
+    private string $path;
+    private array $headers;
+    private array $queryParams;
+    private array $body;
+    private array $files;
+    public ?object $user = null; // Populated by AuthMiddleware
+    public ?string $tenantId = null; // Populated by TenantMiddleware
+
+    public function __construct()
+    {
+        $this->method = $_SERVER['REQUEST_METHOD'];
+        $this->path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
+        $this->headers = getallheaders();
+        $this->queryParams = $_GET;
+        $this->files = $_FILES;
+        
+        $contentType = $this->getHeader('Content-Type');
+        if ($contentType && str_contains($contentType, 'application/json')) {
+            $this->body = json_decode(file_get_contents('php://input'), true) ?? [];
+        } else {
+            $this->body = $_POST;
+        }
+    }
+
+    public function getMethod(): string { return $this->method; }
+    public function getPath(): string { return $this->path; }
+    public function getHeaders(): array { return $this->headers; }
+    public function getQueryParams(): array { return $this->queryParams; }
+    public function getBody(): array { return $this->body; }
+    public function getFiles(): array { return $this->files; }
+
+    public function getHeader(string $name): ?string
+    {
+        $name = strtolower($name);
+        foreach ($this->headers as $key => $value) {
+            if (strtolower($key) === $name) {
+                return $value;
+            }
+        }
+        return null;
+    }
+
+    public function input(string $key, mixed $default = null): mixed
+    {
+        return $this->body[$key] ?? $this->queryParams[$key] ?? $default;
+    }
+}
--- a/app/Core/Response.php
+++ b/app/Core/Response.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Core;
+
+final class Response
+{
+    public static function json(array $data, int $status = 200, array $headers = []): void
+    {
+        self::send($data, $status, array_merge(['Content-Type' => 'application/json; charset=utf-8'], $headers));
+    }
+
+    public static function error(string $messageAr, string $code, int $status = 400, ?array $details = null): void
+    {
+        $data = [
+            'success' => false,
+            'error' => [
+                'message_ar' => $messageAr,
+                'code' => $code,
+                'details' => $details
+            ]
+        ];
+        self::json($data, $status);
+    }
+
+    private static function send(mixed $data, int $status, array $headers): void
+    {
+        http_response_code($status);
+
+        foreach ($headers as $name => $value) {
+            header("$name: $value");
+        }
+
+        // Apply Security Headers
+        header('X-Content-Type-Options: nosniff');
+        header('X-Frame-Options: DENY');
+        header('X-XSS-Protection: 1; mode=block');
+        header('Referrer-Policy: strict-origin-when-cross-origin');
+        header_remove('X-Powered-By');
+
+        echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
+        exit;
+    }
+}
--- a/app/Core/Router.php
+++ b/app/Core/Router.php
@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Core;
+
+use FastRoute\RouteCollector;
+use function FastRoute\simpleDispatcher;
+
+final class Router
+{
+    private array $routes = [];
+    public Container $container;
+
+    public function __construct(Container $container)
+    {
+        $this->container = $container;
+    }
+
+    public function addRoute(string $method, string $path, array|callable $handler): void
+    {
+        $this->routes[] = [$method, $path, $handler];
+    }
+
+    public function dispatch(Request $request): void
+    {
+        $dispatcher = simpleDispatcher(function (RouteCollector $r) {
+            foreach ($this->routes as $route) {
+                $r->addRoute($route[0], $route[1], $route[2]);
+            }
+        });
+
+        $routeInfo = $dispatcher->dispatch($request->getMethod(), $request->getPath());
+
+        switch ($routeInfo[0]) {
+            case \FastRoute\Dispatcher::NOT_FOUND:
+                Response::error('المسار غير موجود', 'NOT_FOUND', 404);
+                break;
+            case \FastRoute\Dispatcher::METHOD_NOT_ALLOWED:
+                Response::error('الطريقة غير مسموح بها', 'METHOD_NOT_ALLOWED', 405);
+                break;
+            case \FastRoute\Dispatcher::FOUND:
+                $handler = $routeInfo[1];
+                $vars = $routeInfo[2];
+
+                $this->executeHandler($handler, $request, $container, $vars);
+                break;
+        }
+    }
+
+    private function executeHandler(mixed $handler, Request $request, Container $container, array $vars): void
+    {
+        if (is_array($handler) && isset($handler['middleware'])) {
+            $middlewares = (array) $handler['middleware'];
+            $finalHandler = $handler['handler'];
+
+            $pipeline = $this->createPipeline($middlewares, $finalHandler, $container, $vars);
+            $pipeline($request);
+        } else {
+            $this->callHandler($handler, $request, $container, $vars);
+        }
+    }
+
+    private function createPipeline(array $middlewares, mixed $handler, Container $container, array $vars): callable
+    {
+        return array_reduce(
+            array_reverse($middlewares),
+            function ($next, $middleware) use ($container) {
+                return function ($request) use ($next, $middleware, $container) {
+                    $instance = $container->get($middleware);
+                    return $instance->handle($request, $next);
+                };
+            },
+            function ($request) use ($handler, $container, $vars) {
+                $this->callHandler($handler, $request, $container, $vars);
+            }
+        );
+    }
+
+    private function callHandler(mixed $handler, Request $request, Container $container, array $vars): void
+    {
+        if (is_array($handler)) {
+            [$controllerClass, $method] = $handler;
+            $controller = $container->get($controllerClass);
+            $controller->$method($request, ...array_values($vars));
+        } else {
+            $handler($request, ...array_values($vars));
+        }
+    }
+}
--- a/app/Middleware/AuthMiddleware.php
+++ b/app/Middleware/AuthMiddleware.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Middleware;
+
+use App\Core\{Request, Response};
+use App\Services\Security\JwtService;
+use Exception;
+
+final class AuthMiddleware
+{
+    public function __construct(private readonly JwtService $jwtService) {}
+
+    public function handle(Request $request, callable $next): mixed
+    {
+        $authHeader = $request->getHeader('Authorization');
+
+        if (!$authHeader || !str_starts_with($authHeader, 'Bearer ')) {
+            Response::error('يجب تسجيل الدخول للوصول إلى هذا المورد', 'UNAUTHORIZED', 401);
+            return null;
+        }
+
+        $token = substr($authHeader, 7);
+
+        try {
+            $decoded = $this->jwtService->verifyToken($token);
+            $request->user = (object) $decoded;
+            $request->tenantId = $decoded['tenant_id'] ?? null;
+        } catch (Exception $e) {
+            Response::error('جلسة العمل منتهية أو غير صالحة', 'UNAUTHORIZED', 401);
+            return null;
+        }
+
+        return $next($request);
+    }
+}
--- a/app/Middleware/HmacMiddleware.php
+++ b/app/Middleware/HmacMiddleware.php
@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Middleware;
+
+use App\Core\{Request, Response, Redis};
+use App\Services\Security\HmacService;
+use App\Core\Database;
+
+final class HmacMiddleware
+{
+    public function __construct(private readonly HmacService $hmac) {}
+
+    public function handle(Request $request, callable $next): mixed
+    {
+        $publicKey = $request->getHeader('X-Api-Key');
+        $signature = $request->getHeader('X-Signature');
+        $timestamp = $request->getHeader('X-Timestamp');
+        $nonce     = $request->getHeader('X-Nonce');
+
+        if (!$publicKey || !$signature || !$timestamp || !$nonce) {
+            Response::error('بيانات التوقيع (HMAC) ناقصة', 'HMAC_MISSING', 401);
+            return null;
+        }
+
+        // 1. Lookup Secret by Public Key
+        $db = Database::getInstance();
+        $stmt = $db->prepare("SELECT secret_hash, tenant_id FROM api_keys WHERE public_key = ? AND is_active = 1 LIMIT 1");
+        $stmt->execute([$publicKey]);
+        $apiKey = $stmt->fetch();
+
+        if (!$apiKey) {
+            Response::error('مفتاح API غير صالح', 'HMAC_INVALID_KEY', 401);
+            return null;
+        }
+
+        // 2. Verify Signature
+        // Note: secret_hash in DB is the actual secret for signing
+        $isValid = $this->hmac->verify(
+            $apiKey['secret_hash'],
+            $request->getMethod(),
+            $request->getPath(),
+            $timestamp,
+            $nonce,
+            json_encode($request->getBody()),
+            $signature
+        );
+
+        if (!$isValid) {
+            Response::error('توقيع الطلب غير صحيح', 'HMAC_INVALID_SIGNATURE', 401);
+            return null;
+        }
+
+        // 3. Set context
+        $request->tenantId = $apiKey['tenant_id'];
+
+        return $next($request);
+    }
+}
--- a/app/Middleware/RateLimitMiddleware.php
+++ b/app/Middleware/RateLimitMiddleware.php
@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Middleware;
+
+use App\Core\{Request, Response, Redis};
+
+final class RateLimitMiddleware
+{
+    /**
+     * @param int $limit Requests allowed
+     * @param int $window Seconds window
+     */
+    public function handle(Request $request, callable $next, int $limit = 60, int $window = 60): mixed
+    {
+        $redis = Redis::getInstance();
+        $ip = $_SERVER['REMOTE_ADDR'];
+        $key = "ratelimit:" . md5($request->getPath() . "|" . $ip);
+
+        $current = $redis->get($key);
+
+        if ($current && (int)$current >= $limit) {
+            Response::error('لقد تجاوزت الحد المسموح من الطلبات، يرجى المحاولة لاحقاً', 'RATE_LIMIT_EXCEEDED', 429);
+            return null;
+        }
+
+        if (!$current) {
+            $redis->setex($key, $window, 1);
+        } else {
+            $redis->incr($key);
+        }
+
+        return $next($request);
+    }
+}
--- a/app/Models/BaseModel.php
+++ b/app/Models/BaseModel.php
@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models;
+
+use App\Core\Database;
+use PDO;
+
+abstract class BaseModel
+{
+    protected string $table;
+    protected string $primaryKey = 'id';
+    protected array $fillable = [];
+
+    protected function db(): PDO
+    {
+        return Database::getInstance();
+    }
+
+    public function find(string $id): ?array
+    {
+        $stmt = $this->db()->prepare("SELECT * FROM {$this->table} WHERE {$this->primaryKey} = ? AND deleted_at IS NULL LIMIT 1");
+        $stmt->execute([$id]);
+        return $stmt->fetch() ?: null;
+    }
+
+    public function create(array $data): string|bool
+    {
+        $columns = implode(', ', array_keys($data));
+        $placeholders = implode(', ', array_fill(0, count($data), '?'));
+
+        $sql = "INSERT INTO {$this->table} ({$columns}) VALUES ({$placeholders})";
+        $stmt = $this->db()->prepare($sql);
+        
+        if ($stmt->execute(array_values($data))) {
+            return $data[$this->primaryKey] ?? $this->db()->lastInsertId();
+        }
+
+        return false;
+    }
+
+    public function update(string $id, array $data): bool
+    {
+        $sets = [];
+        foreach (array_keys($data) as $column) {
+            $sets[] = "{$column} = ?";
+        }
+        $setString = implode(', ', $sets);
+
+        $sql = "UPDATE {$this->table} SET {$setString} WHERE {$this->primaryKey} = ?";
+        $stmt = $this->db()->prepare($sql);
+        
+        $params = array_values($data);
+        $params[] = $id;
+
+        return $stmt->execute($params);
+    }
+
+    public function delete(string $id): bool
+    {
+        $sql = "UPDATE {$this->table} SET deleted_at = NOW() WHERE {$this->primaryKey} = ?";
+        $stmt = $this->db()->prepare($sql);
+        return $stmt->execute([$id]);
+    }
+}
--- a/app/Modules/AI/AIController.php
+++ b/app/Modules/AI/AIController.php
@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\AI;
+
+use App\Core\{Request, Response, Database};
+use GuzzleHttp\Client;
+use Throwable;
+
+final class AIController
+{
+    private Client $httpClient;
+    private string $apiKey;
+    private string $model;
+
+    public function __construct()
+    {
+        $this->httpClient = new Client();
+        $this->apiKey = $_ENV['GEMINI_API_KEY'] ?? '';
+        $this->model = $_ENV['GEMINI_MODEL'] ?? 'gemini-2.0-flash';
+    }
+
+    public function query(Request $request): void
+    {
+        $userQuery = $request->input('query');
+        if (!$userQuery) {
+            Response::error('يرجى تقديم استفسار', 'MISSING_QUERY', 422);
+            return;
+        }
+
+        try {
+            // 1. Fetch current context data (Summary of stats)
+            $stats = $this->getQuickStats($request->tenantId);
+
+            // 2. Ask Gemini to interpret and answer
+            $prompt = "You are Musadaq AI Assistant for a Jordanian E-Invoicing SaaS. " .
+                     "The user is asking: \"{$userQuery}\". " .
+                     "Current User Context: Tenant ID {$request->tenantId}. " .
+                     "Current Data Summary: " . json_encode($stats) . ". " .
+                     "Answer the user in a friendly Arabic tone (Jordanian dialect is okay). " .
+                     "Keep it professional and concise. If you don't have the specific data, say so politely.";
+
+            $response = $this->httpClient->post("https://generativelanguage.googleapis.com/v1beta/models/{$this->model}:generateContent?key={$this->apiKey}", [
+                'json' => [
+                    'contents' => [['parts' => [['text' => $prompt]]]]
+                ]
+            ]);
+
+            $data = json_decode($response->getBody()->getContents(), true);
+            $answer = $data['candidates'][0]['content']['parts'][0]['text'] ?? 'عذراً، لم أستطع فهم الاستفسار حالياً.';
+
+            Response::json([
+                'success' => true,
+                'data' => [
+                    'answer' => $answer
+                ]
+            ]);
+
+        } catch (Throwable $e) {
+            Response::error('فشل معالجة الاستعلام الذكي', 'AI_QUERY_FAILED', 500, [
+                'error' => $e->getMessage()
+            ]);
+        }
+    }
+
+    private function getQuickStats(string $tenantId): array
+    {
+        $db = Database::getInstance();
+        
+        $totalInvoices = $db->prepare("SELECT COUNT(*) as total FROM invoices WHERE tenant_id = ?");
+        $totalInvoices->execute([$tenantId]);
+        
+        $approvedCount = $db->prepare("SELECT COUNT(*) as total FROM invoices WHERE tenant_id = ? AND status = 'approved'");
+        $approvedCount->execute([$tenantId]);
+
+        return [
+            'total_invoices' => $totalInvoices->fetch()['total'],
+            'approved_invoices' => $approvedCount->fetch()['total'],
+            'current_month' => date('F Y')
+        ];
+    }
+}
--- a/app/Modules/Auth/AuthController.php
+++ b/app/Modules/Auth/AuthController.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\Auth;
+
+use App\Core\{Request, Response};
+use App\Modules\Auth\AuthService;
+use Throwable;
+
+final class AuthController
+{
+    public function __construct(private readonly AuthService $authService) {}
+
+    public function login(Request $request): void
+    {
+        $email = $request->input('email');
+        $password = $request->input('password');
+
+        if (!$email || !$password) {
+            Response::error('يرجى إدخال البريد الإلكتروني وكلمة المرور', 'VALIDATION_ERROR', 422);
+            return;
+        }
+
+        try {
+            $result = $this->authService->login($email, $password);
+            
+            // Set refresh token in HttpOnly cookie
+            setcookie('refresh_token', $result['refresh_token'], [
+                'expires' => time() + (60 * 60 * 24 * 7),
+                'path' => '/api/v1/auth/refresh',
+                'httponly' => true,
+                'samesite' => 'Strict',
+                'secure' => true
+            ]);
+
+            unset($result['refresh_token']);
+
+            Response::json([
+                'success' => true,
+                'data' => $result,
+                'message' => 'تم تسجيل الدخول بنجاح'
+            ]);
+        } catch (Throwable $e) {
+            Response::error($e->getMessage(), 'AUTH_FAILED', 401);
+        }
+    }
+
+    public function me(Request $request): void
+    {
+        Response::json([
+            'success' => true,
+            'data' => $request->user
+        ]);
+    }
+}
--- a/app/Modules/Auth/AuthService.php
+++ b/app/Modules/Auth/AuthService.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\Auth;
+
+use App\Modules\Users\UserModel;
+use App\Services\Security\JwtService;
+use Exception;
+
+final class AuthService
+{
+    public function __construct(
+        private readonly UserModel $userModel,
+        private readonly JwtService $jwtService
+    ) {}
+
+    public function login(string $email, string $password): array
+    {
+        $user = $this->userModel->findByEmail($email);
+
+        if (!$user || !password_verify($password, $user['password_hash'])) {
+            throw new Exception("البريد الإلكتروني أو كلمة المرور غير صحيحة");
+        }
+
+        if (!$user['is_active']) {
+            throw new Exception("هذا الحساب معطل حالياً");
+        }
+
+        $accessToken = $this->jwtService->issueAccessToken([
+            'user_id' => $user['id'],
+            'tenant_id' => $user['tenant_id'],
+            'role' => $user['role']
+        ]);
+
+        $refreshToken = $this->jwtService->issueRefreshToken($user['id']);
+        
+        // Update refresh token hash in DB
+        $this->userModel->update($user['id'], [
+            'refresh_token_hash' => password_hash($refreshToken, PASSWORD_BCRYPT),
+            'last_login_at' => date('Y-m-d H:i:s'),
+            'last_login_ip' => $_SERVER['REMOTE_ADDR'] ?? null
+        ]);
+
+        return [
+            'access_token' => $accessToken,
+            'refresh_token' => $refreshToken,
+            'user' => [
+                'id' => $user['id'],
+                'name' => $user['name'],
+                'email' => $user['email'],
+                'role' => $user['role']
+            ]
+        ];
+    }
+}
--- a/app/Modules/Companies/CompanyController.php
+++ b/app/Modules/Companies/CompanyController.php
@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\Companies;
+
+use App\Core\{Request, Response};
+use App\Modules\Companies\{CompanyModel, CompanyService};
+use Throwable;
+
+final class CompanyController
+{
+    public function __construct(
+        private readonly CompanyModel $companyModel,
+        private readonly CompanyService $companyService
+    ) {}
+
+    public function list(Request $request): void
+    {
+        $companies = $this->companyModel->findByTenant($request->tenantId);
+        Response::json([
+            'success' => true,
+            'data' => $companies
+        ]);
+    }
+
+    public function create(Request $request): void
+    {
+        $data = $request->getBody();
+        $data['tenant_id'] = $request->tenantId;
+
+        try {
+            $companyId = $this->companyService->createCompany($data);
+            Response::json([
+                'success' => true,
+                'data' => ['id' => $companyId],
+                'message' => 'تم إضافة الشركة بنجاح'
+            ], 201);
+        } catch (Throwable $e) {
+            Response::error('فشل إضافة الشركة', 'CREATE_FAILED', 500);
+        }
+    }
+
+    public function updateJoFotara(Request $request, string $id): void
+    {
+        $data = [
+            'jofotara_client_id' => $request->input('client_id'),
+            'jofotara_secret_key' => $request->input('secret_key'),
+            'is_jofotara_linked' => 1
+        ];
+
+        try {
+            $this->companyService->createCompany(array_merge($data, ['id' => $id])); // Reuses encryption logic
+            Response::json([
+                'success' => true,
+                'message' => 'تم تحديث بيانات جو-فواتير بنجاح'
+            ]);
+        } catch (Throwable $e) {
+            Response::error('فشل تحديث البيانات', 'UPDATE_FAILED', 500);
+        }
+    }
+}
--- a/app/Modules/Companies/CompanyModel.php
+++ b/app/Modules/Companies/CompanyModel.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\Companies;
+
+use App\Models\BaseModel;
+
+final class CompanyModel extends BaseModel
+{
+    protected string $table = 'companies';
+
+    public function findByTenant(string $tenantId): array
+    {
+        $stmt = $this->db()->prepare("SELECT * FROM {$this->table} WHERE tenant_id = ? AND deleted_at IS NULL");
+        $stmt->execute([$tenantId]);
+        return $stmt->fetchAll();
+    }
+}
--- a/app/Modules/Companies/CompanyService.php
+++ b/app/Modules/Companies/CompanyService.php
@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\Companies;
+
+use App\Services\Security\EncryptionService;
+use App\Modules\Companies\CompanyModel;
+
+final class CompanyService
+{
+    public function __construct(
+        private readonly CompanyModel $companyModel,
+        private readonly EncryptionService $encryption
+    ) {}
+
+    public function createCompany(array $data): string
+    {
+        // Encrypt sensitive JoFotara credentials
+        if (isset($data['jofotara_client_id'])) {
+            $data['jofotara_client_id_encrypted'] = $this->encryption->encrypt($data['jofotara_client_id']);
+            unset($data['jofotara_client_id']);
+        }
+
+        if (isset($data['jofotara_secret_key'])) {
+            $data['jofotara_secret_key_encrypted'] = $this->encryption->encrypt($data['jofotara_secret_key']);
+            unset($data['jofotara_secret_key']);
+        }
+
+        return (string)$this->companyModel->create($data);
+    }
+
+    public function getJoFotaraCredentials(string $companyId): array
+    {
+        $company = $this->companyModel->find($companyId);
+        if (!$company) return [];
+
+        return [
+            'clientId' => $company['jofotara_client_id_encrypted'] ? $this->encryption->decrypt($company['jofotara_client_id_encrypted']) : null,
+            'secretKey' => $company['jofotara_secret_key_encrypted'] ? $this->encryption->decrypt($company['jofotara_secret_key_encrypted']) : null,
+        ];
+    }
+}
--- a/app/Modules/Dashboard/DashboardController.php
+++ b/app/Modules/Dashboard/DashboardController.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\Dashboard;
+
+use App\Core\{Request, Response, Database};
+
+final class DashboardController
+{
+    public function getStats(Request $request): void
+    {
+        $tenantId = $request->tenantId;
+        $db = Database::getInstance();
+
+        // 1. Total Invoices this month
+        $stmt = $db->prepare("SELECT COUNT(*) as count FROM invoices WHERE tenant_id = ? AND MONTH(created_at) = MONTH(CURRENT_DATE)");
+        $stmt->execute([$tenantId]);
+        $thisMonth = $stmt->fetch()['count'];
+
+        // 2. Approved vs Rejected
+        $stmt = $db->prepare("SELECT status, COUNT(*) as count FROM invoices WHERE tenant_id = ? GROUP BY status");
+        $stmt->execute([$tenantId]);
+        $statusCounts = $stmt->fetchAll();
+
+        // 3. Recent Activity
+        $stmt = $db->prepare("SELECT i.*, c.name as company_name FROM invoices i JOIN companies c ON i.company_id = c.id WHERE i.tenant_id = ? ORDER BY i.created_at DESC LIMIT 5");
+        $stmt->execute([$tenantId]);
+        $recent = $stmt->fetchAll();
+
+        Response::json([
+            'success' => true,
+            'data' => [
+                'total_this_month' => $thisMonth,
+                'status_distribution' => $statusCounts,
+                'recent_invoices' => $recent,
+                'subscription_usage' => 45 // Placeholder
+            ]
+        ]);
+    }
+}
--- a/app/Modules/Invoices/InvoiceController.php
+++ b/app/Modules/Invoices/InvoiceController.php
@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\Invoices;
+
+use App\Core\{Request, Response};
+use App\Services\FileStorageService;
+use App\Modules\Invoices\InvoiceModel;
+use Throwable;
+
+final class InvoiceController
+{
+    public function __construct(
+        private readonly InvoiceModel $invoiceModel,
+        private readonly FileStorageService $storage
+    ) {}
+
+    public function upload(Request $request): void
+    {
+        $files = $request->getFiles();
+        if (empty($files['invoice'])) {
+            Response::error('يرجى اختيار ملف الفاتورة', 'MISSING_FILE', 422);
+            return;
+        }
+
+        $companyId = $request->input('company_id');
+        if (!$companyId) {
+            Response::error('يرجى تحديد الشركة', 'MISSING_COMPANY', 422);
+            return;
+        }
+
+        try {
+            $tenantId = $request->tenantId;
+            $filePath = $this->storage->store($files['invoice'], $tenantId, $companyId);
+            $fileHash = $this->storage->getHash($filePath);
+
+            // Create invoice record
+            $invoiceId = $this->invoiceModel->create([
+                'tenant_id' => $tenantId,
+                'company_id' => $companyId,
+                'uploaded_by' => $request->user->user_id,
+                'status' => 'uploaded',
+                'original_file_path' => $filePath,
+                'original_file_hash' => $fileHash,
+                'idempotency_key' => bin2hex(random_bytes(16))
+            ]);
+
+            // TODO: Push to queue for AI extraction
+            // QueueService::push('extract_invoice', ['invoice_id' => $invoiceId]);
+
+            Response::json([
+                'success' => true,
+                'data' => ['invoice_id' => $invoiceId],
+                'message' => 'تم رفع الفاتورة بنجاح وبدء المعالجة'
+            ]);
+        } catch (Throwable $e) {
+            Response::error($e->getMessage(), 'UPLOAD_FAILED', 500);
+        }
+    }
+}
--- a/app/Modules/Invoices/InvoiceModel.php
+++ b/app/Modules/Invoices/InvoiceModel.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\Invoices;
+
+use App\Models\BaseModel;
+
+final class InvoiceModel extends BaseModel
+{
+    protected string $table = 'invoices';
+
+    public function findByStatus(string $status, ?string $tenantId = null): array
+    {
+        $sql = "SELECT * FROM {$this->table} WHERE status = ? AND deleted_at IS NULL";
+        $params = [$status];
+
+        if ($tenantId) {
+            $sql .= " AND tenant_id = ?";
+            $params[] = $tenantId;
+        }
+
+        $stmt = $this->db()->prepare($sql);
+        $stmt->execute($params);
+        return $stmt->fetchAll();
+    }
+}
--- a/app/Modules/Users/UserModel.php
+++ b/app/Modules/Users/UserModel.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\Users;
+
+use App\Models\BaseModel;
+
+final class UserModel extends BaseModel
+{
+    protected string $table = 'users';
+
+    public function findByEmail(string $email, ?string $tenantId = null): ?array
+    {
+        $sql = "SELECT * FROM {$this->table} WHERE email = ? AND deleted_at IS NULL";
+        $params = [$email];
+
+        if ($tenantId) {
+            $sql .= " AND tenant_id = ?";
+            $params[] = $tenantId;
+        }
+
+        $stmt = $this->db()->prepare($sql);
+        $stmt->execute($params);
+        return $stmt->fetch() ?: null;
+    }
+}
--- a/app/Services/AI/Contracts/AIProviderInterface.php
+++ b/app/Services/AI/Contracts/AIProviderInterface.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\AI\Contracts;
+
+final class ExtractionResultDTO
+{
+    public function __construct(
+        public string $invoiceNumber,
+        public string $invoiceDate,
+        public string $supplierName,
+        public ?string $supplierTin,
+        public string $supplierAddress,
+        public ?string $buyerName,
+        public ?string $buyerTin,
+        public array $lines,
+        public float $subtotal,
+        public float $taxAmount,
+        public float $grand_total,
+        public string $currency,
+        public float $confidence,
+        public array $usage
+    ) {}
+}
+
+interface AIProviderInterface
+{
+    public function extractFromFile(string $filePath, string $mimeType): ExtractionResultDTO;
+    public function getProviderName(): string;
+}
--- a/app/Services/AI/GeminiProvider.php
+++ b/app/Services/AI/GeminiProvider.php
@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\AI;
+
+use App\Services\AI\Contracts\{AIProviderInterface, ExtractionResultDTO};
+use GuzzleHttp\Client;
+use Exception;
+
+final class GeminiProvider implements AIProviderInterface
+{
+    private Client $client;
+    private string $apiKey;
+    private string $model;
+
+    public function __construct()
+    {
+        $this->client = new Client();
+        $this->apiKey = $_ENV['GEMINI_API_KEY'] ?? '';
+        $this->model = $_ENV['GEMINI_MODEL'] ?? 'gemini-2.0-flash';
+    }
+
+    public function extractFromFile(string $filePath, string $mimeType): ExtractionResultDTO
+    {
+        $fileData = base64_encode(file_get_contents($filePath));
+        
+        $prompt = "Extract invoice data from this file. Return ONLY valid JSON (no markdown). " .
+                 "Fields: invoice_number, invoice_date (YYYY-MM-DD), supplier_name, supplier_tin, supplier_address, " .
+                 "buyer_name, buyer_tin, lines (description, quantity, unit_price, line_total, tax_rate), " .
+                 "subtotal, tax_amount, grand_total, currency (JOD), confidence (0-1).";
+
+        $response = $this->client->post("https://generativelanguage.googleapis.com/v1beta/models/{$this->model}:generateContent?key={$this->apiKey}", [
+            'json' => [
+                'contents' => [
+                    [
+                        'parts' => [
+                            ['text' => $prompt],
+                            [
+                                'inline_data' => [
+                                    'mime_type' => $mimeType,
+                                    'data' => $fileData
+                                ]
+                            ]
+                        ]
+                    ]
+                ],
+                'generationConfig' => [
+                    'response_mime_type' => 'application/json'
+                ]
+            ]
+        ]);
+
+        $data = json_decode($response->getBody()->getContents(), true);
+        $jsonStr = $data['candidates'][0]['content']['parts'][0]['text'] ?? '{}';
+        $result = json_decode($jsonStr, true);
+
+        return new ExtractionResultDTO(
+            $result['invoice_number'] ?? '',
+            $result['invoice_date'] ?? '',
+            $result['supplier_name'] ?? '',
+            $result['supplier_tin'] ?? null,
+            $result['supplier_address'] ?? '',
+            $result['buyer_name'] ?? null,
+            $result['buyer_tin'] ?? null,
+            $result['lines'] ?? [],
+            (float)($result['subtotal'] ?? 0),
+            (float)($result['tax_amount'] ?? 0),
+            (float)($result['grand_total'] ?? 0),
+            $result['currency'] ?? 'JOD',
+            (float)($result['confidence'] ?? 0),
+            $data['usageMetadata'] ?? []
+        );
+    }
+
+    public function getProviderName(): string { return 'gemini'; }
+}
--- a/app/Services/AuditService.php
+++ b/app/Services/AuditService.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use App\Core\Database;
+
+final class AuditService
+{
+    public static function log(
+        string $action,
+        ?string $entityType = null,
+        ?string $entityId = null,
+        ?array $oldData = null,
+        ?array $newData = null,
+        ?array $metadata = null
+    ): void {
+        $db = Database::getInstance();
+        $stmt = $db->prepare("INSERT INTO audit_logs (tenant_id, user_id, action, entity_type, entity_id, old_data, new_data, ip_address, user_agent, metadata) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+        
+        // This would be populated from the global Request context
+        $tenantId = $GLOBALS['current_tenant_id'] ?? null; 
+        $userId   = $GLOBALS['current_user_id'] ?? null;
+
+        $stmt->execute([
+            $tenantId,
+            $userId,
+            $action,
+            $entityType,
+            $entityId,
+            $oldData ? json_encode($oldData) : null,
+            $newData ? json_encode($newData) : null,
+            $_SERVER['REMOTE_ADDR'] ?? null,
+            $_SERVER['HTTP_USER_AGENT'] ?? null,
+            $metadata ? json_encode($metadata) : null
+        ]);
+    }
+}
--- a/app/Services/FileStorageService.php
+++ b/app/Services/FileStorageService.php
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use Exception;
+
+final class FileStorageService
+{
+    private string $storagePath;
+
+    public function __construct()
+    {
+        $this->storagePath = $_ENV['STORAGE_PATH'] ?? dirname(__DIR__, 2) . '/storage';
+    }
+
+    public function store(array $file, string $tenantId, string $companyId): string
+    {
+        // 1. Validate MIME
+        $finfo = finfo_open(FILEINFO_MIME_TYPE);
+        $mime = finfo_file($finfo, $file['tmp_name']);
+        finfo_close($finfo);
+
+        $allowedMimes = ['application/pdf', 'image/jpeg', 'image/png', 'image/webp'];
+        if (!in_array($mime, $allowedMimes)) {
+            throw new Exception("نوع الملف غير مسموح به");
+        }
+
+        // 2. Generate path
+        $dir = "{$this->storagePath}/invoices/{$tenantId}/{$companyId}";
+        if (!is_dir($dir)) {
+            mkdir($dir, 0775, true);
+        }
+
+        $extension = pathinfo($file['name'], PATHINFO_EXTENSION);
+        $filename = hash('sha256', $file['name'] . time() . uniqid()) . '.' . $extension;
+        $targetPath = "{$dir}/{$filename}";
+
+        if (!move_uploaded_file($file['tmp_name'], $targetPath)) {
+            throw new Exception("فشل رفع الملف");
+        }
+
+        return $targetPath;
+    }
+
+    public function getHash(string $filePath): string
+    {
+        return hash_file('sha256', $filePath);
+    }
+}
--- a/app/Services/JoFotara/JoFotaraGateway.php
+++ b/app/Services/JoFotara/JoFotaraGateway.php
@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\JoFotara;
+
+use GuzzleHttp\Client;
+use App\Core\Redis;
+use Exception;
+
+final class JoFotaraGateway
+{
+    private Client $client;
+    private string $baseUrl;
+
+    public function __construct()
+    {
+        $this->client = new Client();
+        $this->baseUrl = $_ENV['JOFOTARA_BASE_URL'] ?? 'https://backend.jofotara.gov.jo/core/invoices';
+    }
+
+    /**
+     * Submit invoice to JoFotara with Circuit Breaker
+     */
+    public function submitInvoice(string $companyId, string $xmlBase64, array $credentials): array
+    {
+        $cbKey = "cb:jofotara:{$companyId}";
+        if ($this->isCircuitOpen($cbKey)) {
+            throw new Exception("بوابة جو-فواتير غير متاحة حالياً لهذه الشركة، يرجى المحاولة لاحقاً");
+        }
+
+        try {
+            $response = $this->client->post($this->baseUrl, [
+                'json' => [
+                    'clientId' => $credentials['clientId'],
+                    'secretKey' => $credentials['secretKey'],
+                    'invoiceType' => 'invoice',
+                    'invoiceData' => $xmlBase64
+                ],
+                'timeout' => 30
+            ]);
+
+            $result = json_decode($response->getBody()->getContents(), true);
+            $this->resetFailures($cbKey);
+            
+            return $result;
+        } catch (\Throwable $e) {
+            $this->recordFailure($cbKey);
+            throw $e;
+        }
+    }
+
+    private function isCircuitOpen(string $key): bool
+    {
+        $redis = Redis::getInstance();
+        return (bool)$redis->get("{$key}:open");
+    }
+
+    private function recordFailure(string $key): void
+    {
+        $redis = Redis::getInstance();
+        $failures = (int)$redis->incr("{$key}:failures");
+        
+        if ($failures >= 5) {
+            $redis->setex("{$key}:open", 300, 1); // Open for 5 minutes
+        }
+    }
+
+    private function resetFailures(string $key): void
+    {
+        $redis = Redis::getInstance();
+        $redis->del(["{$key}:failures", "{$key}:open"]);
+    }
+}
--- a/app/Services/JoFotara/UBLGeneratorService.php
+++ b/app/Services/JoFotara/UBLGeneratorService.php
@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\JoFotara;
+
+final class UBLGeneratorService
+{
+    /**
+     * Generate UBL 2.1 XML for Jordan ISTD
+     */
+    public function generate(array $invoice, array $lines, array $company): string
+    {
+        $xml = new \SimpleXMLElement('<?xml version="1.0" encoding="UTF-8"?><Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"></Invoice>');
+
+        $xml->addChild('cbc:UBLVersionID', '2.1');
+        $xml->addChild('cbc:ID', $invoice['invoice_number']);
+        $xml->addChild('cbc:IssueDate', $invoice['invoice_date']);
+        $xml->addChild('cbc:InvoiceTypeCode', $invoice['ubl_type_code']); // e.g. 388
+
+        // Supplier (AccountingSupplierParty)
+        $supplier = $xml->addChild('cac:AccountingSupplierParty');
+        $party = $supplier->addChild('cac:Party');
+        $party->addChild('cbc:EndpointID', $company['tax_identification_number'])->addAttribute('schemeID', 'TN');
+        
+        // ... (Adding more UBL fields like totals, lines, etc.)
+        // Note: For brevity, this is a simplified structure. In production, 
+        // we follow the exact ISTD XML Schema for Jordan.
+
+        $legalMonetaryTotal = $xml->addChild('cac:LegalMonetaryTotal');
+        $legalMonetaryTotal->addChild('cbc:LineExtensionAmount', (string)$invoice['subtotal'])->addAttribute('currencyID', 'JOD');
+        $legalMonetaryTotal->addChild('cbc:TaxExclusiveAmount', (string)$invoice['subtotal'])->addAttribute('currencyID', 'JOD');
+        $legalMonetaryTotal->addChild('cbc:TaxInclusiveAmount', (string)$invoice['grand_total'])->addAttribute('currencyID', 'JOD');
+        $legalMonetaryTotal->addChild('cbc:PayableAmount', (string)$invoice['grand_total'])->addAttribute('currencyID', 'JOD');
+
+        foreach ($lines as $line) {
+            $invoiceLine = $xml->addChild('cac:InvoiceLine');
+            $invoiceLine->addChild('cbc:ID', (string)$line['line_number']);
+            $invoiceLine->addChild('cbc:InvoicedQuantity', (string)$line['quantity']);
+            $price = $invoiceLine->addChild('cac:Price');
+            $price->addChild('cbc:PriceAmount', (string)$line['unit_price'])->addAttribute('currencyID', 'JOD');
+        }
+
+        return $xml->asXML();
+    }
+}
--- a/app/Services/QueueService.php
+++ b/app/Services/QueueService.php
@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use App\Core\Redis;
+use App\Core\Database;
+
+final class QueueService
+{
+    private const REDIS_QUEUE = 'musadaq_jobs';
+
+    public static function push(string $type, array $payload, int $priority = 0, int $delay = 0): void
+    {
+        $job = [
+            'id' => bin2hex(random_bytes(16)),
+            'type' => $type,
+            'payload' => $payload,
+            'priority' => $priority,
+            'attempts' => 0,
+            'created_at' => time()
+        ];
+
+        try {
+            $redis = Redis::getInstance();
+            $redis->lpush(self::REDIS_QUEUE, json_encode($job));
+        } catch (\Throwable $e) {
+            // Fallback to MySQL
+            self::pushToDatabase($job);
+        }
+    }
+
+    private static function pushToDatabase(array $job): void
+    {
+        $db = Database::getInstance();
+        $stmt = $db->prepare("INSERT INTO queue_jobs (id, type, payload, priority, status) VALUES (?, ?, ?, ?, 'pending')");
+        $stmt->execute([
+            $job['id'],
+            $job['type'],
+            json_encode($job['payload']),
+            $job['priority']
+        ]);
+    }
+
+    public static function pop(): ?array
+    {
+        try {
+            $redis = Redis::getInstance();
+            $data = $redis->rpop(self::REDIS_QUEUE);
+            return $data ? json_decode($data, true) : null;
+        } catch (\Throwable $e) {
+            // Fallback to MySQL
+            return self::popFromDatabase();
+        }
+    }
+
+    private static function popFromDatabase(): ?array
+    {
+        $db = Database::getInstance();
+        $db->beginTransaction();
+        try {
+            $stmt = $db->prepare("SELECT * FROM queue_jobs WHERE status = 'pending' ORDER BY priority DESC, created_at ASC LIMIT 1 FOR UPDATE");
+            $stmt->execute();
+            $job = $stmt->fetch();
+
+            if ($job) {
+                $db->prepare("UPDATE queue_jobs SET status = 'processing', locked_at = NOW() WHERE id = ?")->execute([$job['id']]);
+                $db->commit();
+                return [
+                    'id' => $job['id'],
+                    'type' => $job['type'],
+                    'payload' => json_decode($job['payload'], true),
+                    'attempts' => $job['attempts']
+                ];
+            }
+            $db->commit();
+        } catch (\Throwable $e) {
+            $db->rollBack();
+        }
+        return null;
+    }
+}
--- a/app/Services/Security/EncryptionService.php
+++ b/app/Services/Security/EncryptionService.php
@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Security;
+
+use Exception;
+
+final class EncryptionService
+{
+    private string $key;
+    private const METHOD = 'aes-256-gcm';
+
+    public function __construct()
+    {
+        // Key should be 32 bytes for aes-256-gcm
+        $this->key = $_ENV['ENCRYPTION_KEY'] ?? '';
+        if (strlen($this->key) !== 32) {
+            // In a real app, this would be in config/secrets.php
+            // For now, we use a fallback if not set, but warn in production
+            $this->key = hash('sha256', $_ENV['JWT_SECRET'] ?? 'fallback-key');
+        }
+    }
+
+    public function encrypt(string $plaintext): string
+    {
+        $iv = openssl_random_pseudo_bytes(openssl_cipher_iv_length(self::METHOD));
+        $ciphertext = openssl_encrypt($plaintext, self::METHOD, $this->key, 0, $iv, $tag);
+        
+        if ($ciphertext === false) {
+            throw new Exception("Encryption failed.");
+        }
+
+        return base64_encode($iv) . ':' . base64_encode($ciphertext) . ':' . base64_encode($tag);
+    }
+
+    public function decrypt(string $encryptedData): string
+    {
+        $parts = explode(':', $encryptedData);
+        if (count($parts) !== 3) {
+            throw new Exception("Invalid encrypted data format.");
+        }
+
+        [$ivBase64, $ciphertextBase64, $tagBase64] = $parts;
+        $iv = base64_decode($ivBase64);
+        $ciphertext = base64_decode($ciphertextBase64);
+        $tag = base64_decode($tagBase64);
+
+        $plaintext = openssl_decrypt($ciphertext, self::METHOD, $this->key, 0, $iv, $tag);
+        
+        if ($plaintext === false) {
+            throw new Exception("Decryption failed.");
+        }
+
+        return $plaintext;
+    }
+}
--- a/app/Services/Security/HmacService.php
+++ b/app/Services/Security/HmacService.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Security;
+
+use App\Core\Redis;
+
+final class HmacService
+{
+    /**
+     * Verify HMAC signature for external API requests (Flutter)
+     */
+    public function verify(
+        string $secret,
+        string $method,
+        string $path,
+        string $timestamp,
+        string $nonce,
+        string $body,
+        string $providedSignature
+    ): bool {
+        // 1. Check timestamp (within 5 minutes)
+        if (abs(time() - (int)$timestamp) > 300) {
+            return false;
+        }
+
+        // 2. Replay protection using Nonce in Redis
+        // Note: Redis::getInstance() would be used here
+        // If nonce exists, reject
+        
+        // 3. Calculate Signature
+        $bodyHash = hash('sha256', $body);
+        $stringToSign = strtoupper($method) . "\n" . 
+                       $path . "\n" . 
+                       $timestamp . "\n" . 
+                       $nonce . "\n" . 
+                       $bodyHash;
+
+        $calculatedSignature = hash_hmac('sha256', $stringToSign, $secret);
+
+        return hash_equals($calculatedSignature, $providedSignature);
+    }
+
+    public function sign(string $secret, string $method, string $path, string $timestamp, string $nonce, string $body): string
+    {
+        $bodyHash = hash('sha256', $body);
+        $stringToSign = strtoupper($method) . "\n" . 
+                       $path . "\n" . 
+                       $timestamp . "\n" . 
+                       $nonce . "\n" . 
+                       $bodyHash;
+
+        return hash_hmac('sha256', $stringToSign, $secret);
+    }
+}
--- a/app/Services/Security/JwtService.php
+++ b/app/Services/Security/JwtService.php
@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Security;
+
+use Firebase\JWT\JWT;
+use Firebase\JWT\Key;
+use Exception;
+
+final class JwtService
+{
+    private string $secret;
+    private int $accessExpiry;
+    private int $refreshExpiry;
+
+    public function __construct()
+    {
+        $this->secret = $_ENV['JWT_SECRET'] ?? 'change-me';
+        $this->accessExpiry = (int)($_ENV['JWT_ACCESS_EXPIRY'] ?? 900);
+        $this->refreshExpiry = (int)($_ENV['JWT_REFRESH_EXPIRY'] ?? 604800);
+    }
+
+    public function issueAccessToken(array $payload): string
+    {
+        $payload['exp'] = time() + $this->accessExpiry;
+        $payload['iat'] = time();
+        $payload['jti'] = bin2hex(random_bytes(16));
+
+        return JWT::encode($payload, $this->secret, 'HS256');
+    }
+
+    public function issueRefreshToken(string $userId): string
+    {
+        // Refresh token is a random string stored in DB (hashed)
+        return bin2hex(random_bytes(64));
+    }
+
+    public function verifyToken(string $token): array
+    {
+        try {
+            $decoded = JWT::decode($token, new Key($this->secret, 'HS256'));
+            return (array) $decoded;
+        } catch (Exception $e) {
+            throw new Exception("Invalid or expired token: " . $e->getMessage());
+        }
+    }
+}
--- a/app/Services/SubscriptionService.php
+++ b/app/Services/SubscriptionService.php
@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use App\Core\Database;
+use Exception;
+
+final class SubscriptionService
+{
+    public function checkLimit(string $tenantId, string $type): void
+    {
+        $db = Database::getInstance();
+        
+        $stmt = $db->prepare("SELECT * FROM subscriptions WHERE tenant_id = ? LIMIT 1");
+        $stmt->execute([$tenantId]);
+        $sub = $stmt->fetch();
+
+        if (!$sub) throw new Exception("لا يوجد اشتراك فعال");
+
+        if ($type === 'invoices') {
+            if ($sub['invoices_used_this_month'] >= $sub['max_invoices_per_month']) {
+                throw new Exception("لقد وصلت للحد الأقصى من الفواتير المسموح بها في خطتك الحالية");
+            }
+        }
+
+        if ($type === 'companies') {
+            $countStmt = $db->prepare("SELECT COUNT(*) as total FROM companies WHERE tenant_id = ? AND deleted_at IS NULL");
+            $countStmt->execute([$tenantId]);
+            $count = $countStmt->fetch()['total'];
+
+            if ($count >= $sub['max_companies']) {
+                throw new Exception("لقد وصلت للحد الأقصى من الشركات المسموح بها في خطتك الحالية");
+            }
+        }
+    }
+
+    public function incrementUsage(string $tenantId, string $type): void
+    {
+        if ($type === 'invoices') {
+            $db = Database::getInstance();
+            $stmt = $db->prepare("UPDATE subscriptions SET invoices_used_this_month = invoices_used_this_month + 1 WHERE tenant_id = ?");
+            $stmt->execute([$tenantId]);
+        }
+    }
+}
--- a/app/Services/TaxValidationService.php
+++ b/app/Services/TaxValidationService.php
@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+final class TaxValidationService
+{
+    /**
+     * Validate an invoice against Jordan ISTD rules (001-007)
+     */
+    public function validate(array $invoice, array $lines): array
+    {
+        $errors = [];
+
+        // Rule 001: Total integrity (grand_total = Σ line_totals)
+        $lineSum = array_sum(array_column($lines, 'line_total'));
+        if (abs($invoice['grand_total'] - $lineSum) > 0.01) {
+            $errors[] = ['code' => 'RULE_001', 'message_ar' => 'مجموع سطور الفاتورة لا يطابق المجموع الكلي'];
+        }
+
+        // Rule 002: Tax integrity (tax_amount = subtotal × tax_rate)
+        foreach ($lines as $line) {
+            $expectedTax = round($line['quantity'] * $line['unit_price'] * $line['tax_rate'], 3);
+            if (abs($line['tax_amount'] - $expectedTax) > 0.01) {
+                $errors[] = ['code' => 'RULE_002', 'message_ar' => "خطأ في حساب الضريبة للسطر {$line['line_number']}"];
+            }
+        }
+
+        // Rule 003: Invoice number required
+        if (empty($invoice['invoice_number'])) {
+            $errors[] = ['code' => 'RULE_003', 'message_ar' => 'رقم الفاتورة مطلوب'];
+        }
+
+        // Rule 004: No future dates
+        if (strtotime($invoice['invoice_date']) > time()) {
+            $errors[] = ['code' => 'RULE_004', 'message_ar' => 'تاريخ الفاتورة لا يمكن أن يكون في المستقبل'];
+        }
+
+        // Rule 005: Valid JO Tax Rates
+        $validRates = [0.16, 0.10, 0.05, 0.04, 0.02, 0.00];
+        foreach ($lines as $line) {
+            if (!in_array(round((float)$line['tax_rate'], 2), $validRates)) {
+                $errors[] = ['code' => 'RULE_005', 'message_ar' => "نسبة الضريبة ({$line['tax_rate']}) غير صالحة في الأردن"];
+            }
+        }
+
+        // Rule 006: Buyer ID for large invoices (> 10,000 JOD)
+        if ($invoice['grand_total'] > 10000 && empty($invoice['buyer_tin']) && empty($invoice['buyer_national_id'])) {
+            $errors[] = ['code' => 'RULE_006', 'message_ar' => 'يجب تزويد الرقم الضريبي أو الوطني للمشتري للفواتير التي تتجاوز 10,000 دينار'];
+        }
+
+        // Rule 007: Discount integrity
+        $expectedSubtotal = $invoice['subtotal'] - $invoice['discount_total'];
+        // This is a simplified check for Rule 007
+        if ($expectedSubtotal < 0) {
+            $errors[] = ['code' => 'RULE_007', 'message_ar' => 'إجمالي الخصم لا يمكن أن يتجاوز المجموع الفرعي'];
+        }
+
+        return [
+            'is_valid' => empty($errors),
+            'errors' => $errors
+        ];
+    }
+}
--- a/composer.json
+++ b/composer.json
@@ -0,0 +1,38 @@
+{
+    "name": "musadaq/platform",
+    "description": "Jordanian E-Invoicing Automation SaaS",
+    "type": "project",
+    "license": "proprietary",
+    "require": {
+        "php": ">=8.4",
+        "ext-pdo": "*",
+        "ext-pdo_mysql": "*",
+        "ext-openssl": "*",
+        "ext-sodium": "*",
+        "ext-curl": "*",
+        "ext-mbstring": "*",
+        "ext-json": "*",
+        "vlucas/phpdotenv": "^5.6",
+        "monolog/monolog": "^3.5",
+        "firebase/php-jwt": "^6.10",
+        "ramsey/uuid": "^4.7",
+        "nikic/fast-route": "^1.3",
+        "predis/predis": "^2.2",
+        "guzzlehttp/guzzle": "^7.9",
+        "respect/validation": "^2.3",
+        "league/flysystem": "^3.28",
+        "symfony/mailer": "^7.1"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^11.0",
+        "phpstan/phpstan": "^1.12",
+        "squizlabs/php_codesniffer": "^3.10"
+    },
+    "autoload": {
+        "psr-4": { "App\\": "app/" }
+    },
+    "config": {
+        "optimize-autoloader": true,
+        "sort-packages": true
+    }
+}
--- a/database/schema.sql
+++ b/database/schema.sql
@@ -0,0 +1,243 @@
+SET NAMES utf8mb4;
+SET CHARACTER SET utf8mb4;
+
+-- ─── Tenants ──────────────────────────────────────────────
+CREATE TABLE tenants (
+    id              CHAR(36) NOT NULL DEFAULT (UUID()),
+    name            VARCHAR(255) NOT NULL,
+    email           VARCHAR(255) NOT NULL,
+    phone           VARCHAR(20) NULL,
+    status          ENUM('active','suspended','trial') NOT NULL DEFAULT 'trial',
+    trial_ends_at   DATETIME NULL,
+    settings        JSON DEFAULT (JSON_OBJECT()),
+    created_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    deleted_at      DATETIME NULL,
+    PRIMARY KEY (id),
+    UNIQUE KEY uq_tenants_email (email)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- ─── Users ────────────────────────────────────────────────
+CREATE TABLE users (
+    id                  CHAR(36) NOT NULL DEFAULT (UUID()),
+    tenant_id           CHAR(36) NOT NULL,
+    name                VARCHAR(255) NOT NULL,
+    email               VARCHAR(255) NOT NULL,
+    password_hash       VARCHAR(255) NOT NULL,
+    role                ENUM('super_admin','admin','accountant','employee','viewer') NOT NULL,
+    assigned_company_id CHAR(36) NULL,
+    refresh_token_hash  VARCHAR(255) NULL,
+    totp_secret         VARCHAR(64) NULL,
+    totp_enabled        TINYINT(1) NOT NULL DEFAULT 0,
+    is_active           TINYINT(1) NOT NULL DEFAULT 1,
+    email_verified_at   DATETIME NULL,
+    last_login_at       DATETIME NULL,
+    last_login_ip       VARCHAR(45) NULL,
+    failed_login_count  INT NOT NULL DEFAULT 0,
+    locked_until        DATETIME NULL,
+    created_at          DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at          DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    deleted_at          DATETIME NULL,
+    PRIMARY KEY (id),
+    UNIQUE KEY uq_tenant_email (tenant_id, email),
+    CONSTRAINT fk_users_tenant FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- ─── API Keys ─────────────────────────────────────────────
+CREATE TABLE api_keys (
+    id           CHAR(36) NOT NULL DEFAULT (UUID()),
+    tenant_id    CHAR(36) NOT NULL,
+    user_id      CHAR(36) NOT NULL,
+    name         VARCHAR(100) NOT NULL,
+    public_key   VARCHAR(64) NOT NULL,
+    secret_hash  VARCHAR(255) NOT NULL,
+    permissions  JSON DEFAULT (JSON_ARRAY('invoices:read','invoices:upload')),
+    last_used_at DATETIME NULL,
+    is_active    TINYINT(1) NOT NULL DEFAULT 1,
+    expires_at   DATETIME NULL,
+    created_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (id),
+    UNIQUE KEY uq_api_public_key (public_key),
+    CONSTRAINT fk_apikeys_tenant FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
+    CONSTRAINT fk_apikeys_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- ─── Companies ────────────────────────────────────────────
+CREATE TABLE companies (
+    id                              CHAR(36) NOT NULL DEFAULT (UUID()),
+    tenant_id                       CHAR(36) NOT NULL,
+    name                            VARCHAR(255) NOT NULL,
+    name_en                         VARCHAR(255) NULL,
+    tax_identification_number       VARCHAR(20) NOT NULL,
+    commercial_registration_number  VARCHAR(50) NULL,
+    address                         TEXT NULL,
+    city                            VARCHAR(100) NULL,
+    contact_email                   VARCHAR(255) NULL,
+    contact_phone                   VARCHAR(20) NULL,
+    jofotara_client_id_encrypted    TEXT NULL,
+    jofotara_secret_key_encrypted   TEXT NULL,
+    jofotara_income_source_sequence VARCHAR(50) NULL,
+    certificate_path                VARCHAR(255) NULL,
+    certificate_password_encrypted  TEXT NULL,
+    is_jofotara_linked              TINYINT(1) NOT NULL DEFAULT 0,
+    is_active                       TINYINT(1) NOT NULL DEFAULT 1,
+    created_at                      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at                      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    deleted_at                      DATETIME NULL,
+    PRIMARY KEY (id),
+    INDEX idx_companies_tenant (tenant_id),
+    INDEX idx_companies_tin (tax_identification_number),
+    CONSTRAINT fk_companies_tenant FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- ─── Subscriptions ────────────────────────────────────────
+CREATE TABLE subscriptions (
+    id                       CHAR(36) NOT NULL DEFAULT (UUID()),
+    tenant_id                CHAR(36) NOT NULL,
+    plan                     ENUM('free','basic','office','pro','enterprise') NOT NULL DEFAULT 'basic',
+    max_companies            INT NOT NULL DEFAULT 3,
+    max_invoices_per_month   INT NOT NULL DEFAULT 50,
+    max_users                INT NOT NULL DEFAULT 2,
+    price_jod                DECIMAL(10,2) NOT NULL DEFAULT 0.00,
+    invoices_used_this_month INT NOT NULL DEFAULT 0,
+    status                   ENUM('active','past_due','cancelled','trial') NOT NULL DEFAULT 'active',
+    current_period_start     DATETIME NULL,
+    current_period_end       DATETIME NULL,
+    created_at               DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at               DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (id),
+    UNIQUE KEY uq_sub_tenant (tenant_id),
+    CONSTRAINT fk_sub_tenant FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- ─── Invoices ─────────────────────────────────────────────
+CREATE TABLE invoices (
+    id                   CHAR(36) NOT NULL DEFAULT (UUID()),
+    tenant_id            CHAR(36) NOT NULL,
+    company_id           CHAR(36) NOT NULL,
+    uploaded_by          CHAR(36) NULL,
+    invoice_number       VARCHAR(100) NULL,
+    invoice_date         DATE NULL,
+    invoice_type         ENUM('cash','credit') NOT NULL DEFAULT 'cash',
+    ubl_type_code        CHAR(3) NOT NULL DEFAULT '388',
+    payment_method_code  CHAR(3) NOT NULL DEFAULT '013',
+    supplier_tin         VARCHAR(20) NULL,
+    supplier_name        VARCHAR(255) NULL,
+    supplier_address     TEXT NULL,
+    buyer_tin            VARCHAR(20) NULL,
+    buyer_national_id    VARCHAR(20) NULL,
+    buyer_name           VARCHAR(255) NULL,
+    subtotal             DECIMAL(15,3) NOT NULL DEFAULT 0,
+    discount_total       DECIMAL(15,3) NOT NULL DEFAULT 0,
+    tax_amount           DECIMAL(15,3) NOT NULL DEFAULT 0,
+    grand_total          DECIMAL(15,3) NOT NULL DEFAULT 0,
+    currency_code        CHAR(3) NOT NULL DEFAULT 'JOD',
+    status               ENUM('uploaded','extracting','extracted','validated',
+                         'validation_failed','submitting','approved','rejected')
+                         NOT NULL DEFAULT 'uploaded',
+    original_file_path   TEXT NULL,
+    original_file_hash   VARCHAR(64) NULL,
+    invoice_category     VARCHAR(20) NOT NULL DEFAULT 'simplified',
+    validation_errors    JSON NULL,
+    qr_code              TEXT NULL,
+    jofotara_response    JSON NULL,
+    ai_provider          VARCHAR(20) NULL,
+    ai_confidence_score  DECIMAL(4,3) NULL,
+    ai_prompt_tokens     INT NOT NULL DEFAULT 0,
+    ai_completion_tokens INT NOT NULL DEFAULT 0,
+    ai_total_cost        DECIMAL(10,6) NOT NULL DEFAULT 0,
+    ai_raw_response      JSON NULL,
+    idempotency_key      VARCHAR(64) NULL,
+    created_at           DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at           DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    deleted_at           DATETIME NULL,
+    PRIMARY KEY (id),
+    UNIQUE KEY uq_idempotency (idempotency_key),
+    INDEX idx_invoices_tenant (tenant_id),
+    INDEX idx_invoices_company (company_id),
+    INDEX idx_invoices_status (status),
+    INDEX idx_invoices_date (invoice_date),
+    INDEX idx_invoices_file_hash (original_file_hash),
+    CONSTRAINT fk_inv_tenant  FOREIGN KEY (tenant_id)   REFERENCES tenants(id)   ON DELETE CASCADE,
+    CONSTRAINT fk_inv_company FOREIGN KEY (company_id)  REFERENCES companies(id) ON DELETE CASCADE,
+    CONSTRAINT fk_inv_user    FOREIGN KEY (uploaded_by) REFERENCES users(id)     ON DELETE SET NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- ─── Invoice Lines ────────────────────────────────────────
+CREATE TABLE invoice_lines (
+    id          CHAR(36) NOT NULL DEFAULT (UUID()),
+    invoice_id  CHAR(36) NOT NULL,
+    line_number INT NOT NULL,
+    description TEXT NOT NULL,
+    quantity    DECIMAL(15,3) NOT NULL,
+    unit_price  DECIMAL(15,3) NOT NULL,
+    discount    DECIMAL(15,3) NOT NULL DEFAULT 0,
+    tax_rate    DECIMAL(5,4) NOT NULL,
+    tax_amount  DECIMAL(15,3) NOT NULL DEFAULT 0,
+    line_total  DECIMAL(15,3) NOT NULL,
+    PRIMARY KEY (id),
+    INDEX idx_lines_invoice (invoice_id),
+    CONSTRAINT fk_lines_invoice FOREIGN KEY (invoice_id) REFERENCES invoices(id) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- ─── Audit Logs ───────────────────────────────────────────
+CREATE TABLE audit_logs (
+    id          CHAR(36) NOT NULL DEFAULT (UUID()),
+    tenant_id   CHAR(36) NULL,
+    user_id     CHAR(36) NULL,
+    action      VARCHAR(100) NOT NULL,
+    entity_type VARCHAR(50) NULL,
+    entity_id   CHAR(36) NULL,
+    old_data    JSON NULL,
+    new_data    JSON NULL,
+    ip_address  VARCHAR(45) NULL,
+    user_agent  TEXT NULL,
+    metadata    JSON NULL,
+    created_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (id),
+    INDEX idx_audit_tenant  (tenant_id),
+    INDEX idx_audit_action  (action),
+    INDEX idx_audit_created (created_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- ─── Risk Scores ──────────────────────────────────────────
+CREATE TABLE risk_scores (
+    id          CHAR(36) NOT NULL DEFAULT (UUID()),
+    tenant_id   CHAR(36) NOT NULL,
+    company_id  CHAR(36) NOT NULL,
+    invoice_id  CHAR(36) NULL,
+    risk_type   VARCHAR(50) NOT NULL,
+    score       TINYINT UNSIGNED NOT NULL,
+    reason      TEXT NOT NULL,
+    is_resolved TINYINT(1) NOT NULL DEFAULT 0,
+    resolved_by CHAR(36) NULL,
+    resolved_at DATETIME NULL,
+    created_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (id),
+    INDEX idx_risk_tenant     (tenant_id),
+    INDEX idx_risk_unresolved (is_resolved),
+    CONSTRAINT fk_risk_tenant   FOREIGN KEY (tenant_id)  REFERENCES tenants(id)   ON DELETE CASCADE,
+    CONSTRAINT fk_risk_company  FOREIGN KEY (company_id) REFERENCES companies(id) ON DELETE CASCADE,
+    CONSTRAINT fk_risk_invoice  FOREIGN KEY (invoice_id) REFERENCES invoices(id)  ON DELETE SET NULL,
+    CONSTRAINT fk_risk_resolver FOREIGN KEY (resolved_by) REFERENCES users(id)    ON DELETE SET NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- ─── Queue Jobs (MySQL fallback when Redis unavailable) ───
+CREATE TABLE queue_jobs (
+    id           CHAR(36) NOT NULL DEFAULT (UUID()),
+    type         VARCHAR(100) NOT NULL,
+    payload      JSON NOT NULL,
+    priority     INT NOT NULL DEFAULT 0,
+    attempts     INT NOT NULL DEFAULT 0,
+    max_attempts INT NOT NULL DEFAULT 3,
+    status       ENUM('pending','processing','completed','failed','dead')
+                 NOT NULL DEFAULT 'pending',
+    error        TEXT NULL,
+    locked_at    DATETIME NULL,
+    locked_by    VARCHAR(100) NULL,
+    scheduled_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    completed_at DATETIME NULL,
+    created_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (id),
+    INDEX idx_queue_pending (status, priority DESC, scheduled_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
--- a/public/api.php
+++ b/public/api.php
--- a/public/assets/css/app.css
+++ b/public/assets/css/app.css
@@ -0,0 +1,85 @@
+@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Sans+Arabic:wght@400;500;600;700&family=JetBrains+Mono&family=Inter:wght@400;500;600&display=swap');
+
+:root {
+    --primary: #10b981;
+    --primary-hover: #059669;
+    --primary-muted: rgba(16,185,129,0.1);
+    --danger: #ef4444;
+    --warning: #f59e0b;
+    --info: #3b82f6;
+    --success: #22c55e;
+
+    /* Dark (default) */
+    --bg-app: #0a0f1a;
+    --bg-card: rgba(15,23,42,0.8);
+    --bg-sidebar: #060b14;
+    --bg-input: rgba(15,23,42,0.6);
+    --border: rgba(51,65,85,0.6);
+    --text-primary: #f1f5f9;
+    --text-secondary: #94a3b8;
+    --text-muted: #475569;
+    --glass: rgba(15,23,42,0.6);
+    --glass-border: rgba(255,255,255,0.06);
+    --shadow-glow: 0 0 40px rgba(16,185,129,0.08);
+}
+
+[data-theme="light"] {
+    --bg-app: #f1f5f9;
+    --bg-card: #ffffff;
+    --bg-sidebar: #ffffff;
+    --bg-input: #f8fafc;
+    --border: #e2e8f0;
+    --text-primary: #0f172a;
+    --text-secondary: #475569;
+    --text-muted: #94a3b8;
+    --glass: rgba(255,255,255,0.8);
+    --glass-border: rgba(0,0,0,0.04);
+    --shadow-glow: 0 4px 24px rgba(0,0,0,0.06);
+}
+
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+    font-family: 'Inter', 'IBM Plex Sans Arabic', sans-serif;
+}
+
+body {
+    background-color: var(--bg-app);
+    color: var(--text-primary);
+    direction: rtl;
+    min-height: 100vh;
+    overflow-x: hidden;
+    transition: background-color 0.3s, color 0.3s;
+}
+
+/* Glassmorphism Utilities */
+.glass {
+    background: var(--glass);
+    backdrop-filter: blur(12px);
+    -webkit-backdrop-filter: blur(12px);
+    border: 1px solid var(--glass-border);
+}
+
+.glow {
+    box-shadow: var(--shadow-glow);
+}
+
+/* Custom Scrollbar */
+::-webkit-scrollbar {
+    width: 6px;
+}
+::-webkit-scrollbar-track {
+    background: transparent;
+}
+::-webkit-scrollbar-thumb {
+    background: var(--border);
+    border-radius: 10px;
+}
+::-webkit-scrollbar-thumb:hover {
+    background: var(--text-muted);
+}
+
+/* RTL Specifics */
+[dir="rtl"] .ml-auto { margin-right: auto; margin-left: 0; }
+[dir="rtl"] .mr-auto { margin-left: auto; margin-right: 0; }
--- a/public/assets/js/api.js
+++ b/public/assets/js/api.js
@@ -0,0 +1,76 @@
+/**
+ * مُصادَق — API Client with JWT Auth & Refresh Flow
+ */
+const API = {
+    baseUrl: '/api/v1',
+    accessToken: localStorage.getItem('access_token'),
+
+    async get(path) {
+        return this._request('GET', path);
+    },
+
+    async post(path, body) {
+        return this._request('POST', path, body);
+    },
+
+    async upload(path, formData) {
+        return this._request('POST', path, formData, true);
+    },
+
+    async _request(method, path, body = null, isFormData = false) {
+        const headers = {
+            'Accept': 'application/json',
+        };
+
+        if (this.accessToken) {
+            headers['Authorization'] = `Bearer ${this.accessToken}`;
+        }
+
+        if (!isFormData && body) {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(body);
+        }
+
+        try {
+            const response = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body
+            });
+
+            if (response.status === 401) {
+                // Try refresh token
+                const refreshed = await this.refreshToken();
+                if (refreshed) {
+                    return this._request(method, path, body, isFormData);
+                } else {
+                    window.location.href = '/login';
+                }
+            }
+
+            const data = await response.json();
+            if (!response.ok) throw data;
+            return data;
+        } catch (error) {
+            console.error('API Error:', error);
+            throw error;
+        }
+    },
+
+    async refreshToken() {
+        try {
+            const response = await fetch(`${this.baseUrl}/auth/refresh`, { method: 'POST' });
+            if (response.ok) {
+                const result = await response.json();
+                this.accessToken = result.data.access_token;
+                localStorage.setItem('access_token', this.accessToken);
+                return true;
+            }
+        } catch (e) {
+            return false;
+        }
+        return false;
+    }
+};
+
+export default API;
--- a/public/index.php
+++ b/public/index.php
@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use App\Core\Application;
+use App\Modules\Auth\AuthController;
+use App\Middleware\AuthMiddleware;
+
+$app = new Application(dirname(__DIR__));
+$router = $app->getRouter();
+
+// ══ Auth Routes ══════════════════════════════════════════════
+$router->addRoute('POST', '/api/v1/auth/login', [AuthController::class, 'login']);
+
+// ══ Company Routes ═══════════════════════════════════════════
+$router->addRoute('GET', '/api/v1/companies', [
+    'middleware' => [\App\Middleware\AuthMiddleware::class],
+    'handler' => [\App\Modules\Companies\CompanyController::class, 'list']
+]);
+$router->addRoute('POST', '/api/v1/companies', [
+    'middleware' => [\App\Middleware\AuthMiddleware::class],
+    'handler' => [\App\Modules\Companies\CompanyController::class, 'create']
+]);
+$router->addRoute('PUT', '/api/v1/companies/{id}/jofotara', [
+    'middleware' => [\App\Middleware\AuthMiddleware::class],
+    'handler' => [\App\Modules\Companies\CompanyController::class, 'updateJoFotara']
+]);
+
+// ══ Invoice Routes ═══════════════════════════════════════════
+$router->addRoute('GET', '/api/v1/invoices', [
+    'middleware' => [\App\Middleware\AuthMiddleware::class],
+    'handler' => [\App\Modules\Invoices\InvoiceController::class, 'list']
+]);
+$router->addRoute('POST', '/api/v1/invoices/upload', [
+    'middleware' => [\App\Middleware\AuthMiddleware::class],
+    'handler' => [\App\Modules\Invoices\InvoiceController::class, 'upload']
+]);
+$router->addRoute('GET', '/api/v1/invoices/{id}', [
+    'middleware' => [\App\Middleware\AuthMiddleware::class],
+    'handler' => [\App\Modules\Invoices\InvoiceController::class, 'detail']
+]);
+
+// ══ External API (HMAC) ══════════════════════════════════════
+$router->addRoute('POST', '/api/v1/external/invoices/upload', [
+    'middleware' => [\App\Middleware\HmacMiddleware::class],
+    'handler' => [\App\Modules\Invoices\InvoiceController::class, 'upload']
+]);
+
+// ══ Dashboard ════════════════════════════════════════════════
+$router->addRoute('GET', '/api/v1/dashboard', [
+    'middleware' => [\App\Middleware\AuthMiddleware::class],
+    'handler' => [\App\Modules\Dashboard\DashboardController::class, 'getStats']
+]);
+
+// ══ Health Check ═════════════════════════════════════════════
+$router->addRoute('GET', '/api/v1/health', function($request) {
+    \App\Core\Response::json([
+        'status' => 'ok',
+        'timestamp' => date('c'),
+        'php' => PHP_VERSION,
+        'db' => 'connected' // Simple check
+    ]);
+});
+
+// ══ SPA Shell ═══════════════════════════════════════════════
+$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
+if (!str_starts_with($path, '/api/v1/')) {
+    include __DIR__ . '/shell.php';
+    exit;
+}
+
+$app->run();
--- a/public/shell.php
+++ b/public/shell.php
@@ -0,0 +1,208 @@
+<!DOCTYPE html>
+<html lang="ar" dir="rtl" data-theme="dark">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>مُصادَق — أتمتة الفوترة الضريبية</title>
+    
+    <!-- Styles -->
+    <link rel="stylesheet" href="/assets/css/app.css">
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    
+    <script>
+        tailwind.config = {
+            darkMode: 'class',
+            theme: {
+                extend: {
+                    colors: {
+                        primary: '#10b981',
+                        'primary-dark': '#059669',
+                        dark: '#0a0f1a',
+                        card: '#0f172a'
+                    }
+                }
+            }
+        }
+    </script>
+</head>
+<body class="bg-dark text-slate-100 antialiased overflow-x-hidden">
+
+    <div id="app" x-data="appRouter()">
+        <!-- Navigation -->
+        <nav class="fixed top-0 w-full z-50 glass border-b border-white/10 px-6 py-4 flex items-center justify-between">
+            <div class="flex items-center gap-3">
+                <div class="w-10 h-10 bg-primary rounded-xl flex items-center justify-center shadow-lg shadow-primary/20">
+                    <span class="text-white font-bold text-xl">م</span>
+                </div>
+                <h1 class="text-xl font-bold bg-clip-text text-transparent bg-gradient-to-r from-white to-slate-400">مُصادَق</h1>
+            </div>
+
+            <div class="flex items-center gap-4">
+                <template x-if="isLoggedIn">
+                    <div class="flex items-center gap-4">
+                        <button class="p-2 hover:bg-white/5 rounded-lg transition-colors">
+                            <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 17h5l-1.405-1.405A2.032 2.032 0 0118 14.158V11a6.002 6.002 0 00-4-5.659V5a2 2 0 10-4 0v.341C7.67 6.165 6 8.388 6 11v3.159c0 .538-.214 1.055-.595 1.436L4 17h5m6 0v1a3 3 0 11-6 0v-1m6 0H9"></path></svg>
+                        </button>
+                        <div class="w-10 h-10 rounded-full bg-slate-800 border border-white/10"></div>
+                    </div>
+                </template>
+            </div>
+        </nav>
+
+        <!-- AI Floating Assistant -->
+        <div class="fixed bottom-8 right-8 z-[60]" x-data="{ open: false, query: '', answer: '', loading: false }">
+            <button @click="open = !open" class="w-16 h-16 bg-gradient-to-tr from-primary to-emerald-400 rounded-full flex items-center justify-center shadow-2xl shadow-primary/40 hover:scale-110 transition-transform">
+                <svg class="w-8 h-8 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 11a7 7 0 01-7 7m0 0a7 7 0 01-7-7m7 7v4m0 0H8m4 0h4m-4-8a3 3 0 01-3-3V5a3 3 0 116 0v6a3 3 0 01-3 3z"></path></svg>
+            </button>
+
+            <!-- Chat Popover -->
+            <div x-show="open" x-transition class="absolute bottom-20 right-0 w-80 glass rounded-3xl border-white/10 p-6 shadow-2xl">
+                <h4 class="font-bold mb-4 flex items-center gap-2">
+                    <span class="w-2 h-2 bg-primary rounded-full animate-pulse"></span>
+                    مُساعد مُصادَق الذكي
+                </h4>
+                
+                <div class="bg-white/5 rounded-xl p-3 mb-4 min-h-[60px] text-sm text-slate-300" x-text="answer || 'كيف يمكنني مساعدتك اليوم؟'"></div>
+
+                <div class="relative">
+                    <input type="text" x-model="query" @keydown.enter="loading = true; answer = 'جاري التحليل...'; const res = await API.post('/ai/query', {query}); answer = res.data.answer; loading = false; query = '';" 
+                        class="w-full bg-white/10 border border-white/10 rounded-xl px-4 py-2 text-sm focus:outline-none focus:border-primary" placeholder="اسأل عن فواتيرك...">
+                    <button class="absolute left-2 top-2 text-primary">
+                        <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 5l7 7-7 7M5 5l7 7-7 7"></path></svg>
+                    </button>
+                </div>
+            </div>
+        </div>
+
+        <!-- Main Content -->
+        <main class="pt-24 pb-12 px-6 max-w-7xl mx-auto">
+            <div id="page-content" x-html="pageHtml"></div>
+        </main>
+
+        <!-- Notifications -->
+        <div class="fixed bottom-6 left-6 z-[100] flex flex-col gap-3" id="toast-container"></div>
+    </div>
+
+    <script type="module">
+        import API from '/assets/js/api.js';
+
+        window.appRouter = () => ({
+            isLoggedIn: !!localStorage.getItem('access_token'),
+            pageHtml: '',
+            async init() {
+                this.navigate(window.location.pathname);
+                window.onpopstate = () => this.navigate(window.location.pathname);
+            },
+            async navigate(path) {
+                if (path === '/login' || !this.isLoggedIn) {
+                    this.pageHtml = await this.loadPage('login');
+                    window.history.pushState({}, '', '/login');
+                } else if (path === '/' || path === '/dashboard') {
+                    this.pageHtml = await this.loadPage('dashboard');
+                    window.history.pushState({}, '', '/dashboard');
+                }
+            },
+            initCharts() {
+                const ctx = document.getElementById('invoiceChart')?.getContext('2d');
+                if (ctx) {
+                    new Chart(ctx, {
+                        type: 'line',
+                        data: {
+                            labels: ['الأحد', 'الاثنين', 'الثلاثاء', 'الأربعاء', 'الخميس', 'الجمعة', 'السبت'],
+                            datasets: [{
+                                label: 'الفواتير المرفوعة',
+                                data: [65, 59, 80, 81, 56, 55, 40],
+                                borderColor: '#10b981',
+                                tension: 0.4,
+                                fill: true,
+                                backgroundColor: 'rgba(16, 185, 129, 0.1)'
+                            }]
+                        },
+                        options: { responsive: true, plugins: { legend: { display: false } }, scales: { y: { beginAtZero: true, grid: { color: 'rgba(255,255,255,0.05)' } }, x: { grid: { display: false } } } }
+                    });
+                }
+                const statusCtx = document.getElementById('statusChart')?.getContext('2d');
+                if (statusCtx) {
+                    new Chart(statusCtx, {
+                        type: 'doughnut',
+                        data: {
+                            labels: ['مقبول', 'مرفوض', 'معلق'],
+                            datasets: [{
+                                data: [80, 10, 10],
+                                backgroundColor: ['#10b981', '#ef4444', '#f59e0b'],
+                                borderWidth: 0
+                            }]
+                        },
+                        options: { cutout: '80%', plugins: { legend: { position: 'bottom', labels: { color: '#94a3b8' } } } }
+                    });
+                }
+            },
+            async loadPage(page) {
+                if (page === 'dashboard') {
+                    return `
+                    <div class="space-y-8" x-init="setTimeout(() => initCharts(), 100)">
+                        <div class="flex items-center justify-between">
+                            <h2 class="text-3xl font-bold">لوحة التحكم</h2>
+                            <button class="bg-primary hover:bg-primary-dark text-white px-6 py-2 rounded-xl transition-all shadow-lg shadow-primary/20 flex items-center gap-2">
+                                <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4"></path></svg>
+                                رفع فاتورة جديدة
+                            </button>
+                        </div>
+                        <div class="grid grid-cols-1 md:grid-cols-4 gap-6">
+                            <div class="glass p-6 rounded-3xl border-white/10 glow">
+                                <p class="text-slate-400 text-sm mb-1">فواتير الشهر</p>
+                                <h3 class="text-3xl font-bold">1,284</h3>
+                            </div>
+                            <div class="glass p-6 rounded-3xl border-white/10">
+                                <p class="text-slate-400 text-sm mb-1">تمت المصادقة</p>
+                                <h3 class="text-3xl font-bold">1,150</h3>
+                            </div>
+                            <div class="glass p-6 rounded-3xl border-white/10">
+                                <p class="text-slate-400 text-sm mb-1">قيد المعالجة</p>
+                                <h3 class="text-3xl font-bold">94</h3>
+                            </div>
+                            <div class="glass p-6 rounded-3xl border-white/10 border-danger/20">
+                                <p class="text-slate-400 text-sm mb-1">تنبيهات المخاطر</p>
+                                <h3 class="text-3xl font-bold text-danger">4</h3>
+                            </div>
+                        </div>
+                        <div class="grid grid-cols-1 lg:grid-cols-3 gap-8">
+                            <div class="lg:col-span-2 glass p-8 rounded-3xl border-white/10">
+                                <h4 class="font-bold mb-6">تحليل الفواتير الأسبوعي</h4>
+                                <canvas id="invoiceChart" height="250"></canvas>
+                            </div>
+                            <div class="glass p-8 rounded-3xl border-white/10">
+                                <h4 class="font-bold mb-6">توزيع الحالات</h4>
+                                <canvas id="statusChart" height="250"></canvas>
+                            </div>
+                        </div>
+                    </div>`;
+                }
+                if (page === 'login') return \`
+                    <div class="flex flex-col items-center justify-center min-h-[60vh]">
+                        <div class="w-full max-w-md p-8 glass rounded-3xl glow border-white/10">
+                            <h2 class="text-3xl font-bold mb-2 text-center">مرحباً بك مجدداً</h2>
+                            <p class="text-slate-400 text-center mb-8">قم بتسجيل الدخول للوصول إلى لوحة التحكم</p>
+                            
+                            <form class="space-y-6">
+                                <div>
+                                    <label class="block text-sm font-medium text-slate-300 mb-2">البريد الإلكتروني</label>
+                                    <input type="email" class="w-full bg-white/5 border border-white/10 rounded-xl px-4 py-3 focus:outline-none focus:border-primary transition-colors" placeholder="name@company.com">
+                                </div>
+                                <div>
+                                    <label class="block text-sm font-medium text-slate-300 mb-2">كلمة المرور</label>
+                                    <input type="password" class="w-full bg-white/5 border border-white/10 rounded-xl px-4 py-3 focus:outline-none focus:border-primary transition-colors" placeholder="••••••••">
+                                </div>
+                                <button type="submit" class="w-full bg-primary hover:bg-primary-dark text-white font-bold py-3 rounded-xl transition-all shadow-lg shadow-primary/20">دخول</button>
+                            </form>
+                        </div>
+                    </div>
+                `;
+                return '<div>الصفحة قيد الإنشاء</div>';
+            }
+        });
+    </script>
+</body>
+</html>
--- a/queue/worker.php
+++ b/queue/worker.php
@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use App\Core\Application;
+use App\Services\QueueService;
+
+// Initialize App (loads .env, etc.)
+$app = new Application(dirname(__DIR__));
+
+echo "[*] Musadaq Queue Worker Started...\n";
+
+// Signal handling for graceful shutdown
+$keepRunning = true;
+pcntl_async_signals(true);
+pcntl_signal(SIGTERM, function() use (&$keepRunning) {
+    echo "[!] SIGTERM received, shutting down gracefully...\n";
+    $keepRunning = false;
+});
+
+while ($keepRunning) {
+    $job = QueueService::pop();
+
+    if ($job) {
+        echo "[+] Processing job: {$job['type']} ({$job['id']})\n";
+        try {
+            // Process based on type
+            // match($job['type']) { ... }
+            
+            echo "[✓] Job completed: {$job['id']}\n";
+        } catch (\Throwable $e) {
+            echo "[✗] Job failed: {$job['id']} - {$e->getMessage()}\n";
+            // Handle retries or DLQ
+        }
+    } else {
+        // Sleep if no jobs
+        usleep(500000); // 0.5s
+    }
+}
+
+echo "[*] Worker stopped.\n";