Address PR #68 review: make the history feature flag a true on/off switch

MONITOR_HISTORY_ENABLED was read-path only, so "default off" still ran
per-check ingestion and the hourly aggregate / daily prune jobs. Plus
follow-up correctness and clarity fixes from the code review.

Feature flag (blocker):
- Add MonitorCheckLogService::logCheckIfEnabled(); all automatic per-check
  ingestion (uptime hooks, certificate listeners, domain verification) now
  no-ops when the flag is off. logCheck() stays unconditional for operator
  paths (backfill, seeder) so history can still be pre-staged.
- Gate monitor:aggregate-check-metrics and monitor:prune-check-history behind
  ->when(config('monitor-history.enabled')) and add withoutOverlapping().
  Core uptime/certificate/domain checks remain ungated.

Correctness / clarity:
- Extract DomainService::resolveExpirationNotifications() and cover the
  expiry-warning thresholds with tests (locks the whole-day int behaviour).
- Reword monitor:backfill-check-history so it no longer implies multi-day
  history: it writes one current-state snapshot per enabled check type and
  --days only sizes the aggregation window. Locked with a test.
- Heatmap legend now reflects every colour getCellClasses() emits (green/red
  gradients + yellow), not a single swatch per status.

Docs / hygiene:
- Document the flag semantics, a revised rollout checklist, and the dedicated
  monitor_test MySQL database the suite requires.
- Untrack the accidentally committed .phpunit.cache artifact and gitignore it.

Tests: 48 passed (was 34). Pint clean. Frontend build clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: rathorevaibhav

.gitignore

@@ -7,6 +7,7 @@
 .env
 .env.backup
 .phpunit.result.cache
+/.phpunit.cache
 Homestead.json
 Homestead.yaml
 npm-debug.log

.phpunit.cache/test-results

@@ -14,11 +14,11 @@ class BackfillMonitorCheckHistory extends Command
 {
     protected $signature = 'monitor:backfill-check-history
                             {--monitor-id= : Backfill only one monitor by id}
-                            {--days=30 : Days window used for aggregation after backfill}
+                            {--days=30 : Size of the aggregation window (in days) rolled up after the snapshot; does NOT fabricate per-day history}
                             {--timezone= : Timezone used for daily aggregation}
                             {--dry-run : Preview rows without writing}';
 
-    protected $description = 'Create synthetic monitor check logs from current monitor state';
+    protected $description = 'Seed one synthetic check log per enabled check type from current monitor state (approximate, not real history)';
 
     public function handle(
         MonitorCheckLogService $logService,

app/Console/Commands/BackfillMonitorCheckHistory.php

@@ -17,7 +17,7 @@ public function handle(CertificateCheckFailed $event): void
             return;
         }
 
-        $this->monitorCheckLogService->logCheck(
+        $this->monitorCheckLogService->logCheckIfEnabled(
             monitor: $monitor,
             checkType: MonitorCheckLogService::CHECK_TYPE_CERTIFICATE,
             status: MonitorCheckLogService::STATUS_FAILED,

app/Listeners/LogCertificateCheckFailed.php

@@ -17,7 +17,7 @@ public function handle(CertificateCheckSucceeded $event): void
             return;
         }
 
-        $this->monitorCheckLogService->logCheck(
+        $this->monitorCheckLogService->logCheckIfEnabled(
             monitor: $monitor,
             checkType: MonitorCheckLogService::CHECK_TYPE_CERTIFICATE,
             status: MonitorCheckLogService::STATUS_SUCCESS,

app/Listeners/LogCertificateCheckSucceeded.php

@@ -45,7 +45,7 @@ public function uptimeRequestSucceeded(ResponseInterface $response): void
             ? $updatedMonitor->uptime_check_failure_reason
             : null;
 
-        app(MonitorCheckLogService::class)->logCheck(
+        app(MonitorCheckLogService::class)->logCheckIfEnabled(
             monitor: $updatedMonitor,
             checkType: MonitorCheckLogService::CHECK_TYPE_UPTIME,
             status: $status,
@@ -68,7 +68,7 @@ public function uptimeRequestFailed(string $reason): void
             return;
         }
 
-        app(MonitorCheckLogService::class)->logCheck(
+        app(MonitorCheckLogService::class)->logCheckIfEnabled(
             monitor: $updatedMonitor,
             checkType: MonitorCheckLogService::CHECK_TYPE_UPTIME,
             status: MonitorCheckLogService::STATUS_FAILED,

app/Models/Monitor.php

@@ -50,7 +50,7 @@ public function verifyDomainExpiration(Monitor $monitor): array
         $domainInfo = $this->getDomainExpirationDate($monitor->url);
 
         if (empty($domainInfo)) {
-            app(MonitorCheckLogService::class)->logCheck(
+            app(MonitorCheckLogService::class)->logCheckIfEnabled(
                 monitor: $monitor,
                 checkType: MonitorCheckLogService::CHECK_TYPE_DOMAIN,
                 status: MonitorCheckLogService::STATUS_FAILED,
@@ -82,7 +82,7 @@ public function verifyDomainExpiration(Monitor $monitor): array
         $status = $outcome['status'];
         $message = $outcome['message'];
 
-        app(MonitorCheckLogService::class)->logCheck(
+        app(MonitorCheckLogService::class)->logCheckIfEnabled(
             monitor: $monitor,
             checkType: MonitorCheckLogService::CHECK_TYPE_DOMAIN,
             status: $status,
@@ -124,30 +124,42 @@ public function resolveDomainExpirationOutcome(int $daysUntilExpiration): array
         return ['status' => $status, 'message' => $message];
     }
 
-    protected function checkAndNotifyExpiration(Monitor $monitor, int $daysUntilExpiration): array
+    /**
+     * Resolve which expiration-warning notifications are due for a whole-day count
+     * until expiration. Returns at most one notification (the first matching
+     * threshold). An already-expired domain (negative days) never produces an
+     * "expires in N days" warning.
+     */
+    public function resolveExpirationNotifications(int $daysUntilExpiration): array
     {
-        $expirationDate = $monitor->domain_expires_at;
-
-        if (! $expirationDate) {
+        if ($daysUntilExpiration < 0) {
             return [];
         }
 
-        $domainCheckTimePeriods = config('domain-expiration.domain_check_time_period');
+        $domainCheckTimePeriods = config('domain-expiration.domain_check_time_period', []);
 
-        $notifications = [];
-
-        foreach ($domainCheckTimePeriods as $warningType => $details) {
+        foreach ($domainCheckTimePeriods as $details) {
             $daysThreshold = $details['days'];
 
-            if ($daysUntilExpiration >= 0 && $daysUntilExpiration === $daysThreshold) {
-                $notifications[] = [
+            if ($daysUntilExpiration === $daysThreshold) {
+                return [[
                     'days' => $daysThreshold,
                     'message' => "Domain expires in $daysThreshold ".($daysThreshold === 1 ? 'day' : 'days').'!',
-                ];
-                break;
+                ]];
             }
         }
 
+        return [];
+    }
+
+    protected function checkAndNotifyExpiration(Monitor $monitor, int $daysUntilExpiration): array
+    {
+        if (! $monitor->domain_expires_at) {
+            return [];
+        }
+
+        $notifications = $this->resolveExpirationNotifications($daysUntilExpiration);
+
         if (empty($notifications)) {
             return [];
         }

app/Services/DomainService.php

@@ -23,6 +23,40 @@ class MonitorCheckLogService
 
     public const STATUS_UNKNOWN = 'unknown';
 
+    /**
+     * Log a check only when monitor history is enabled.
+     *
+     * This is the entry point for automatic, per-check ingestion (uptime/domain/
+     * certificate hooks). When the feature flag is off it is a no-op, so a "default
+     * off" deployment incurs no per-check write load. Operator-driven paths
+     * (backfill, seeder) call logCheck() directly to bypass the flag.
+     */
+    public function logCheckIfEnabled(
+        Monitor $monitor,
+        string $checkType,
+        string $status,
+        CarbonInterface|string|null $checkedAt = null,
+        ?string $message = null,
+        ?string $failureReason = null,
+        ?int $responseTimeMs = null,
+        array $metadata = []
+    ): ?MonitorCheckLog {
+        if (! config('monitor-history.enabled')) {
+            return null;
+        }
+
+        return $this->logCheck(
+            $monitor,
+            $checkType,
+            $status,
+            $checkedAt,
+            $message,
+            $failureReason,
+            $responseTimeMs,
+            $metadata
+        );
+    }
+
     public function logCheck(
         Monitor $monitor,
         string $checkType,

app/Services/MonitorCheckLogService.php

@@ -107,3 +107,32 @@ Before you start following the guidelines, make sure to go through the [prerequi
     php artisan serve
     ```
     Note- php artisan serve command will start a development server on your local machine that listens to port 8000 by default. This command will provide a link in the terminal which we can copy and paste it in our browser and see our laraver application.
+
+## Running tests
+
+The test suite runs against MySQL (not SQLite) so `RefreshDatabase` exercises the
+same engine as production. It uses a **dedicated** database named `monitor_test`
+(configured in `phpunit.xml`) so tests never touch your development data — a guard
+test fails fast if the suite is pointed anywhere else.
+
+1. Create the test database once:
+
+    ```sh
+    mysql -u root -e "CREATE DATABASE IF NOT EXISTS monitor_test;"
+    ```
+
+    (Adjust the user/host to match your `.env`. No data needs to be seeded —
+    migrations run automatically.)
+
+2. If `php artisan config:cache` was ever run, clear it first, otherwise the cached
+   `DB_DATABASE` overrides `phpunit.xml` and the suite would run against your dev DB:
+
+    ```sh
+    php artisan config:clear
+    ```
+
+3. Run the suite:
+
+    ```sh
+    php artisan test
+    ```

docs/installation.md

@@ -4,12 +4,27 @@ This document covers operational workflows for monitor history logging, aggregat
 
 ## Feature Flag
 
-Monitor history UI and payload are controlled by:
+The entire monitor-history feature is controlled by a single flag (default **off**):
 
 ```bash
 MONITOR_HISTORY_ENABLED=true
 ```
 
+When the flag is **off**, the feature is a true no-op:
+
+- Per-check ingestion (uptime/domain/certificate hooks) writes **no** rows to
+  `monitor_check_logs`, so there is no added write load.
+- The scheduled `monitor:aggregate-check-metrics` and `monitor:prune-check-history`
+  jobs are skipped entirely (nothing is aggregated or pruned).
+- The monitor detail page returns no history payload.
+
+Core uptime/certificate/domain checking and domain-expiry notifications are
+**not** affected by this flag — they always run.
+
+Operator commands (`monitor:backfill-check-history`, `monitor:aggregate-check-metrics`,
+`monitor:prune-check-history`) can still be run manually regardless of the flag, so
+history can be pre-staged before the feature is switched on.
+
 ## Timezone
 
 Daily metrics are bucketed by a single server-side timezone, and the monitor
@@ -44,7 +59,8 @@ Useful options:
 
 ### Backfill synthetic logs (one-time bootstrap)
 
-Creates synthetic check logs from current monitor state and aggregates days window.
+Seeds **one** synthetic check log per enabled check type from each monitor's
+*current* state, then aggregates the window into daily metrics.
 
 ```bash
 php artisan monitor:backfill-check-history --days=30
@@ -59,7 +75,11 @@ Useful options:
 Notes:
 
 - Backfill records include `metadata.source=backfill`.
-- Backfill is best-effort and should be treated as approximate history.
+- This is a **single current-state snapshot per check type**, not a reconstruction
+  of real per-day history (that data does not exist). It exists only so a monitor
+  is not completely empty before real checks start accumulating. `--days` sizes the
+  aggregation window that rolls the snapshot up; it does not fabricate per-day rows.
+- Real history begins accumulating from the moment the feature flag is switched on.
 
 ### Prune old raw logs
 
@@ -76,12 +96,13 @@ Useful options:
 
 ## Scheduler
 
-Configured schedules:
+History maintenance schedules (only run while `MONITOR_HISTORY_ENABLED=true`, and
+guarded with `withoutOverlapping()` so a slow run cannot stack on the next tick):
 
 - `monitor:aggregate-check-metrics` hourly
 - `monitor:prune-check-history` daily at `01:00`
 
-Existing schedules remain unchanged:
+Existing core schedules remain unchanged and always run:
 
 - `monitor:check-uptime` every minute
 - `monitor:check-certificate` daily
@@ -101,22 +122,27 @@ Default:
 ## Rollout Checklist
 
 1. Deploy migrations for history tables and idempotency key.
-2. Deploy ingestion listeners/model hooks/services.
-3. Enable scheduler entries for aggregate/prune commands.
-4. Run backfill in `--dry-run` mode and review expected writes.
-5. Run live backfill once approved.
-6. Validate monitor detail page:
+2. Deploy the code (ingestion hooks, scheduler entries, services). All of it stays
+   dormant while `MONITOR_HISTORY_ENABLED` is off.
+3. (Optional) Pre-stage approximate history while the flag is still off:
+   - Run `monitor:backfill-check-history --dry-run` and review expected writes.
+   - Run the live backfill once approved.
+4. Enable `MONITOR_HISTORY_ENABLED=true` in the target environment. This activates,
+   together: per-check ingestion, the hourly aggregate + daily prune schedules, and
+   the detail-page payload. Real history accumulates from this point forward.
+5. Validate the monitor detail page:
    - range filters work
    - heatmaps render by check type
    - recent checks and totals are sensible
-7. Enable `MONITOR_HISTORY_ENABLED=true` in target environment.
-8. Monitor logs for command failures and verify aggregate row growth.
+6. Monitor logs for command failures and verify aggregate row growth.
 
 ## Troubleshooting
 
 ### No heatmap data visible
 
-- Confirm feature flag is enabled.
+- Confirm `MONITOR_HISTORY_ENABLED=true`. Ingestion only writes logs while the flag
+  is on, so a freshly enabled feature has no history until checks run (or a backfill
+  is performed).
 - Confirm `monitor_check_logs` has data.
 - Run `monitor:aggregate-check-metrics --lookback=30`.
 - Check selected timezone/range in monitor detail.