fuel-alert/.claude/rules/architecture.md

Architecture

Shape: Vue SPA ⇄ REST API ⇄ fat Laravel Services

The frontend is a Vue 3 single-page app (resources/js/). It talks to the backend exclusively over a REST API (routes/api.php → app/Http/Controllers/Api/). Controllers stay thin; all business logic lives in Service classes (app/Services/). Blade is reduced to a one-line SPA shell, server-rendered legal pages, transactional emails, and the Filament admin panel.

Browser
  └── Vue SPA (resources/js, mounted on #app via app.blade.php)
        └── axios (resources/js/axios.js — baseURL '/api', cookie + XSRF auth)
              └── REST API (routes/api.php → Http/Controllers/Api/*)
                    └── Services (app/Services/*)   ← all business logic
                          └── Models / Jobs / Events / Notifications

Core principle: fat Services, thin everything else

All business logic lives in Service classes. API controllers, console commands, jobs, listeners, and Filament resources are thin orchestrators — they call Services and return results. Never put domain logic in a controller or a Vue component.

Directory structure (actual)

app/
├── Console/Commands/   # Scheduler: PollFuelPrices, FetchOilPrices, BackfillOilPrices,
│                       #   RunLlmOverlay, EvaluateVolatilityRegime, ResolveForecastOutcomes,
│                       #   ArchiveOldPricesCommand, ImportBeisFuelPrices, ImportPostcodes
├── Http/
│   ├── Controllers/Api/   # AuthController, StationController, StatsController, UserController
│   ├── Controllers/       # BillingController (Stripe Checkout/Portal redirects)
│   ├── Middleware/        # VerifyApiKey (API-key gate), RequiresFeature (tier gate)
│   ├── Requests/          # Form requests
│   └── Resources/Api/     # StationResource (API output shaping)
├── Actions/Fortify/    # Fortify auth actions (CreateNewUser, …)
├── Services/           # ALL business logic — see below
├── Models/             # Eloquent models
├── Notifications/      # FuelPriceAlert + custom Channels (OneSignal, Vonage WA/SMS)
├── Jobs/               # DispatchUserNotificationJob, PollFuelPricesJob,
│                       #   SendScheduledWhatsAppJob, SendPaymentFailedReminderJob
├── Events/             # PricesUpdatedEvent
├── Listeners/          # HandleStripeWebhook (Cashier WebhookReceived)
├── Filament/           # Admin panel (Resources, Widgets) + Providers/Filament
├── Enums/              # FuelType, PlanTier, …
└── Livewire/Actions/   # Logout only — Livewire is otherwise vestigial

app/Services/
├── FuelPriceService.php       # Fuel Finder API polling + storage
├── StationTaggingService.php  # Supermarket brand detection
├── PostcodeService.php        # postcode/outcode/place → lat/lng (+ LocationResult DTO)
├── PlanFeatures.php           # Single source of tier-entitlement truth (see tiers.md)
├── HaversineQuery.php         # Distance SQL helper
├── ApiLogger.php              # Wraps outbound HTTP, logs to api_logs
├── StationSearch/             # StationSearchService (+ SearchCriteria, SearchResult DTOs)
├── BrentPriceSources/         # FRED + EIA Brent sources (+ BrentPriceFetcher)
└── Forecasting/               # Weekly forecast subsystem — WeeklyForecastService,
                               #   LlmOverlayService, BacktestRunner, OutcomeResolver,
                               #   VolatilityRegimeService, feature/leak tooling, …

resources/
├── js/                 # Vue 3 SPA — see .claude/rules/frontend.md
└── views/
    ├── app.blade.php   # SPA shell (mounts #app)
    ├── legal/          # Server-rendered legal pages
    ├── emails/         # Mailable templates
    └── livewire/auth/  # Starter-kit Volt auth screens (left untouched)

routes/
├── web.php             # SPA shell + catch-all, legal pages, billing redirects, server logout
└── api.php             # REST API consumed by the SPA (see below)

Stale service names elsewhere. Domain rule files (scoring.md, prediction.md, notifications.md) still name services that have since been refactored away — e.g. AlertScoringService, OilPriceService, NationalFuelPredictionService, NotificationDispatchService, SubscriptionService. Those concerns now live under Services/Forecasting/, Services/StationSearch/, and PlanFeatures. Always verify a service name against app/Services/ before trusting it from those files.

Service class conventions

• Constructor injection only — no facade usage inside Services
• Each Service has one responsibility — do not merge concerns
• Return typed DTOs or Eloquent collections — never raw arrays from Services
• Services never dispatch jobs directly — that's the controller/command/listener's job

The REST API

routes/api.php is the SPA's backend. Three access tiers:

• Public (no auth): POST /api/auth/register, POST /api/auth/login, GET /api/auth/me, GET /api/fuel-types, GET /api/stats/live
• API-key (VerifyApiKey + throttle:60,1): GET /api/stations, GET /api/stats/searches
• Sanctum (auth:sanctum): POST /api/auth/logout, /api/user/* (preferences, saved stations, profile, password, delete account)

Conventions:

• Shape responses with API Resources (app/Http/Resources/Api/), never raw arrays.
• The fuel prediction is embedded in the /api/stations response under the prediction key — there is no standalone prediction endpoint (see prediction.md).
• Tier-gate routes with the feature middleware (RequiresFeature); never inline entitlement checks (see tiers.md).
• Auth is cookie/session via Sanctum SPA mode (axios sends XSRF + credentials); the API-key gate protects the expensive station search from scraping.

Frontend

The Vue SPA is documented in .claude/rules/frontend.md. Do not build new Livewire components — Livewire/Flux remain only for the starter-kit auth screens and the Logout action.