README

Framework-Agnostic Order-to-Cash Workflow Coordination

Overview

Nexus\SalesOperations orchestrates the complete Order-to-Cash (O2C) cycle, coordinating workflows across Sales, Receivable, Inventory, and Warehouse domains. Designed with Progressive Disclosure to serve businesses from small startups to large enterprises.

Progressive Disclosure Philosophy

This orchestrator scales with your business needs:

Tier 1: Essential (Small Business)

• Quote → Order conversion
• Simple order confirmation
• Basic fulfillment tracking
• Direct invoicing

Tier 2: Growth (Mid-Market)

• Credit limit enforcement
• Multi-warehouse allocation
• Partial shipment handling
• Commission calculations

Tier 3: Enterprise (Large Corporation)

• Multi-currency with rate locking
• Revenue recognition (IFRS 15/ASC 606)
• Advanced pricing rules
• Complete audit trail
• Approval workflows

Architecture

src/
├── Contracts/           # Orchestrator interfaces (dependency inversion)
│   ├── QuotationInterface.php
│   ├── SalesOrderInterface.php
│   ├── CustomerInterface.php
│   ├── InvoiceInterface.php
│   ├── CreditManagerInterface.php
│   └── ...
├── Coordinators/        # Stateless traffic cops
│   ├── QuotationToOrderCoordinator.php
│   ├── OrderFulfillmentCoordinator.php
│   ├── CreditCheckCoordinator.php
│   └── ...
├── Workflows/           # Stateful long-running processes
│   ├── OrderToCashWorkflow.php
│   ├── SplitShipmentWorkflow.php
│   └── ...
├── Services/            # Pure business calculations
│   ├── MarginCalculator.php
│   ├── CommissionCalculator.php
│   ├── RevenueRecognitionService.php
│   └── ...
├── Listeners/           # Event reactors
│   ├── OnOrderConfirmedReserveStock.php
│   ├── OnShipmentCreatedGenerateInvoice.php
│   └── ...
├── Rules/               # Validation constraints
│   ├── CreditLimitRule.php
│   ├── StockAvailabilityRule.php
│   └── ...
├── DataProviders/       # Cross-package data aggregation
│   ├── OrderContextProvider.php
│   └── ...
├── DTOs/                # Strict data contracts
│   ├── CreateOrderRequest.php
│   ├── FulfillmentRequest.php
│   └── ...
├── Enums/               # Type-safe enumerations
│   ├── OrderStatus.php
│   ├── FulfillmentStatus.php
│   └── ...
└── Exceptions/          # Domain-specific errors
    ├── CreditLimitExceededException.php
    ├── InsufficientStockException.php
    └── ...

Core Components

Coordinators

1. QuotationToOrderCoordinator

Converts quotations to confirmed sales orders.

use Nexus\SalesOperations\Coordinators\QuotationToOrderCoordinator;
use Nexus\SalesOperations\DTOs\ConvertQuotationRequest;

$coordinator = $container->get(QuotationToOrderCoordinator::class);

$result = $coordinator->convertToOrder(new ConvertQuotationRequest(
    quotationId: 'quote-001',
    confirmedBy: 'user-123',
    notes: 'Customer confirmed via email',
    overrides: [
        'payment_terms' => 'NET_30',
    ]
));

if ($result->success) {
    echo "Order created: {$result->orderId}";
}

2. OrderFulfillmentCoordinator

Coordinates order fulfillment across inventory and warehouse.

use Nexus\SalesOperations\Coordinators\OrderFulfillmentCoordinator;
use Nexus\SalesOperations\DTOs\FulfillmentRequest;

$coordinator = $container->get(OrderFulfillmentCoordinator::class);

$result = $coordinator->fulfill(new FulfillmentRequest(
    orderId: 'order-001',
    warehouseId: 'wh-001',
    lines: [
        ['product_id' => 'prod-001', 'quantity' => 10],
        ['product_id' => 'prod-002', 'quantity' => 5],
    ],
    shippedBy: 'user-123',
    trackingNumber: 'TRK-123456',
));

echo "Shipment created: {$result->shipmentId}";
echo "Invoice generated: {$result->invoiceId}";

3. CreditCheckCoordinator

Enforces credit limits before order confirmation.

use Nexus\SalesOperations\Coordinators\CreditCheckCoordinator;

$coordinator = $container->get(CreditCheckCoordinator::class);

$check = $coordinator->checkCredit(
    customerId: 'customer-001',
    orderAmount: 5000.00,
    currency: 'USD'
);

if ($check->approved) {
    echo "Credit approved. Available: {$check->availableCredit}";
} else {
    echo "Credit denied: {$check->reason}";
    // Place order on credit hold
}

Workflows

OrderToCashWorkflow

Complete O2C lifecycle management.

use Nexus\SalesOperations\Workflows\OrderToCashWorkflow;
use Nexus\SalesOperations\DTOs\OrderToCashRequest;

$workflow = $container->get(OrderToCashWorkflow::class);

$result = $workflow->execute(new OrderToCashRequest(
    tenantId: 'tenant-001',
    customerId: 'customer-001',
    lines: [
        ['product_id' => 'prod-001', 'quantity' => 100, 'unit_price' => 50.00],
    ],
    paymentTerms: 'NET_30',
    requestedBy: 'user-001',
));

// Workflow handles:
// 1. Credit check
// 2. Stock reservation
// 3. Order confirmation
// 4. Fulfillment
// 5. Invoicing
// 6. Payment tracking
// 7. Commission calculation

Services

MarginCalculator

use Nexus\SalesOperations\Services\MarginCalculator;

$calculator = $container->get(MarginCalculator::class);

$analysis = $calculator->analyze(
    orderLines: $order->getLines(),
    costBasis: 'weighted_average',  // or 'fifo', 'standard'
    includeLandedCost: true,
);

echo "Gross Margin: {$analysis->grossMarginPercent}%";
echo "Net Margin: {$analysis->netMarginPercent}%";
echo "Total Profit: {$analysis->totalProfit}";

CommissionCalculator

use Nexus\SalesOperations\Services\CommissionCalculator;

$calculator = $container->get(CommissionCalculator::class);

$commission = $calculator->calculate(
    orderId: 'order-001',
    salespersonId: 'sales-001',
    basis: 'gross_profit',  // or 'revenue', 'quantity'
);

echo "Commission earned: {$commission->amount}";
echo "Rate applied: {$commission->rate}%";

Rules

CreditLimitRule

use Nexus\SalesOperations\Rules\CreditLimitRule;

$rule = $container->get(CreditLimitRule::class);

$result = $rule->validate(new CreditCheckRequest(
    customerId: 'customer-001',
    orderAmount: 10000.00,
));

if (!$result->passed) {
    throw new CreditLimitExceededException($result->message);
}

Event-Driven Integration

Events Published

Event Listeners

Progressive Disclosure Matrix

Contracts (Interfaces)

All interfaces are defined in Contracts/ following the Orchestrator Interface Segregation Pattern. Adapters implement these interfaces using atomic packages.

Core Interfaces

interface CustomerInterface
{
    public function getId(): string;
    public function getName(): string;
    public function getCreditLimit(): float;
    public function getPaymentTerms(): string;
    public function getCurrency(): string;
}

interface QuotationInterface
{
    public function getId(): string;
    public function getCustomerId(): string;
    public function getStatus(): string;
    public function getTotal(): float;
    public function getLines(): array;
    public function getValidUntil(): \DateTimeImmutable;
}

interface SalesOrderInterface
{
    public function getId(): string;
    public function getOrderNumber(): string;
    public function getCustomerId(): string;
    public function getStatus(): string;
    public function getTotal(): float;
    public function getLines(): array;
    public function getPaymentTerms(): string;
}

interface InvoiceInterface
{
    public function getId(): string;
    public function getInvoiceNumber(): string;
    public function getOrderId(): string;
    public function getTotal(): float;
    public function getBalanceDue(): float;
    public function getStatus(): string;
}

interface CreditManagerInterface
{
    public function checkCreditLimit(string $customerId, float $amount): bool;
    public function getAvailableCredit(string $customerId): float;
    public function placeOnHold(string $orderId, string $reason): void;
    public function releaseHold(string $orderId): void;
}

interface StockReservationInterface
{
    public function reserve(string $orderId, string $productId, float $quantity): bool;
    public function release(string $orderId): void;
    public function getReservedQuantity(string $orderId, string $productId): float;
}

interface ShipmentInterface
{
    public function getId(): string;
    public function getOrderId(): string;
    public function getStatus(): string;
    public function getTrackingNumber(): ?string;
    public function getLines(): array;
}

Installation

composer require azaharizaman/nexus-sales-operations

Required Dependencies (via Adapters)

Testing

# Run all tests
vendor/bin/phpunit orchestrators/SalesOperations/tests

# Run with coverage
vendor/bin/phpunit --coverage-html coverage orchestrators/SalesOperations/tests

License

MIT License - See LICENSE file.

Documentation

• ARCHITECTURE.md - System architecture
• ORCHESTRATOR_INTERFACE_SEGREGATION.md - Interface pattern
• CODING_GUIDELINES.md - Coding standards