TenantAtlas/docs/architecture-guidelines.md

TenantPilot Architecture Guidelines

Status: 2026-05-15 Applies to: Laravel 12.52, PHP 8.4, Filament 5.2+, Livewire 4, PostgreSQL 16.

Target Architecture

TenantPilot should remain a Laravel monolith with explicit bounded modules, not a speculative framework. The architecture target is:

• Filament owns admin UI composition only.
• Domain/application services own Intune, backup, restore, audit, evidence, and permission behavior.
• Jobs own long-running or remote Graph work.
• Policies and gates own authorization.
• Models own persistence relationships, casts, scopes, and small invariants only.
• Migrations own data integrity through foreign keys, unique constraints, partial indexes, and JSONB where queryable.

This aligns with the constitution: heavy architecture is allowed for tenant isolation, RBAC, auditability, immutable history, queue correctness, credential safety, and compliance evidence; speculative generic layers are not.

Current Architecture Signals

Strong patterns already present:

• GraphClientInterface is the required external Graph seam.
• UiEnforcement and WorkspaceUiEnforcement centralize UI authorization behavior.
• OperationRun provides observable queued operations.
• ProviderCredential uses encrypted casts for credential payloads.
• Workspace/tenant isolation migrations add non-null workspace ownership and composite constraints.
• Pest lanes and architecture/governance tests already exist.

High-risk drift:

• Large Filament classes concentrate UI, authorization, table configuration, modal logic, dispatching, notifications, and domain workflow glue in one place.
• Some resources use static can*() methods instead of dedicated policies, making authorization harder to audit globally.
• Historic JSON columns remain mixed with newer JSONB design.

Rules

• Business logic must not live directly in Filament table/header actions except trivial UI orchestration.
• Every action that creates, mutates, deletes, restores, retries, syncs, dispatches, or exports must call a service/action class or queued job.
• Every new resource-backed model needs a policy, or a documented exception in the feature spec.
• Every tenant-owned query must scope by workspace and managed environment before rendering or mutation.
• Graph calls must never happen during UI render. They must happen in services/jobs through GraphClientInterface.
• New abstractions require the constitution proportionality check unless they are security, audit, queue, or isolation-critical.
• Do not add generic provider frameworks until at least two real providers require the variation.
• Prefer extracted builders only when they reduce real review burden. Do not extract one-off schema fragments into a new layer just for style.

Refactoring Backlog

Target	Problem	Recommendation	Priority	Effort	Risk if ignored
ManagedEnvironmentOnboardingWizard	5,748 LOC workflow page	Split into step schema builders, onboarding draft mutation service, and page-only orchestration.	P1	L	High regression risk in onboarding and RBAC.
ManagedEnvironmentResource	3,785 LOC resource	Extract table columns/filters/actions and tenant-scoped domain actions.	P1	L	Difficult safe review of destructive environment actions.
RestoreRunResource	2,779 LOC resource	Extract restore action builders and write-gate composition.	P1	M	Restore safety logic becomes hard to audit.
FindingResource	2,503 LOC resource	Extract bulk exception/assignment workflows.	P2	M	Slower feature work and fragile tests.
BackupScheduleResource	repeated run/retry/bulk closures	Extract StartBackupScheduleRunAction service.	P1	M	Duplicate authorization/audit behavior can drift.

Preferred Code Patterns

Thin Filament Resource

use App\Filament\Resources\BackupScheduleResource\Actions\BackupScheduleActions;
use App\Filament\Resources\BackupScheduleResource\Schemas\BackupScheduleForm;
use App\Filament\Resources\BackupScheduleResource\Tables\BackupScheduleTable;
use App\Models\BackupSchedule;
use Filament\Resources\Resource;
use Filament\Schemas\Schema;
use Filament\Tables\Table;

final class BackupScheduleResource extends Resource
{
    protected static ?string $model = BackupSchedule::class;

    protected static bool $isGloballySearchable = false;

    public static function form(Schema $schema): Schema
    {
        return BackupScheduleForm::configure($schema);
    }

    public static function table(Table $table): Table
    {
        return BackupScheduleTable::configure($table);
    }

    public static function makeRunNowAction(): Action
    {
        return BackupScheduleActions::runNow();
    }
}

Service Action for Business Logic

namespace App\Actions\BackupSchedules;

use App\Jobs\RunBackupScheduleJob;
use App\Models\BackupSchedule;
use App\Models\User;
use App\Services\OperationRunService;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Gate;

final class StartBackupScheduleRun
{
    public function __construct(
        private readonly OperationRunService $operationRuns,
    ) {}

    public function handle(User $actor, BackupSchedule $schedule): int
    {
        Gate::forUser($actor)->authorize('run', $schedule);

        return DB::transaction(function () use ($schedule, $actor): int {
            $run = $this->operationRuns->startBackupScheduleRun($schedule, $actor);

            RunBackupScheduleJob::dispatch($schedule->getKey(), $run->getKey())
                ->onQueue('graph');

            return (int) $run->getKey();
        });
    }
}

Idempotent Job Skeleton

use App\Models\OperationRun;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\DB;

final class SyncManagedEnvironmentPoliciesJob implements ShouldQueue
{
    use Queueable;

    public int $tries = 3;

    public int $timeout = 300;

    public function __construct(
        private readonly int $operationRunId,
    ) {}

    public function handle(): void
    {
        $run = DB::transaction(function (): OperationRun {
            $run = OperationRun::query()->lockForUpdate()->findOrFail($this->operationRunId);

            if ($run->isTerminal()) {
                return $run;
            }

            $run->markRunning();

            return $run;
        });

        if ($run->isTerminal()) {
            return;
        }

        // Graph work happens here through GraphClientInterface-backed services.
    }
}

Acceptance Standard for New Features

• Spec/plan/tasks exist when code changes runtime behavior.
• Resource/page logic remains UI-focused.
• Mutations have policy authorization, transaction boundaries where needed, audit logging, and tests.
• Remote work is queued and observable.
• Tenant/workspace isolation is proven by tests.
• PostgreSQL-specific behavior is covered in the PostgreSQL lane.