Multi-Party Marketplace Invoicing &
Double-Entry Financial Rails.

<?php
namespace App\Services;

use App\Core\Database;
use PDO;

class FeeEngine
{
    /**
     * Calculate application fee for a given payment context
     */
    public static function calculate(int $amountCents, array $context = []): array
    {
        if ($amountCents <= 0) {
            return [
                'application_fee_cents'      => 0,
                'estimated_stripe_fee_cents' => 0,
                'merchant_net_cents'         => 0,
                'fee_rule_id'                => null,
                'breakdown'                  => ['type' => 'zero_amount'],
            ];
        }

        $pdo        = Database::pdo();
        $merchantId = $context['merchant_id'] ?? null;
        $productId  = $context['product_id'] ?? null;
        $profileId  = $context['platform_profile_id'] ?? null;

        // 1. Look for matching fee rule in priority order:
        //    a. Specific Merchant override -> b. Product rule -> c. Platform Profile rule
        $rule = null;
        if ($merchantId) {
            $stmt = $pdo->prepare("SELECT * FROM `fee_rules` WHERE `merchant_id` = ? AND `is_active` = 1 LIMIT 1");
            $stmt->execute([$merchantId]);
            $rule = $stmt->fetch(PDO::FETCH_ASSOC);
        }

        // 2. Default fee parameters: 1.00% + $0.30
        $feeType    = $rule['fee_type'] ?? 'percentage_plus_fixed';
        $percent    = (float)($rule['percentage'] ?? 1.00);
        $fixedCents = (int)($rule['fixed_cents'] ?? 30);

        // 3. Compute application cut
        $appFee = (int)round(($amountCents * $percent) / 100) + $fixedCents;

        // 4. Compute Stripe standard 2.9% + $0.30 estimate
        $estStripeFee = (int)round(($amountCents * 0.029) + 30);
        $merchantNet  = max(0, $amountCents - $appFee - $estStripeFee);

        return [
            'application_fee_cents'      => $appFee,
            'estimated_stripe_fee_cents' => $estStripeFee,
            'merchant_net_cents'         => $merchantNet,
            'fee_rule_id'                => $rule['fee_rule_id'] ?? null,
        ];
    }
}

<?php
namespace App\Services;

use App\Core\Database;

class FlowService
{
    /**
     * Trigger workflows listening for an event
     */
    public static function trigger(int $businessId, string $eventName, string $entityType, int $entityId, array $data = [], ?int $clientId = null)
    {
        // 1. Built-in Core Automatic State Transitions
        self::executeCoreRules($businessId, $eventName, $entityType, $entityId, $data, $clientId);

        // 2. Custom User-Configured Workflows
        $workflows = Database::fetchAll(
            "SELECT * FROM workflow_definitions WHERE business_id = ? AND trigger_event = ? AND is_active = 1",
            [$businessId, $eventName]
        );

        foreach ($workflows as $wf) {
            self::executeWorkflow($wf, $entityType, $entityId, $data, $clientId);
        }
    }

    private static function executeCoreRules(int $businessId, string $eventName, string $entityType, int $entityId, array $data, ?int $clientId)
    {
        // A. When an Invoice is Paid -> Unlock deliverables tied to this invoice!
        if ($eventName === 'invoice.paid') {
            $deliverables = Database::fetchAll(
                "SELECT * FROM deliverables WHERE business_id = ? AND invoice_id = ? AND is_unlocked = 0",
                [$businessId, $entityId]
            );

            foreach ($deliverables as $d) {
                Database::query("UPDATE deliverables SET is_unlocked = 1, unlocked_at = NOW() WHERE id = ?", [$d['id']]);

                EventService::dispatch($businessId, 'deliverable.unlocked', 'deliverable', $d['id'], 
                    "Deliverable '{$d['title']}' unlocked automatically upon invoice payment!", [
                    'invoice_id' => $entityId,
                    'deliverable_id' => $d['id']
                ], $d['client_id']);
            }
        }

        // B. When a Contract is Signed -> Auto-generate 50% deposit invoice
        if ($eventName === 'contract.signed') {
            $contract = Database::fetch("SELECT * FROM contracts WHERE id = ?", [$entityId]);
            if ($contract && $contract['deposit_cents'] > 0) {
                // Auto-generate invoice and email client with Stripe link
                $lastInv = Database::fetch("SELECT number FROM invoices WHERE business_id=? ORDER BY id DESC LIMIT 1", [$businessId]);
                $nextNum = $lastInv ? 'INV-' . (intval(substr($lastInv['number'], 4)) + 1) : 'INV-1001';
                $publicToken = bin2hex(random_bytes(32));

                Database::query("
                    INSERT INTO `invoices` (`business_id`, `client_id`, `number`, `status`, `currency`, `subtotal_cents`, `total_cents`, `date_issued`, `date_due`, `public_token`)
                    VALUES (?, ?, ?, 'sent', 'USD', ?, ?, CURDATE(), DATE_ADD(CURDATE(), INTERVAL 7 DAY), ?)
                ", [$businessId, $contract['client_id'], $nextNum, $contract['deposit_cents'], $contract['deposit_cents'], $publicToken]);
            }
        }
    }
}

<?php
// Recurring Invoice Cron Job: Run daily via system crontab
define('APP_ROOT', dirname(__DIR__));
require APP_ROOT . '/vendor/autoload.php';
$config = require APP_ROOT . '/config.php';

use App\Core\Database;

Database::init($config['db']);
$today = date('Y-m-d');

// Find active subscription profiles due for run
$profiles = Database::fetchAll(
    "SELECT * FROM recurring_profiles WHERE is_active = 1 AND next_run_date <= ?",
    [$today]
);

foreach ($profiles as $p) {
    $pdo = Database::pdo();
    $pdo->beginTransaction();

    try {
        // 1. Generate sequential invoice number
        $lastInv = Database::fetch("SELECT number FROM invoices WHERE business_id=? ORDER BY id DESC LIMIT 1", [$p['business_id']]);
        $nextNum = $lastInv ? 'INV-' . (intval(substr($lastInv['number'], 4)) + 1) : 'INV-' . rand(1000, 9999);
        $token   = bin2hex(random_bytes(16));

        // 2. Insert new invoice from recurring template
        $stmt = $pdo->prepare("
            INSERT INTO invoices (business_id, client_id, number, status, currency, subtotal_cents, total_cents, date_issued, date_due, public_token, platform_fee_cents) 
            VALUES (?, ?, ?, 'sent', 'USD', ?, ?, ?, ?, ?, ?)
        ");
        $stmt->execute([
            $p['business_id'], $p['client_id'], $nextNum, 
            $p['amount_cents'], $p['amount_cents'], 
            $today, date('Y-m-d', strtotime('+7 days')), 
            $token, $p['platform_fee_cents'] ?? 300
        ]);
        $invoiceId = $pdo->lastInsertId();

        // 3. Compute and advance next run date
        $nextRun = date('Y-m-d', strtotime('+1 month', strtotime($today)));
        if ($p['frequency'] === 'weekly') {
            $nextRun = date('Y-m-d', strtotime('+1 week', strtotime($today)));
        }

        $pdo->prepare("UPDATE recurring_profiles SET next_run_date = ?, last_run_date = ? WHERE id = ?")
            ->execute([$nextRun, $today, $p['id']]);

        $pdo->commit();
    } catch (Exception $e) {
        $pdo->rollBack();
        error_log("Failed recurring run for profile {$p['id']}: " . $e->getMessage());
    }
}