MainController.php

<?php

namespace App\Http\Controllers\User;

use App\Http\Controllers\Controller;
use App\Models\Project;
use App\Models\ProjectCustomStat;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

/**
 * User portal dashboard — serves the overview for the authenticated client's
 * active project, real-time stats, and oversight health score.
 */
class MainController extends Controller
{
    public function dashboard()
    {
        $user = auth('user')->user();
        $project = $user->projects()->with(['customStats', 'reports'])->first();
        // Build $customStats and calculate oversight health score
        // Returns: $project, $customStats, $oversightHealth
        // ...
    }

    private function calculateOversightHealth(Project $project, $customStats): array
    {
        // Calculates a composite health score (0–100) from data point counts,
        // report submission frequency, and visit completion rates.
        // Returns ['score' => int, 'label' => string, 'breakdown' => array]
        // Returns score: 0 (not a default 75) when no metrics have been recorded yet.
        // ...
    }
}