Research — Unified Badge System (Single Source of Truth) v1

Goal

Standardize status/health and severity/risk badge semantics suite-wide so operators can reliably scan the admin UI without misread signals (for example, “success” never appearing as warning).

V1 scope explicitly excludes tag/category chips (policy type/platform/environment).

Existing Code & Patterns (to reuse)

Filament badge surfaces (current)

Tables already use TextColumn::badge() in many places.
Ad-hoc status and severity mapping exists in several hotspots, for example:
- /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Monitoring/Operations.php
- /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Widgets/Dashboard/RecentDriftFindings.php
- /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/forms/components/restore-run-checks.blade.php

Guard test pattern (current)

The repo already uses Pest “guard” tests that scan the codebase for forbidden patterns:
- /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Guards/NoLegacyBulkOperationsTest.php

Status / severity sources (current)

Status-like values already exist in models/enums and must remain the source of truth for meaning:

Operation runs: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Models/OperationRun.php (status) + outcome usage in UI.
Inventory sync runs: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Models/InventorySyncRun.php (status constants).
Backup schedule runs: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Models/BackupScheduleRun.php (status constants).
Entra group sync runs: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Models/EntraGroupSyncRun.php (status constants).
Restore runs: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/RestoreRunStatus.php (enum).
Findings: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Models/Finding.php (severity + status constants).

Key Decisions

Decision: Centralize status-like badge semantics behind domain mappers

Decision: Introduce a central badge semantics layer that maps a “domain” + “value” to a single badge meaning (label + color meaning + optional icon).
Rationale: Eliminates drift from per-page match blocks and keeps UI semantics testable and reviewable.
Alternatives considered:
- Inline mappings per resource/widget: rejected (drifts quickly; hard to enforce).
- Config-only mappings: rejected for v1 (harder to type-check; still needs a rendering abstraction).
- DB-stored mappings: rejected (adds runtime dependency and migration/tenant complexity for no user value).

Decision: V1 scope is “status-like” only (status/health + severity/risk)

Decision: V1 migrates status-like badges suite-wide; tag/category chips are deferred.
Rationale: Status/health and severity/risk are the highest-risk trust killers when inconsistent; tags are valuable but less safety-critical and more domain-specific.

Decision: Canonical drift severity meanings

Decision: Drift finding severity mapping is canonical: low = neutral, medium = warning, high = danger.
Rationale: Severity is a risk/attention signal; “low” should not appear as “success”.

Decision: No severity taxonomy changes in v1

Decision: Do not add/rename severity levels (for example, do not introduce “critical” in v1).
Rationale: This feature standardizes rendering semantics; changing underlying severity taxonomy is a separate scope and needs domain review.

Decision: Enforcement is tests + a lightweight guard

Decision: Add:
- Mapping tests per domain (including invariants like “success is never warning”).
- A lightweight guard test that flags newly introduced ad-hoc mappings for status/health and severity/risk.
Rationale: Mapping tests prove correctness; the guard prevents regressions and enforces the single-source-of-truth rule.
Alternatives considered:
- Strict guard banning any badge usage not from the central system: rejected (too brittle; would block deferred tag/category chip work and legitimate non-status uses).

Open Questions

None — remaining work is implementation-time discovery of all status-like badge surfaces to migrate.

4.3 KiB Raw Blame History