fuel-price/docs/superpowers/specs/2026-04-04-filament-admin-design.md

Filament Admin Panel — Design Spec

Date: 2026-04-04
Stack: Laravel 11, Filament v5, Livewire v4
Scope: Admin panel for FuelAlert — internal tooling only, no user-facing exposure

---

1. Access & Auth

• Filament panel mounted at /admin
• Protected by is_admin boolean on users table
• Migration adds is_admin TINYINT(1) DEFAULT 0 to users
• AdminPanelProvider uses ->authGuard('web') (same guard as the main app — no separate admin users table)
• canAccessPanel() check: $user->is_admin === true
• uovidiu@sent.com seeded as admin via a dedicated AdminSeeder (idempotent — safe to re-run)
• No self-registration on the admin panel — access is granted only via the is_admin flag

---

2. Dashboard Page

Default landing page. Four StatsOverviewWidget cards:

Stat	Source	Alert
Total users	users count	—
Stations in DB	stations count + max(last_seen_at)	—
Latest oil prediction	Most recent price_predictions row — direction, confidence, source	Yellow if > 24h old
API errors (24h)	api_logs where status_code >= 400 or error IS NOT NULL, last 24h	Red if > 0

No charts on the dashboard — keep it scannable. Charts live inside individual resources.

---

3. Resources

3.1 Users (UserResource)

Purpose: View all registered users, manage admin flag, correct postcodes.

Table columns: name, email, postcode, is_admin (badge), created_at
Filters: is_admin toggle
Actions:

• Edit: is_admin toggle, postcode text field (no other fields editable from admin)
• Delete: allowed (hard delete, with confirmation modal)

Notes:

• No subscription tier column yet — add when Cashier is integrated
• No impersonation in v1 — add later when user dashboard exists

---

3.2 API Logs (ApiLogResource)

Purpose: Primary debugging tool — see every outbound HTTP call made by the scheduler.

Table columns: service (badge), method, url (truncated), status_code (colour-coded), duration_ms, error (truncated), created_at
Filters: service (select: fuel_finder, fred, anthropic), errors only (toggle: where error IS NOT NULL or status >= 400), date range
Default sort: created_at DESC
Actions: View (modal showing full url, full error, request/response if available) — no edit, no delete

Colour coding for status_code:

• 2xx → success (green)
• 4xx → warning (yellow)
• 5xx / null → danger (red)

---

3.3 Oil Predictions (OilPredictionResource)

Purpose: Verify the daily oil:predict job is running and producing sensible output.

Table columns: predicted_for (date), source (badge: LLM / EWMA), direction (badge: rising/falling/flat with colour), confidence (progress bar 0–100), reasoning (truncated), generated_at
Filters: source, direction, date range
Default sort: predicted_for DESC
Actions:

• View (modal showing full reasoning text)
• Run prediction now (page-level action): executes php artisan oil:predict via Artisan::call(), shows success/failure notification

No edit/delete — predictions are immutable audit records.

---

3.4 Brent Prices (BrentPriceResource)

Purpose: Verify FRED fetch is populating data correctly.

Table columns: date, price_usd
Default sort: date DESC
Actions: none

Simple read-only table. No filters needed — data is always chronological. Include a line chart widget (BrentPriceChartWidget) showing the last 30 days using Filament's built-in chart widget.

---

3.5 Stations (StationResource)

Purpose: Browse the ~14,500 UK stations; verify supermarket tagging and closure flags.

Table columns: trading_name, brand_name, postcode, city, is_supermarket (badge), is_motorway_service_station (badge), temporary_closure (badge), last_seen_at
Filters: is_supermarket, is_motorway_service_station, temporary_closure, permanent_closure, postcode prefix (text search)
Search: trading_name, brand_name, postcode
Default sort: last_seen_at DESC
Actions:

• View (modal with full address, amenities, opening_times, fuel_types JSON)
• Trigger full poll (page-level action): dispatches a queued PollFuelPricesJob (wraps fuel:poll --full) rather than calling Artisan synchronously — full station refresh on 14,500 records would exceed HTTP timeout. Shows "Poll dispatched to queue" notification immediately; result visible in API Logs once complete.

No edit — station data is owned by Fuel Finder API, overwritten on each poll.

---

4. Resources Planned But Not Built Yet

These will be added once the underlying tables/services exist:

Resource	Depends on
Alerts Log	alerts table + NotificationDispatchService
Scoring Results	scoring_results table + AlertScoringService
Subscriptions	Cashier integration + subscriptions table

---

5. Navigation Groups

Dashboard (no group)
├── Users
Data
├── Stations
├── Brent Prices
├── Oil Predictions
System
├── API Logs

---

6. Build Order

1. Migration — add is_admin to users
2. AdminSeeder — seed uovidiu@sent.com as admin
3. AdminPanelProvider — mount panel, configure auth
4. ApiLogResource — highest immediate value
5. UserResource — manage admin flag
6. OilPredictionResource + run-prediction action
7. BrentPriceResource + chart widget
8. StationResource + full-poll action
9. Dashboard widgets (last — depends on all resources being stable)

---

7. Out of Scope (v1)

• Role-based permissions beyond is_admin — single admin user is sufficient
• Activity log / audit trail of admin actions
• Dark mode customisation
• Custom Filament theme — use default
• Two-factor auth on admin panel — covered by app-level 2FA (Fortify)