Add Popular Routes

Curated from/to destination pairs for marketing content, editable via a
Filament resource and served publicly (no auth, IP-throttled like CMS
pages) through GET /api/v1/popular-routes. The API response trims each
nested destination down to id/name/mm_name rather than the full catalog
resource.

app-modules/routing/database/factories/PopularRouteFactory.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Modules\Routing\Database\Factories;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+use Modules\Catalog\Models\Destination;
+use Modules\Routing\Models\PopularRoute;
+
+/**
+ * @extends Factory<PopularRoute>
+ */
+class PopularRouteFactory extends Factory
+{
+    /**
+     * Define the model's default state.
+     *
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        return [
+            'from_destination_id' => Destination::factory(),
+            'to_destination_id' => Destination::factory(),
+            'description' => fake()->sentence(),
+            'mm_description' => fake()->sentence(),
+            'is_active' => true,
+        ];
+    }
+}

app-modules/routing/database/migrations/2026_08_28_000000_create_popular_routes_table.php

@@ -0,0 +1,34 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('popular_routes', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('from_destination_id')->constrained('destinations')->cascadeOnDelete();
+            $table->foreignId('to_destination_id')->constrained('destinations')->cascadeOnDelete();
+            $table->text('description')->nullable();
+            $table->text('mm_description')->nullable();
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+
+            $table->unique(['from_destination_id', 'to_destination_id']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('popular_routes');
+    }
+};

app-modules/routing/routes/routing-routes.php

@@ -2,6 +2,7 @@
 
 use Illuminate\Support\Facades\Route;
 use Modules\Routing\Http\Controllers\EvRouteController;
+use Modules\Routing\Http\Controllers\PopularRouteController;
 
 Route::prefix('api/v1')->middleware(['api', 'api.auth', 'throttle:api-read'])->group(function () {
     Route::post('/routes/search', [EvRouteController::class, 'search'])->name('routing.routes.search');
@@ -9,3 +10,10 @@ Route::prefix('api/v1')->middleware(['api', 'api.auth', 'throttle:api-read'])->g
     Route::get('/routes/{route}/pricing', [EvRouteController::class, 'pricing'])->name('routing.routes.pricing');
     Route::get('/routes/{route}/time-slots', [EvRouteController::class, 'timeSlots'])->name('routing.routes.time-slots');
 });
+
+// Popular Routes are curated marketing content, typically shown before the
+// user logs in (like CMS pages), so this group skips api.auth —
+// throttle:api-read still rate-limits it by IP.
+Route::prefix('api/v1')->middleware(['api', 'throttle:api-read'])->group(function () {
+    Route::get('/popular-routes', [PopularRouteController::class, 'index'])->name('routing.popular-routes.index');
+});

app-modules/routing/src/Filament/Resources/PopularRoutes/Pages/CreatePopularRoute.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Modules\Routing\Filament\Resources\PopularRoutes\Pages;
+
+use Filament\Resources\Pages\CreateRecord;
+use Modules\Routing\Filament\Resources\PopularRoutes\PopularRouteResource;
+
+class CreatePopularRoute extends CreateRecord
+{
+    protected static string $resource = PopularRouteResource::class;
+}

app-modules/routing/src/Filament/Resources/PopularRoutes/Pages/EditPopularRoute.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Modules\Routing\Filament\Resources\PopularRoutes\Pages;
+
+use Filament\Actions\DeleteAction;
+use Filament\Resources\Pages\EditRecord;
+use Modules\Routing\Filament\Resources\PopularRoutes\PopularRouteResource;
+
+class EditPopularRoute extends EditRecord
+{
+    protected static string $resource = PopularRouteResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [
+            DeleteAction::make(),
+        ];
+    }
+}

app-modules/routing/src/Filament/Resources/PopularRoutes/Pages/ListPopularRoutes.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Modules\Routing\Filament\Resources\PopularRoutes\Pages;
+
+use Filament\Actions\CreateAction;
+use Filament\Resources\Pages\ListRecords;
+use Modules\Routing\Filament\Resources\PopularRoutes\PopularRouteResource;
+
+class ListPopularRoutes extends ListRecords
+{
+    protected static string $resource = PopularRouteResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [
+            CreateAction::make(),
+        ];
+    }
+}

app-modules/routing/src/Filament/Resources/PopularRoutes/PopularRouteResource.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Modules\Routing\Filament\Resources\PopularRoutes;
+
+use BackedEnum;
+use Filament\Resources\Resource;
+use Filament\Schemas\Schema;
+use Filament\Support\Icons\Heroicon;
+use Filament\Tables\Table;
+use Modules\Routing\Filament\Resources\PopularRoutes\Pages\CreatePopularRoute;
+use Modules\Routing\Filament\Resources\PopularRoutes\Pages\EditPopularRoute;
+use Modules\Routing\Filament\Resources\PopularRoutes\Pages\ListPopularRoutes;
+use Modules\Routing\Filament\Resources\PopularRoutes\Schemas\PopularRouteForm;
+use Modules\Routing\Filament\Resources\PopularRoutes\Tables\PopularRoutesTable;
+use Modules\Routing\Models\PopularRoute;
+use UnitEnum;
+
+class PopularRouteResource extends Resource
+{
+    protected static ?string $model = PopularRoute::class;
+
+    protected static string|BackedEnum|null $navigationIcon = Heroicon::OutlinedFire;
+
+    protected static string|UnitEnum|null $navigationGroup = 'Routing';
+
+    public static function form(Schema $schema): Schema
+    {
+        return PopularRouteForm::configure($schema);
+    }
+
+    public static function table(Table $table): Table
+    {
+        return PopularRoutesTable::configure($table);
+    }
+
+    public static function getPages(): array
+    {
+        return [
+            'index' => ListPopularRoutes::route('/'),
+            'create' => CreatePopularRoute::route('/create'),
+            'edit' => EditPopularRoute::route('/{record}/edit'),
+        ];
+    }
+}

app-modules/routing/src/Filament/Resources/PopularRoutes/Schemas/PopularRouteForm.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace Modules\Routing\Filament\Resources\PopularRoutes\Schemas;
+
+use Filament\Forms\Components\Select;
+use Filament\Forms\Components\Textarea;
+use Filament\Forms\Components\Toggle;
+use Filament\Schemas\Components\Grid;
+use Filament\Schemas\Components\Section;
+use Filament\Schemas\Components\Utilities\Get;
+use Filament\Schemas\Schema;
+use Illuminate\Validation\Rules\Unique;
+
+class PopularRouteForm
+{
+    public static function configure(Schema $schema): Schema
+    {
+        return $schema
+            ->components([
+                Section::make('Popular Route')
+                    ->schema([
+                        Grid::make(2)
+                            ->schema([
+                                Select::make('from_destination_id')
+                                    ->label('From')
+                                    ->relationship('fromDestination', 'name')
+                                    ->required()
+                                    ->searchable()
+                                    ->preload()
+                                    ->live(),
+                                Select::make('to_destination_id')
+                                    ->label('To')
+                                    ->relationship('toDestination', 'name')
+                                    ->required()
+                                    ->searchable()
+                                    ->preload()
+                                    ->different('from_destination_id')
+                                    ->unique(
+                                        modifyRuleUsing: fn (Unique $rule, Get $get) => $rule->where('from_destination_id', $get('from_destination_id')),
+                                        ignoreRecord: true,
+                                    )
+                                    ->validationMessages([
+                                        'different' => 'The destination must be different from the origin.',
+                                        'unique' => 'A popular route between these destinations already exists.',
+                                    ]),
+                            ]),
+                        Textarea::make('description')
+                            ->columnSpanFull(),
+                        Textarea::make('mm_description')
+                            ->label('Myanmar Description')
+                            ->columnSpanFull(),
+                        Toggle::make('is_active')
+                            ->required()
+                            ->default(true),
+                    ]),
+            ]);
+    }
+}

app-modules/routing/src/Filament/Resources/PopularRoutes/Tables/PopularRoutesTable.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace Modules\Routing\Filament\Resources\PopularRoutes\Tables;
+
+use Filament\Actions\BulkActionGroup;
+use Filament\Actions\DeleteBulkAction;
+use Filament\Actions\EditAction;
+use Filament\Tables\Columns\IconColumn;
+use Filament\Tables\Columns\TextColumn;
+use Filament\Tables\Filters\SelectFilter;
+use Filament\Tables\Filters\TernaryFilter;
+use Filament\Tables\Table;
+
+class PopularRoutesTable
+{
+    public static function configure(Table $table): Table
+    {
+        return $table
+            ->columns([
+                TextColumn::make('fromDestination.name')
+                    ->label('From')
+                    ->searchable()
+                    ->sortable(),
+                TextColumn::make('toDestination.name')
+                    ->label('To')
+                    ->searchable()
+                    ->sortable(),
+                TextColumn::make('description')
+                    ->limit(50)
+                    ->toggleable(isToggledHiddenByDefault: true),
+                IconColumn::make('is_active')
+                    ->boolean(),
+                TextColumn::make('created_at')
+                    ->dateTime()
+                    ->sortable()
+                    ->toggleable(isToggledHiddenByDefault: true),
+            ])
+            ->filters([
+                SelectFilter::make('from_destination_id')
+                    ->label('From')
+                    ->relationship('fromDestination', 'name')
+                    ->searchable()
+                    ->preload(),
+                SelectFilter::make('to_destination_id')
+                    ->label('To')
+                    ->relationship('toDestination', 'name')
+                    ->searchable()
+                    ->preload(),
+                TernaryFilter::make('is_active'),
+            ])
+            ->recordActions([
+                EditAction::make(),
+            ])
+            ->toolbarActions([
+                BulkActionGroup::make([
+                    DeleteBulkAction::make(),
+                ]),
+            ]);
+    }
+}

app-modules/routing/src/Http/Controllers/PopularRouteController.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Modules\Routing\Http\Controllers;
+
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+use Illuminate\Routing\Controller;
+use Illuminate\Support\Facades\Cache;
+use Modules\Routing\Http\Resources\PopularRouteResource;
+use Modules\Routing\Models\PopularRoute;
+
+class PopularRouteController extends Controller
+{
+    public function index(): AnonymousResourceCollection
+    {
+        $popularRoutes = Cache::tags('routes')->remember(
+            'routes:popular',
+            now()->addMinutes(5),
+            fn () => PopularRoute::query()
+                ->where('is_active', true)
+                ->with(['fromDestination', 'toDestination'])
+                ->get(),
+        );
+
+        return PopularRouteResource::collection($popularRoutes);
+    }
+}

app-modules/routing/src/Http/Resources/PopularRouteResource.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace Modules\Routing\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+use Modules\Catalog\Models\Destination;
+
+class PopularRouteResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'from_destination' => $this->whenLoaded('fromDestination', fn () => self::destinationSummary($this->fromDestination)),
+            'to_destination' => $this->whenLoaded('toDestination', fn () => self::destinationSummary($this->toDestination)),
+            'description' => $this->description,
+            'mm_description' => $this->mm_description,
+        ];
+    }
+
+    /**
+     * Trimmed down from the full DestinationResource (id/name/mm_name only)
+     * — a popular route only needs enough to label the two endpoints, not
+     * every catalog field.
+     *
+     * @return array<string, mixed>
+     */
+    private static function destinationSummary(Destination $destination): array
+    {
+        return [
+            'id' => $destination->id,
+            'name' => $destination->name,
+            'mm_name' => $destination->mm_name,
+        ];
+    }
+}

app-modules/routing/src/Models/PopularRoute.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace Modules\Routing\Models;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use InvalidArgumentException;
+use Modules\Catalog\Models\Destination;
+use Modules\Routing\Database\Factories\PopularRouteFactory;
+use Spatie\Activitylog\Models\Concerns\LogsActivity;
+use Spatie\Activitylog\Support\LogOptions;
+
+class PopularRoute extends Model
+{
+    /** @use HasFactory<PopularRouteFactory> */
+    use HasFactory, LogsActivity;
+
+    /**
+     * Full CRUD audit trail — staff-curated content, infrequent writes
+     * (domain.md §6; T6.2), same as EvRoute/Destination.
+     */
+    public function getActivitylogOptions(): LogOptions
+    {
+        return LogOptions::defaults()
+            ->logFillable()
+            ->logOnlyDirty()
+            ->dontLogEmptyChanges()
+            ->useLogName('routing');
+    }
+
+    /**
+     * @var list<string>
+     */
+    protected $fillable = [
+        'from_destination_id',
+        'to_destination_id',
+        'description',
+        'mm_description',
+        'is_active',
+    ];
+
+    /**
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'is_active' => 'boolean',
+        ];
+    }
+
+    protected static function booted(): void
+    {
+        static::saving(function (self $popularRoute): void {
+            if ($popularRoute->from_destination_id === $popularRoute->to_destination_id) {
+                throw new InvalidArgumentException("A popular route's from and to destinations must be different.");
+            }
+        });
+    }
+
+    public function fromDestination(): BelongsTo
+    {
+        return $this->belongsTo(Destination::class, 'from_destination_id');
+    }
+
+    public function toDestination(): BelongsTo
+    {
+        return $this->belongsTo(Destination::class, 'to_destination_id');
+    }
+}

app-modules/routing/src/Observers/PopularRouteObserver.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Modules\Routing\Observers;
+
+use Illuminate\Support\Facades\Cache;
+use Modules\Routing\Models\PopularRoute;
+
+class PopularRouteObserver
+{
+    public function saved(PopularRoute $popularRoute): void
+    {
+        Cache::tags('routes')->flush();
+    }
+
+    public function deleted(PopularRoute $popularRoute): void
+    {
+        Cache::tags('routes')->flush();
+    }
+}

app-modules/routing/src/Providers/RoutingServiceProvider.php

@@ -5,8 +5,10 @@ namespace Modules\Routing\Providers;
 use Illuminate\Contracts\Auth\Access\Gate;
 use Illuminate\Support\ServiceProvider;
 use Modules\Routing\Models\EvRoute;
+use Modules\Routing\Models\PopularRoute;
 use Modules\Routing\Models\RoutePricing;
 use Modules\Routing\Observers\EvRouteObserver;
+use Modules\Routing\Observers\PopularRouteObserver;
 use Modules\Routing\Observers\RoutePricingObserver;
 use Modules\Routing\Policies\RoutePolicy;
 
@@ -17,8 +19,13 @@ class RoutingServiceProvider extends ServiceProvider
     public function boot(Gate $gate): void
     {
         $gate->policy(EvRoute::class, RoutePolicy::class);
+        // RoutePolicy only gates on the manage_routes permission (no
+        // model-specific logic), so it's reused as-is rather than adding a
+        // near-identical PopularRoutePolicy.
+        $gate->policy(PopularRoute::class, RoutePolicy::class);
 
         EvRoute::observe(EvRouteObserver::class);
         RoutePricing::observe(RoutePricingObserver::class);
+        PopularRoute::observe(PopularRouteObserver::class);
     }
 }

app-modules/routing/tests/Feature/PopularRouteResourceTest.php

@@ -0,0 +1,116 @@
+<?php
+
+use App\Models\User;
+use Illuminate\Database\QueryException;
+use Livewire\Livewire;
+use Modules\Catalog\Models\Destination;
+use Modules\Routing\Filament\Resources\PopularRoutes\Pages\CreatePopularRoute;
+use Modules\Routing\Filament\Resources\PopularRoutes\Pages\EditPopularRoute;
+use Modules\Routing\Filament\Resources\PopularRoutes\Pages\ListPopularRoutes;
+use Modules\Routing\Models\PopularRoute;
+use Spatie\Permission\Models\Permission;
+
+use function Pest\Laravel\assertDatabaseHas;
+
+beforeEach(function () {
+    Permission::findOrCreate('manage_routes', 'web');
+
+    $this->admin = User::factory()->create()->givePermissionTo('manage_routes');
+    $this->actingAs($this->admin);
+});
+
+test('can list popular routes', function () {
+    $routes = PopularRoute::factory()->count(3)->create();
+
+    Livewire::test(ListPopularRoutes::class)
+        ->assertOk()
+        ->assertCanSeeTableRecords($routes);
+});
+
+test('can create a popular route', function () {
+    $from = Destination::factory()->create();
+    $to = Destination::factory()->create();
+
+    Livewire::test(CreatePopularRoute::class)
+        ->fillForm([
+            'from_destination_id' => $from->id,
+            'to_destination_id' => $to->id,
+            'description' => 'A scenic drive.',
+            'mm_description' => 'သာယာသောခရီးစဉ်။',
+            'is_active' => true,
+        ])
+        ->call('create')
+        ->assertNotified()
+        ->assertRedirect();
+
+    assertDatabaseHas(PopularRoute::class, [
+        'from_destination_id' => $from->id,
+        'to_destination_id' => $to->id,
+        'description' => 'A scenic drive.',
+        'mm_description' => 'သာယာသောခရီးစဉ်။',
+        'is_active' => true,
+    ]);
+});
+
+test('from and to destinations must be different', function () {
+    $destination = Destination::factory()->create();
+
+    Livewire::test(CreatePopularRoute::class)
+        ->fillForm([
+            'from_destination_id' => $destination->id,
+            'to_destination_id' => $destination->id,
+        ])
+        ->call('create')
+        ->assertHasFormErrors(['to_destination_id' => 'different']);
+});
+
+test('the same from/to destination pair cannot be created twice', function () {
+    $existing = PopularRoute::factory()->create();
+
+    Livewire::test(CreatePopularRoute::class)
+        ->fillForm([
+            'from_destination_id' => $existing->from_destination_id,
+            'to_destination_id' => $existing->to_destination_id,
+        ])
+        ->call('create')
+        ->assertHasFormErrors(['to_destination_id' => 'unique']);
+});
+
+test('editing a popular route keeps its own from/to pair valid', function () {
+    $popularRoute = PopularRoute::factory()->create();
+
+    Livewire::test(EditPopularRoute::class, ['record' => $popularRoute->getRouteKey()])
+        ->fillForm(['description' => 'Updated description.'])
+        ->call('save')
+        ->assertHasNoFormErrors();
+
+    assertDatabaseHas(PopularRoute::class, [
+        'id' => $popularRoute->id,
+        'description' => 'Updated description.',
+    ]);
+});
+
+test('a user without manage_routes is forbidden from the popular routes page', function () {
+    $support = User::factory()->create();
+    $this->actingAs($support);
+
+    $this->get('/admin/popular-routes')->assertForbidden();
+});
+
+test('the model rejects saving with the same from and to destination directly', function () {
+    $destination = Destination::factory()->create();
+
+    expect(fn () => PopularRoute::factory()->create([
+        'from_destination_id' => $destination->id,
+        'to_destination_id' => $destination->id,
+    ]))->toThrow(InvalidArgumentException::class);
+});
+
+test('the database rejects a duplicate from/to pair directly', function () {
+    $existing = PopularRoute::factory()->create();
+
+    expect(fn () => PopularRoute::factory()->create([
+        'from_destination_id' => $existing->from_destination_id,
+        'to_destination_id' => $existing->to_destination_id,
+    ]))->toThrow(QueryException::class);
+});

app-modules/routing/tests/Feature/PopularRoutesReadApiTest.php

@@ -0,0 +1,59 @@
+<?php
+
+use Modules\Catalog\Models\Destination;
+use Modules\Routing\Models\PopularRoute;
+
+test('lists active popular routes with nested destinations, no auth required', function () {
+    $from = Destination::factory()->create();
+    $to = Destination::factory()->create();
+
+    PopularRoute::factory()->create([
+        'from_destination_id' => $from->id,
+        'to_destination_id' => $to->id,
+        'description' => 'A scenic drive.',
+        'mm_description' => 'သာယာသောခရီးစဉ်။',
+        'is_active' => true,
+    ]);
+
+    PopularRoute::factory()->create(['is_active' => false]);
+
+    $this->getJson('/api/v1/popular-routes')
+        ->assertSuccessful()
+        ->assertJsonCount(1, 'data')
+        ->assertJsonPath('data.0.from_destination.id', $from->id)
+        ->assertJsonPath('data.0.to_destination.id', $to->id)
+        ->assertJsonPath('data.0.description', 'A scenic drive.')
+        ->assertJsonPath('data.0.mm_description', 'သာယာသောခရီးစဉ်။');
+});
+
+test('the nested destinations only expose id, name and mm_name, not the full catalog fields', function () {
+    $from = Destination::factory()->create();
+    $to = Destination::factory()->create();
+
+    PopularRoute::factory()->create([
+        'from_destination_id' => $from->id,
+        'to_destination_id' => $to->id,
+        'is_active' => true,
+    ]);
+
+    $this->getJson('/api/v1/popular-routes')
+        ->assertSuccessful()
+        ->assertJsonPath('data.0.from_destination', [
+            'id' => $from->id,
+            'name' => $from->name,
+            'mm_name' => $from->mm_name,
+        ])
+        ->assertJsonPath('data.0.to_destination', [
+            'id' => $to->id,
+            'name' => $to->name,
+            'mm_name' => $to->mm_name,
+        ]);
+});
+
+test('an inactive popular route is excluded from the list', function () {
+    PopularRoute::factory()->create(['is_active' => false]);
+
+    $this->getJson('/api/v1/popular-routes')
+        ->assertSuccessful()
+        ->assertJsonCount(0, 'data');
+});