Clotho 4c2cd71157 docs: add Phase 0 environment assessment and test baseline (#1 )

## Summary

Complete Phase 0 assessment of core-commerce package with comprehensive
architecture review, security analysis, and test baseline documentation.

## Key Findings

- **Architecture:** Mature Laravel package with event-driven design
- **Services:** 16 singleton services, dual payment gateway support (Stripe + BTCPay)
- **Security:** Recent P1/P2 security enhancements completed (webhook idempotency,
  per-IP rate limiting, fraud detection)
- **Testing:** Pest v3 framework with 14 test files (cannot execute due to
  private dependency on host-uk/core)
- **Codebase:** 185 PHP files, 32 models, 27 services (~8,434 LOC), strict typing

## Status

⚠️ Cannot execute tests/lint/analysis without access to private `host-uk/core` dependency.
Created FINDINGS.md with detailed assessment and recommendations.

Co-Authored-By: Clotho <clotho@lthn.ai>

2026-02-20 03:20:22 +00:00

18 KiB

Raw Blame History

Phase 0: Environment Assessment + Test Baseline

Date: 2026-02-20 Agent: Clotho (darbs-claude) Issue: #1 - Phase 0: environment assessment + test baseline

Executive Summary

This is a mature, well-architected Laravel commerce package (host-uk/core-commerce) providing comprehensive billing, subscriptions, and payment processing capabilities. The codebase demonstrates strong engineering practices with event-driven architecture, comprehensive domain coverage, and UK English conventions.

Status: ⚠️ Cannot execute tests due to private dependency (host-uk/core) Recommendation: Proceed with code review and architectural analysis only

1. Environment Assessment

1.1 Dependency Analysis

Issue: The package depends on host-uk/core which is not publicly available:

"require": {
    "php": "^8.2",
    "host-uk/core": "dev-main"
}

Impact:

❌ Cannot run composer install
❌ Cannot execute tests (vendor/bin/pest)
❌ Cannot run linter (vendor/bin/pint)
❌ Cannot run static analysis (vendor/bin/phpstan)

Mitigation: This is expected for a private package. Testing would require:

Access to private Composer repository hosting host-uk/core
Authentication credentials configured
Full Laravel application context

1.2 Technology Stack

Component	Technology	Version
PHP	Required	^8.2
Framework	Laravel	12.x (via orchestra/testbench ^9.0\|^10.0)
Testing	Pest	^3.0
Code Style	Laravel Pint	^1.18
Package Type	Laravel Package	Service Provider based

1.3 Project Structure

📦 core-commerce (185 PHP files)
├── 📂 Boot.php                    # Service Provider + Event Registration
├── 📂 Services/ (27 files)        # Business Logic Layer (~8,434 LOC)
│   ├── CommerceService            # Order orchestration
│   ├── SubscriptionService        # Subscription lifecycle
│   ├── InvoiceService             # Invoice generation
│   ├── TaxService                 # Jurisdiction-based tax calculation
│   ├── CouponService              # Discount validation
│   ├── CurrencyService            # Multi-currency + exchange rates
│   ├── DunningService             # Failed payment retry logic
│   ├── UsageBillingService        # Metered billing
│   ├── ReferralService            # Affiliate tracking
│   ├── FraudService               # Fraud detection (Stripe Radar)
│   ├── PaymentMethodService       # Stored payment methods
│   ├── CheckoutRateLimiter        # 5 attempts per 15min
│   ├── WebhookRateLimiter         # Per-IP rate limiting
│   └── PaymentGateway/            # Pluggable gateway implementations
│       ├── PaymentGatewayContract # Gateway interface
│       ├── StripeGateway          # Stripe integration (23,326 LOC)
│       └── BTCPayGateway          # BTCPay integration (23,309 LOC)
│
├── 📂 Models/ (32 files)          # Eloquent Models
│   ├── Order, OrderItem           # Order management
│   ├── Subscription               # Subscription lifecycle
│   ├── Invoice, InvoiceItem       # Invoicing
│   ├── Payment, Refund            # Payment transactions
│   ├── Coupon, CouponUsage        # Discounts
│   ├── Product, ProductPrice      # Product catalogue
│   ├── ExchangeRate               # Currency conversion
│   ├── SubscriptionUsage          # Usage-based billing
│   ├── Referral, ReferralCommission # Affiliate system
│   ├── PaymentMethod              # Stored payment methods
│   └── WebhookEvent               # Webhook deduplication
│
├── 📂 Migrations/ (7 files)       # Database Schema
├── 📂 Events/ (5 files)           # Domain Events
│   ├── OrderPaid
│   ├── SubscriptionCreated
│   ├── SubscriptionRenewed
│   ├── SubscriptionUpdated
│   └── SubscriptionCancelled
│
├── 📂 Listeners/ (3 files)        # Event Subscribers
├── 📂 Controllers/                # HTTP Controllers
│   ├── Webhooks/
│   │   ├── StripeWebhookController
│   │   └── BTCPayWebhookController
│   ├── Api/CommerceController
│   └── InvoiceController
│
├── 📂 View/Modal/                 # Livewire Components
│   ├── Admin/                     # Admin panels (9 components)
│   └── Web/                       # User-facing (11 components)
│
├── 📂 Console/ (7 commands)       # Artisan Commands
├── 📂 Middleware/ (2 files)       # HTTP Middleware
├── 📂 Notifications/ (8 files)    # Email/SMS notifications
├── 📂 Mcp/Tools/ (4 files)        # Model Context Protocol tools
└── 📂 tests/ (14 files)           # Pest test suite
    ├── Feature/ (9 tests)
    └── Unit/ (2 tests)

2. Architecture Review

2.1 Design Patterns

✅ Event-Driven Lazy Loading:

The package uses Core Framework's event system for lazy module loading:

public static array $listens = [
    AdminPanelBooting::class => 'onAdminPanel',
    ApiRoutesRegistering::class => 'onApiRoutes',
    WebRoutesRegistering::class => 'onWebRoutes',
    ConsoleBooting::class => 'onConsole',
];

Benefits:

Modules only load when needed
No performance penalty if admin panel not accessed
Clean separation of concerns

✅ Service Layer Pattern:

All business logic isolated in singleton services registered in Boot::register():

$this->app->singleton(\Core\Mod\Commerce\Services\CommerceService::class);
$this->app->singleton(\Core\Mod\Commerce\Services\SubscriptionService::class);
// ... 16 more services

Benefits:

Testable (constructor injection)
Single Responsibility Principle
Clear dependencies

✅ Strategy Pattern (Payment Gateways):

Pluggable payment gateway implementations via PaymentGatewayContract:

$this->app->bind(PaymentGatewayContract::class, function ($app) {
    $defaultGateway = config('commerce.gateways.btcpay.enabled')
        ? 'btcpay'
        : 'stripe';
    return $app->make("commerce.gateway.{$defaultGateway}");
});

✅ Domain Events for Decoupling:

Events trigger listeners without tight coupling:

Event::listen(\Core\Mod\Commerce\Events\OrderPaid::class,
    Listeners\CreateReferralCommission::class);
Event::listen(\Core\Mod\Commerce\Events\SubscriptionRenewed::class,
    Listeners\ResetUsageOnRenewal::class);

2.2 Key Architectural Strengths

Strict Typing: All files use declare(strict_types=1);
UK English Conventions: Consistent use of "colour", "organisation", etc.
PSR-12 Compliance: Configured via Laravel Pint
Data Transfer Objects: DTOs in Data/ directory (SkuOption, FraudAssessment, etc.)
Comprehensive Logging: Webhook handlers include detailed logging
Database Transactions: Critical operations wrapped in DB transactions
Idempotency: Order creation supports idempotency keys
Multi-Currency: Full support with exchange rate providers (ECB, Stripe, Fixed)

2.3 Security Features (Recently Added)

Recent Security Enhancements (Jan 2026):

Webhook Idempotency ✅ (P1)
- Duplicate webhook detection via webhook_events table
- Unique constraint on (gateway, event_id)
Per-IP Rate Limiting ✅ (P2-075)
- WebhookRateLimiter service
- 60 req/min for unknown IPs, 300 req/min for trusted gateway IPs
- CIDR range support
Fraud Detection ✅ (P1-041)
- FraudService integration
- Velocity checks (IP/email limits, failed payment tracking)
- Geo-anomaly detection
- Stripe Radar integration
Input Sanitisation ✅ (P1-042)
- Coupon code sanitisation (3-50 chars, alphanumeric only)
- Length limits and character validation
Payment Verification ✅
- Amount verification for BTCPay settlements
- Currency mismatch detection

3. Test Suite Analysis

3.1 Test Framework: Pest v3

The project uses Pest (not PHPUnit) with Pest's function-based syntax:

describe('Order Creation', function () {
    it('creates an order for a package purchase', function () {
        $order = $this->service->createOrder(
            $this->workspace,
            $this->package,
            'monthly'
        );
        expect($order)->toBeInstanceOf(Order::class)
            ->and($order->status)->toBe('pending');
    });
});

3.2 Test Coverage

Test File	Focus Area	Test Count
`CheckoutFlowTest.php`	End-to-end checkout	~15 scenarios
`SubscriptionServiceTest.php`	Subscription lifecycle	Unknown
`TaxServiceTest.php`	Tax calculation	Unknown
`CouponServiceTest.php`	Discount logic	Unknown
`DunningServiceTest.php`	Failed payment retry	Unknown
`RefundServiceTest.php`	Refund processing	Unknown
`WebhookTest.php`	Webhook handlers (BTCPay focus)	Unknown
`CompoundSkuTest.php`	SKU parsing	Unknown

Note: Cannot run tests to get exact count due to missing dependencies.

3.3 Test Dependencies

Tests require:

Core\Tenant\Models\Package (from host-uk/core)
Core\Tenant\Models\User (from host-uk/core)
Core\Tenant\Models\Workspace (from host-uk/core)
Core\Tenant\Services\EntitlementService (from host-uk/core)

3.4 Testing Gaps (Per TODO.md)

P2 - High Priority:

❌ Integration tests for Stripe webhook handlers (only BTCPay covered)
❌ Concurrent subscription operation tests (race conditions)
❌ Multi-currency order flow tests
❌ Referral commission maturation edge cases (refund during maturation)

P3 - Medium Priority:

❌ Payment method management UI tests (Livewire components)

4. Code Quality Assessment

4.1 Static Analysis Tools

Configured but not executable:

Laravel Pint (vendor/bin/pint)
- PSR-12 compliance
- composer run lint script defined
Pest (vendor/bin/pest)
- composer run test script defined
- Uses Pest v3 syntax
PHPStan (mentioned in issue, no config found)
- vendor/bin/phpstan analyse --memory-limit=512M
- No phpstan.neon or phpstan.neon.dist found in repository

4.2 Code Quality Observations

Strengths:

✅ Consistent declare(strict_types=1); usage
✅ Type hints on all method parameters and returns
✅ PSR-12 formatting (based on Pint config)
✅ UK English spellings throughout
✅ Comprehensive PHPDoc blocks
✅ Clear separation of concerns

Areas for Improvement (Per TODO.md P3-P4):

Type Consistency (P3):
- Mix of float, decimal:2 casts, and int cents for money handling
- Recommendation: Consider brick/money package
DTO Consistency (P3):
- TaxResult embedded in TaxService.php instead of Data/TaxResult.php
- PaymentGatewayContract::refund() returns array instead of RefundResult DTO
State Machine (P3):
- Order status transitions scattered across models and services
- Recommendation: Create OrderStateMachine class
Livewire Typed Properties (P3):
- Some Livewire components use public $variable without type hints

5. Database Schema

5.1 Migrations

7 Migration Files:

0001_01_01_000001_create_commerce_tables.php - Core tables
0001_01_01_000002_create_credit_notes_table.php - Credit notes
0001_01_01_000003_create_payment_methods_table.php - Stored payment methods
2026_01_26_000000_create_usage_billing_tables.php - Usage-based billing
2026_01_26_000001_create_exchange_rates_table.php - Currency exchange
2026_01_26_000001_create_referral_tables.php - Affiliate system
2026_01_29_000001_create_webhook_events_table.php - Webhook deduplication

5.2 Index Optimisation Opportunities (Per TODO.md P3)

Missing Indexes:

orders.idempotency_key (unique index recommended)
invoices.workspace_id, status (composite index for dunning queries)

6. Stripe Integration Assessment

6.1 StripeGateway Implementation

File: Services/PaymentGateway/StripeGateway.php (23,326 LOC)

Capabilities:

✅ Customer management (create, update)
✅ Checkout sessions (Stripe Checkout)
✅ Payment methods (setup sessions, attach/detach)
✅ Subscriptions (create, update, cancel, resume, pause)
✅ One-time charges
✅ Refunds
✅ Invoice retrieval
✅ Webhook verification (signature validation)
✅ Tax rate creation
✅ Customer portal URLs
✅ Stripe Radar fraud detection

Webhook Events Handled:

Based on codebase references:

charge.succeeded - Fraud assessment
payment_intent.succeeded - Fraud assessment
Standard subscription events (likely)

6.2 BTCPayGateway Implementation

File: Services/PaymentGateway/BTCPayGateway.php (23,309 LOC)

Capabilities:

✅ Invoice creation (crypto payments)
✅ Invoice status tracking
✅ Webhook verification (HMAC signature)
✅ Payment settlement handling
⚠️ Limited subscription support (BTCPay is invoice-based)

Webhook Events:

InvoiceSettled - Payment completed
InvoiceExpired - Payment window expired
InvoicePartiallyPaid - Partial payment received (mentioned in TODO as unhandled)

6.3 Stripe vs BTCPay Priority

Default Gateway Logic:

public function getDefaultGateway(): string
{
    // BTCPay is primary, Stripe is fallback
    if (config('commerce.gateways.btcpay.enabled')) {
        return 'btcpay';
    }
    return 'stripe';
}

Interpretation:

BTCPay preferred for cryptocurrency acceptance
Stripe used for traditional card payments
Both can be enabled simultaneously

7. Outstanding TODO Items

7.1 Critical (P1) - Remaining

Input Validation:

Validate billing address components - Order::create() accepts billing_address array without validating structure
Add CSRF protection to API billing endpoints - Routes use auth middleware but not verified or CSRF tokens

7.2 High Priority (P2)

Data Integrity:

Add pessimistic locking to ReferralService::requestPayout()
Add optimistic locking to Subscription model (version column)
Handle partial payments in BTCPay (InvoicePartiallyPaid webhook)

Missing Features:

Implement provisioning API endpoints (commented out in api.php)
Add subscription upgrade/downgrade via API (proration handling)
Add payment method management UI tests
Implement credit note application to future invoices

Error Handling:

Add retry mechanism for failed invoice PDF generation (queue job)
Improve error messages for checkout failures (gateway error mapping)
Add alerting for repeated payment failures (Slack/email after N failures)

Testing Gaps:

Integration tests for Stripe webhook handlers
Tests for concurrent subscription operations
Tests for multi-currency order flow
Tests for referral commission maturation edge cases

7.3 Detailed Breakdown by Phase

See TODO.md for complete breakdown across P1-P6 categories.

8. Recommendations

8.1 Immediate Actions (Phase 1)

Set up private Composer repository access
- Configure authentication for host-uk/core dependency
- Unblock testing, linting, and static analysis
PHPStan Configuration
- Create phpstan.neon if it doesn't exist
- Set level 5-8 for strict analysis
Address P1 Security Items
- Billing address validation
- CSRF protection for API endpoints

8.2 Short-term Improvements (Phase 2)

Complete Test Coverage
- Add Stripe webhook tests
- Add concurrent operation tests
- Add multi-currency flow tests
Add Missing Indexes
- orders.idempotency_key (unique)
- invoices.workspace_id, status (composite)
Implement Missing Features
- Provisioning API endpoints
- BTCPay partial payment handling

8.3 Long-term Enhancements (Phase 3+)

Money Handling Standardisation
- Migrate to brick/money package
- Eliminate float usage for currency amounts
State Machine Implementation
- Extract order status transitions to OrderStateMachine
- Same for SubscriptionStateMachine
Observability
- Add Prometheus metrics for payment success/failure rates
- Add distributed tracing for checkout flow
- Add structured logging with correlation IDs

9. Conclusion

9.1 Overall Assessment

Grade: A- (Excellent, with minor gaps)