Skip to content

Source: README.md. Edit it there; this page is generated at build time.

Reviewly ​

A single-niche affiliate-marketing content site — reviews, comparisons, "best of" listicles, and buying guides — built on Laravel 13 with a Filament v4 admin panel.

See CONTEXT.md for the domain glossary (Product, Brand, Review, Comparison, Listicle, Article, Affiliate Link, Click, etc.) and docs/adr/ for the architecture decisions behind the domain model. The public site's design system lives in design-system/affiliate-review-site/MASTER.md — read it before making UI changes so new work stays consistent. Known small pieces of work that nobody has picked up yet are written down in docs/tickets/.

Stack ​

  • Laravel 13, Filament v4 admin panel at /admin
  • Filament Shield (roles/permissions), TOTP two-factor auth required for the super_admin role
  • spatie/laravel-activitylog, spatie/laravel-medialibrary, spatie/laravel-sitemap
  • Public frontend: Blade + Alpine.js + a Livewire search component, Tailwind CSS v4 via Vite
  • Pest for tests

Local setup ​

PHP version note: if your system's default php/composer are PHP 8.5 without ext-intl, Filament will fail. This project needs PHP 8.4.1+ with ext-intl — 18 locked runtime packages require >=8.4.1, so composer install fails outright on 8.3. If you have multiple PHP versions installed (e.g. via Homebrew), point directly at a compatible one:

bash
/opt/homebrew/opt/php@8.4/bin/php artisan ...
/opt/homebrew/opt/php@8.4/bin/php /usr/local/bin/composer ...

Adjust the path for your own machine, or just use php/composer directly if your default install already has ext-intl.

bash
composer install
cp .env.example .env
php artisan key:generate

npm install
npm run build       # or `npm run dev` to keep Vite watching while you work

php artisan migrate --seed
php artisan storage:link

php artisan serve

Tailwind is compiled at build time by Vite, not scanned live — if you add new utility classes to a Blade file, re-run npm run build (or keep npm run dev running) before checking the browser, or the new classes simply won't exist in the compiled CSS.

Default admin login (local/demo only) ​

Seeding creates one admin account:

email:    admin@example.com
password: password

This user is assigned the super_admin Filament Shield role, so on first login to /admin it will be forced through TOTP authenticator app setup (multiFactorAuthentication is required for super_admin — see app/Providers/Filament/AdminPanelProvider.php). Change or remove this account before any real deployment — it's throwaway seed data, not something to leave live on a production site.

Demo content ​

database/seeders/DemoContentSeeder.php seeds obviously-fake placeholder content (products, reviews, comparisons, listicles, articles, pages, menus) so the public site and admin panel have something to display, including generated placeholder images (database/seeders/Support/PlaceholderImage.php — abstract gradients, no external network calls or stock photography). Don't ship this content to production; it exists purely so a fresh checkout isn't empty.

Running tests ​

bash
php artisan test

Running the browser tests ​

Playwright drives the admin panel in a real browser. First run only:

bash
npm install
npx playwright install chromium

Then:

bash
npm run test:e2e      # headless
npm run test:e2e:ui   # Playwright's interactive UI

The suite is self-contained: it rebuilds a throwaway database/e2e.sqlite, seeds it, and boots its own artisan serve on port 8111 — your .env and database/database.sqlite are never touched. If php on your PATH isn't the version this project runs on, set E2E_PHP:

bash
E2E_PHP=/opt/homebrew/opt/php@8.4/bin/php npm run test:e2e

See tests/e2e/README.md for how the suite is put together.

Regenerating the admin guide ​

docs/admin-guide/README.md documents every admin screen. Its images are captured from the real pages, and the whole thing builds into a single printable manual:

bash
npm run docs:screenshots   # rewrites docs/admin-guide/img/
npm run docs:pdf           # rewrites docs/admin-guide/admin-guide.pdf

The screenshot run is a separate Playwright project, so npm run test:e2e never touches docs/. The PDF build is a plain Node script — it needs no server and no database, only the Markdown and the images already on disk. Run the screenshots first if a screen has changed.

docs/admin-guide/admin-guide.pdf is the file to hand to someone who needs to operate the panel: ~60 A4 pages, every screen explained beside its screenshot, with a numbered contents page and PDF bookmarks.

Browsing the docs as a site ​

Every Markdown doc in the repo, including this README, the ADRs, the admin guide and the tickets, also builds into a searchable VitePress site:

bash
cd website && npm install && npm run docs:dev

website/README.md explains how it's put together.

Releasing to production ​

A release is a vMAJOR.MINOR.PATCH tag on a commit that is on main. Merging to main ships nothing on its own.

Work collects on release/v1: feature PRs target it, and a PR from release/v1 into main is what makes a release. Before tagging, read the release runbook. Its Next release section lists every manual step the tag needs, such as root commands on the box and checks after the deploy. The runbook also covers the branch flow, including why the release PR is merged with a merge commit rather than a squash.

There are two ways to create the tag, and they start the same deploy:

  • From the browser. Go to Releases → Draft a new release. Under Choose a tag, type a new tag such as v1.4.0 and choose Create new tag on publish, with main as the target. Click Generate release notes, then Publish release. Publishing creates the tag, and the tag push starts the deploy.
  • From a terminal. git tag v1.4.0 && git push origin v1.4.0. The workflow then writes the release notes itself once the deploy succeeds.

The Deploy workflow checks that the tag is on main and that CI passed for it, waiting up to 20 minutes if CI is still running. It then deploys on the self-hosted runner and links the run from the repo's production environment. The sequence, and what a failure at each step leaves behind, is in docs/adr/0010. A release published from the browser exists even if its deploy fails, so check the run before announcing it.

To redeploy or roll back, go to Actions → Deploy → Run workflow. In the Use workflow from dropdown, pick a tag, not a branch. The workflow refuses a branch, and so does the runner on the box. Leave rollback unticked to redeploy that tag, or tick it to flip back to the release before the live one (which tag you picked doesn't matter then). If GitHub is down, roll back on the box instead, following deploy/README.md.

Where to see what happened:

WhatWhere
Every deploy run, with logsActions → Deploy
What is live, and its historyRepo home page → Deployments (right sidebar) → production
Release notes per tagReleases

The repo is private, so these pages, like every file in docs/, are visible only to collaborators who are signed in to GitHub.

Production has no demo content ​

The deploy seeds roles and permissions (ShieldSeeder) on every release, and nothing else. It never runs DatabaseSeeder or DemoContentSeeder. Don't run either on production: DatabaseSeeder creates a super_admin with a published password. DemoContentSeeder fills the legal pages with placeholder text (the Affiliate Disclosure reads "Placeholder demo affiliate disclosure text."). It also uses plain create, so it can't be cleanly run twice or undone. To look at the site with content in it, seed a local checkout instead.

A new production database therefore has no menus and no pages. The header and footer menus render empty. The Affiliate Disclosure link is hardcoded into the footer and into every disclosure notice, and it returns a 404 until a page with the slug affiliate-disclosure exists. Before publishing the first review, write that page in the admin, along with About, Contact, Editorial Policy, Privacy Policy and Terms of Use, and build the Header and Footer menus.

A new production database has no users either. Create the first admin on the box, as deploy from /var/www/blog-filament/current:

bash
php artisan make:filament-user
php artisan shield:super-admin --panel=admin

Changing a production setting ​

Production config is .env.production.encrypted, committed to the repo and decrypted on the box at each deploy (docs/adr/0007). Any edit made to shared/.env on the box is overwritten by the next deploy. To change a value, decrypt the file, edit it, re-encrypt it, merge, and release a new tag. ADR 0007 has the exact commands. The key lives on the box and offline, never in GitHub.

The variables beyond Laravel's defaults are documented in .env.example, and a few of them change behaviour:

  • GTM_CONTAINER_ID: enables the GTM snippet and the affiliate-click tracking trigger. If blank, GTM is skipped entirely.
  • NEWSLETTER_FORM_ACTION, NEWSLETTER_EMAIL_FIELD, NEWSLETTER_PROVIDER: the footer signup. If NEWSLETTER_FORM_ACTION is blank, the form isn't rendered. It posts straight to the provider, so there is no API key to keep.
  • AMAZON_CREATORS_*: credentials for price ingestion. See "Switching on merchant price ingestion" below.

Running in production ​

The box itself, meaning nginx, PHP-FPM, the Actions runner and the on-disk layout, is covered in deploy/README.md and ADRs 0008 to 0010.

Scheduler and queue ​

The app uses the database queue driver. On the production box both halves are installed by the deploy itself, from deploy/recipe/runtime.php: one line in the deploy user's crontab runs schedule:run every minute, and a systemd user unit (deploy/systemd/blog-filament-worker.service) keeps one queue:work running and restarts it onto each new release. Neither is configured by hand. docs/adr/0009 explains why each flag is what it is.

Three commands run on the scheduler, all registered in routes/console.php:

CommandScheduleWhat it does
app:publish-scheduled-contentevery minuteFlips scheduled content to published once its time has passed
app:refresh-merchant-priceshourlyQueues price refreshes for affiliate links whose prices are due (see "Switching on merchant price ingestion" below)
model:prunedailyDeletes scheduler run-history older than schedule-monitor.delete_log_items_older_than_days

Whether any of this is actually happening is visible in the admin, at Scheduler in the sidebar. That page depends on schedule-monitor:sync, which the deploy runs after every release goes live (deploy.php). Without it the page has no record to report on, and — this is the trap — an unrecorded task cannot be judged late, so a server where cron was never installed would otherwise show a page with nothing wrong on it.

Price ingestion needs a worker draining the queue. app:refresh-merchant-prices only queues work. With nothing consuming the queue no price is ever refreshed, and because a price that cannot be refreshed is removed once it passes its merchant's TTL, prices degrade to "Check {merchant}" CTAs rather than sitting stale on the page.

Verify structured data (once, after the first published review) ​

Every public page emits a JSON-LD @graph (app/Support/Seo/SchemaBuilder.php). The vocabulary is already verified — validator.schema.org returns 0 errors, 0 warnings for both the Comparison and Listicle graphs, and tests/Feature/SchemaBuilderTest.php and ComparisonListicleBylineTest.php pin the shape on every run.

What that cannot tell you is whether Google will actually grant rich results, because the Rich Results Test only accepts a publicly reachable URL. So it is a post-deploy step, not a local one. Run it once the domain is live, on one URL of each type:

Page typeExpect
A reviewReview with itemReviewed, plus FAQPage if the review has FAQs
A comparisonWebPage carrying the byline, with the ItemList resolved via mainEntity
A listicleAs above, with one ListItem per entry
An article or guideArticle
Any pageBreadcrumbList

Two things worth knowing before you read the output:

  • The ItemList will not appear as a separate item. It is pulled into the WebPage through mainEntity, so a correctly linked graph shows fewer top-level objects, not more. That is the same nesting validator.schema.org reports.
  • Prices are omitted when stale. offers is only emitted for affiliate links whose price is fresh per the merchant's Max price age setting, so a page whose prices have aged out will legitimately show a Product with no offers. That is deliberate, not a markup fault.

Anything the test flags that is not one of those two is worth fixing.

Switching on merchant price ingestion ​

Nothing refreshes prices until an operator opts a merchant in: every Merchant defaults to the Manual price source, meaning its prices are whatever was typed into the admin and ingestion leaves them alone. To switch one on:

  1. Put the AMAZON_CREATORS_* credentials in the production env (see "Changing a production setting" above). They come from Login with Amazon via Associates Central; the partner tag is the marketplace-specific part, the client id and secret are global.
  2. Set the merchant's Price source to Amazon Creators API (Catalog → Merchants → Edit).
  3. Give each of that merchant's affiliate links an ASIN / SKU (Catalog → Products → Edit → Affiliate links). A link with no ASIN is skipped, never cleared.

To run it by hand, or to see what the scheduler would pick up:

bash
php artisan app:refresh-merchant-prices                    # everything due, bounded by pricing.links_per_run
php artisan app:refresh-merchant-prices --merchant=amazon  # one merchant, by slug or id
php artisan app:refresh-merchant-prices --limit=20         # a smaller slice

The admin also has Refresh prices (per merchant) and Refresh price (per affiliate link) actions, which queue the same jobs and ignore the freshness window. Both paths need a queue worker; nothing is fetched inline.

Tuning lives in config/pricing.php. Why the intervals, the ten-ASIN batching and the clear-on-failure behaviour are what they are — and why there is no price history — is in docs/adr/0006-queued-merchant-price-ingestion.md.

License ​

The Laravel framework is open-sourced software licensed under the MIT license.