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

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

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

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

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

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

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

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

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

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

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

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

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')
+        ];
+    }
+}

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

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

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

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

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

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

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

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

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

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

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

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

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

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"]);
+    }
+}

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

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

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

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

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

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

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