Clean Architecture in Modern PHP & React: Building Maintainable SaaS

Fast-growing SaaS products rarely fail because of missing features; they fail because of architectural rot. In early stages, mixing database queries inside HTTP controllers or coupling React UI components directly to backend schema shapes delivers speed. But as teams scale past 15 engineers and hundreds of thousands of users, technical debt turns every minor sprint into a high-friction bug hunt.

In this architectural guide, we demonstrate how combining Uncle Bob’s Clean Architecture, Domain-Driven Design (DDD), and SOLID principles in modern PHP 8.3+ alongside typed React with custom hooks creates enterprise SaaS systems that are robust, easily testable, and painless to maintain.

1. The Core Layers of Clean SaaS Architecture

Clean Architecture enforces a strict inward dependency rule. External details (PostgreSQL, Redis, HTTP Controllers, Stripe SDKs) depend on inner business policies—never the other way around:

2. Modern PHP: Domain Entity & Use Case with Interface Inversion

Here is a real-world example applying the Dependency Inversion Principle (DIP) and Single Responsibility Principle (SRP) in modern PHP:

<?php

declare(strict_types=1);

namespace App\Subscription\Application;

use App\Subscription\Domain\Model\TenantId;
use App\Subscription\Domain\Model\PlanTier;
use App\Subscription\Domain\Repository\TenantRepositoryInterface;
use App\Subscription\Domain\Service\PaymentGatewayInterface;
use App\Shared\Domain\EventBusInterface;

final readonly class UpgradePlanUseCase
{
    public function __construct(
        private TenantRepositoryInterface $tenantRepository,
        private PaymentGatewayInterface $paymentGateway,
        private EventBusInterface $eventBus
    ) {}

    public function execute(TenantId $tenantId, PlanTier $newPlan): void
    {
        $tenant = $this->tenantRepository->findById($tenantId);
        
        // Execute payment through decoupled interface
        $paymentRef = $this->paymentGateway->chargePlanUpgrade($tenant, $newPlan);
        
        // Domain model enforces business invariants internally
        $tenant->upgradeSubscription($newPlan, $paymentRef);
        
        $this->tenantRepository->save($tenant);
        $this->eventBus->publishAll($tenant->releaseDomainEvents());
    }
}

"Frameworks come and go; business rules outlive libraries. If upgrading your framework breaks your domain logic, your architecture is tightly coupled."

3. React: Decoupling State Machines from UI View Components

On the frontend, Clean Architecture principles apply equally. Avoid placing fetch() or complex business state directly inside render components. Use custom headless hooks and view-model adapters:

import { useState, useCallback } from 'react';
import { subscriptionApi } from '../api/subscriptionApiClient';
import type { PlanTier } from '../types';

export const useSubscriptionUpgrade = (tenantId: string) => {
    const [isLoading, setIsLoading] = useState(false);
    const [error, setError] = useState<string | null>(null);

    const upgrade = useCallback(async (tier: PlanTier) => {
        setIsLoading(true);
        setError(null);
        try {
            await subscriptionApi.upgradePlan({ tenantId, tier });
            window.location.href = '/dashboard?upgrade=success';
        } catch (err: any) {
            setError(err?.message ?? 'Upgrade transaction failed.');
        } finally {
            setIsLoading(false);
        }
    }, [tenantId]);

    return { upgrade, isLoading, error };
};

4. Architecture Comparison Matrix

Key Architectural Takeaways

• Enforce Inversion: Domain models should only import domain namespaces—never ORMs or frameworks.
• Use Domain Events: Decouple side effects (emails, webhooks, audit logs) by dispatching asynchronous events.
• Isolate UI in React: Keep presentation components dumb; move data fetching and validation logic into dedicated custom hooks.