TenantAtlas/specs/046-inventory-sync-button/research.md

Phase 0 Research: Inventory Sync Button (046)

Date: 2026-01-09

Findings

Existing patterns to reuse

DB-backed notifications

• Filament DB notifications are already used in multiple places.
• Example: Policy Sync action calls Filament\Notifications\Notification::make()->sendToDatabase(auth()->user())->send().

Bottom-right progress widget

• The bottom-right progress widget is implemented by App\Livewire\BulkOperationProgress and renders resources/views/livewire/bulk-operation-progress.blade.php.
• It polls BulkOperationRun filtered by tenant_id = Tenant::current()->id and user_id = auth()->id().
• It is injected globally into Filament via a render hook in App\Providers\Filament\AdminPanelProvider.

Inventory Sync run records

• Inventory sync runs are already persisted in inventory_sync_runs with counts and status.
• Current InventorySyncService::syncNow(...) runs inline and uses locks/concurrency to create/update InventorySyncRun.

Authorization

• The app already uses tenant-role based authorization for sync operations (e.g. User::canSyncTenant($tenant) in TenantResource).

Inventory selection payload

• Inventory Sync requires a selection payload with shape: {policy_types: list<string>, categories: list<string>, include_foundations: bool, include_dependencies: bool}.
• There is no existing UI picker for inventory selection.

Decisions

Decision: Start Inventory Sync as a queued job

• Chosen: Dispatch an Inventory Sync job from the UI action.
• Rationale: Aligns with existing background operation UX and avoids blocking Livewire requests.
• Alternatives considered:
  • Run inline (current syncNow) — rejected due to UX (slow request) and mismatch with existing “progress widget” expectations.

Decision: Use DB notifications + progress widget UX consistent with Policy/Bulk operations

• Chosen: Create a BulkOperationRun (resource inventory, action sync) so the existing bottom-right widget shows progress; also send DB notifications at start and completion/failure.
• Rationale: Matches established UX language and avoids inventing new UI surfaces.
• Alternatives considered:
  • Only show toast notifications — rejected; user explicitly requires DB notification panel + progress widget.

Decision: Authorize via tenant role sync permission

• Chosen: Gate the UI action using auth()->user()->canSyncTenant(Tenant::current()).
• Rationale: Aligns with existing “sync” authorization patterns already used for tenant/policy operations.
• Alternatives considered:
  • Introduce new permission strings/roles — rejected for MVP; adds RBAC surface area.

Decision: Default selection = “full inventory”

• Chosen: Dispatch inventory sync with policy types set to PolicyTypeResolver::supportedPolicyTypes(), empty categories, and include_foundations=true, include_dependencies=true.
• Rationale: Simplest interpretation of “Run Inventory Sync” without inventing a new picker UX.
• Alternatives considered:
  • Reuse backup policy picker UI — rejected; different domain (backup selection), more UX than requested.

Decision: Attribute initiator on run record and audit trail

• Chosen: Store initiator identity on InventorySyncRun and also emit an audit record.
• Rationale: Improves traceability and aligns with constitution principle “Operations / Run Observability Standard”.
• Alternatives considered:
  • Audit log only — rejected (you chose C).

Open Questions (for Phase 1 design)

• None remaining for planning; implementation will add a dedicated queued job.