DEV Community: Nasrul Hazim

One folder shape for every course: a lifecycle monorepo convention

Nasrul Hazim — Wed, 22 Jul 2026 15:46:35 +0000

TL;DR

I merged several training courses into one monorepo and gave every course the same numbered folder shape: 00-planning → 04-post-training.
A _TEMPLATE/ you copy to start the next one, an _ARCHIVED/ you park old stuff in, and a CLAUDE.md that makes the convention machine-readable.
The trick that makes it stick: templates use <angle-bracket-slots>, and "done" is a grep that returns nothing.

I had course material scattered across repos — planning notes here, marketing copy there, facilitator run-sheets in a third place. Every new course started from a blank page, and I re-invented the folder layout each time. So I collapsed everything into one monorepo with a single rule: every course has the identical shape.

The lifecycle, as folders

The insight isn't "use folders" — it's that a course has a lifecycle, and numbered folders make that lifecycle the primary axis instead of file type. Plan it, sell it, teach it, run it, follow up. Five stages, always in order:

Folder	Stage	What lives here
`00-planning/`	Prepare	Syllabus (source of truth), specs
`01-marketing/`	Sell	Positioning master + channel assets
`02-content/`	Teach	Modules, one file each
`03-delivery/`	Run	Run-sheet, pre-flight checklist, fallback plan
`04-post-training/`	Follow up	Feedback form, follow-up email, post-mortem

The numeric prefix isn't decoration. It forces sort order to match the actual workflow, so the folder listing reads like the process itself. Same reason migration files are timestamped — order is information.

<course>/
  00-planning/       -> derives everything below
  01-marketing/
  02-content/
  03-delivery/
  04-post-training/  --. post-mortem findings
                        |
     ^------------------'  feed back into 00..03

That loop at the end matters: the post-mortem doesn't sit in a graveyard folder. Its findings flow back into the syllabus, the run-sheet, the marketing. The structure runs the same feedback loop it's supposed to teach.

`_TEMPLATE/`: a course starts as a copy

Starting a new course is one line:

cp -r _TEMPLATE my-new-course

The template is the full lifecycle skeleton with the writing already stubbed. What you must fill is marked as <angle-bracket-slots> — <course-name>, <promise-one-liner>, and so on. Everything not in a slot is standing structure you keep.

The part I like most is the definition of done. A course is ready when this returns nothing:

grep -rn '<' --include='*.md' .

No slot hits = no unfilled blanks. It turns "is this finished?" from a judgment call into a command with an exit code — the same instinct as a failing test. If I were wiring this into CI, that grep becomes the assertion.

`_ARCHIVED/`: park it, don't delete it

Retired formats and old campaigns go into _ARCHIVED/, in dated subfolders with a note on why it was retired and what replaced it. One rule keeps it honest: nothing live may reference anything in there. If a live file still links to it, it isn't archived — it's just moved.

Why keep it at all? Because a retired price, a killed campaign style, or an abandoned format is a recorded decision. Deleting it loses the "we already tried that, here's why it didn't work." Git history technically has it, but nobody spelunks reflog for a pricing decision.

`CLAUDE.md`: the convention, machine-readable

The last piece is a CLAUDE.md at the root that spells out the layout, the naming rules, and the standing decisions. It's written for an AI coding agent, but the real value is broader: it's the one file where the convention lives as text instead of as tribal knowledge in my head. Any collaborator — human or agent — reads one file and knows where things go.

The takeaway

The pattern generalizes past courses. Any repeatable body of work with a lifecycle — client engagements, product launches, incident write-ups — benefits from the same three moves: one fixed shape, a copy-to-start template with a grep-checkable done state, and a parking lot for retired decisions. Consistency you can grep beats consistency you have to remember.

Stop Screenshotting Architecture Diagrams: Build Them as Single-File HTML

Nasrul Hazim — Wed, 22 Jul 2026 15:24:38 +0000

TL;DR

Spent today rebuilding two training diagrams — a layered reference architecture and a workflow swimlane — as single-file HTML instead of exported images.
The trick: data in a plain JS array, layout in CSS Grid, connectors in an SVG overlay measured at runtime.
Result: diagrams you can step through, click into, and hand over as one file that opens offline.

Why not just export a PNG?

Because a screenshot is stale by the next sprint, and nobody re-opens the drawing tool to fix it.

Approach	Editable by a dev	Interactive	Portable
PNG from a drawing tool	No (need the source file)	No	Yes
Mermaid in a doc	Yes	No	Needs a renderer
Hand-built HTML	Yes (it's a data array)	Yes	One file, opens anywhere

The third option costs a few hours once. After that, updating a component is editing one object in an array.

Separate the data from the drawing

This is the whole design. Nothing about position, colour, or DOM lives in the content:

const TIERS = [
  { key: 'clients', label: 'Clients', sub: 'consumers · admins' },
  { key: 'edge',    label: 'Edge',    sub: 'TLS · load balancing' },
  // ...
];

const COMPONENTS = [
  { id: 'app', tier: 'app', x: .34, label: 'Control Plane', tech: 'PHP-FPM',
    role: 'Governance UI and sync orchestration.',
    points: [{ type: 'info', text: 'Pushes approved config downstream' }] },
  // ...
];

const LINKS = [['consumers', 'edge'], ['edge', 'gateway'], /* ... */];

tier picks the row. x is a fraction (0..1) across that row, not a pixel. So the layout survives any viewport without me hand-tuning coordinates.

Layout: Grid for the boxes, SVG on top for the wires

  +--------------------------------------------------+
  | lane label |  [card 1]   [card 2]   [card 3]      |  <- CSS Grid row
  |------------+-------------------------------------|
  | lane label |       [card 4]      [card 5]         |
  +--------------------------------------------------+
        ^                    ^
   sticky column      SVG overlay (position:absolute; inset:0)
                      draws paths between measured centres

CSS Grid does the honest work:

grid.style.gridTemplateColumns = `186px repeat(${steps.length}, 178px)`;
grid.style.gridTemplateRows = `repeat(${LANES.length}, 1fr)`;

Then measure the rendered cards and draw connectors into the overlay:

function centre(el) {
  const r = el.getBoundingClientRect(), base = board.getBoundingClientRect();
  return { x: r.left - base.left + r.width / 2, y: r.top - base.top + r.height / 2 };
}

Measure after paint (requestAnimationFrame), and re-measure on resize or when a side drawer opens — otherwise your wires point at where the boxes used to be. That was the one bug that cost me real time.

The bit learners actually respond to

A dot that travels along the flow as you step through it. No library, ~10 lines:

function moveToken(from, to) {
  const a = centres[from], b = centres[to], t0 = performance.now(), dur = 650;
  (function tick(now) {
    const p = Math.min((now - t0) / dur, 1);
    const e = p < .5 ? 2 * p * p : 1 - Math.pow(-2 * p + 2, 2) / 2; // easeInOutQuad
    token.style.left = (a.x + (b.x - a.x) * e - 6) + 'px';
    token.style.top  = (a.y + (b.y - a.y) * e - 6) + 'px';
    if (p < 1) requestAnimationFrame(tick);
  })(performance.now());
}

It's cosmetic, and it's the thing that makes a request's journey land in a room. Movement encodes causality better than an arrow does.

Trade-offs, honestly

Win	Cost
One file, no build step, opens offline	You hand-write the layout logic
Content is a data array anyone can edit	No auto-layout — you place things
Full control of interaction	Accessibility is on you (add keyboard nav)

If your diagram is throwaway, use Mermaid. If it's going to be taught from repeatedly and evolve with the system, the data-driven HTML pays for itself fast.

Extracting the shell into a reusable template so a new diagram is just a new data file. That's the real deliverable — not the diagram, the mould it came out of.

Ebook Reviewer Wanted: Help Me Find What's Gone Stale

Nasrul Hazim — Wed, 22 Jul 2026 03:41:53 +0000

Technical books have a shelf life that nobody prints on the cover.

A cookbook from 2018 still works. A history book from 2018 still works. A Laravel book from 2018 will teach you a middleware pattern that was replaced twice, recommend a package whose maintainer archived it, and show you a test suite in a syntax that no longer runs.

I've written a series of ebooks on PHP, OOP, SOLID, design patterns, Laravel conventions, testing with Pest, application architecture, and AI-assisted development. There are also two aimed at kids learning to code. Every one of them was correct when I wrote it. That is a much weaker claim than "correct now," and I'd rather find the gap myself than have a reader find it for me.

So: I'm opening the series to technical reviewers before the final edition ships. Applications close Sunday, 26 July.

Why I can't do this alone

Not because I lack the time. Because I lack the distance.

When you write a technical book, you build a mental model of the reader and then you write to that model for months. The model is always partly wrong, and you are the last person who can see how. You skip a step because it's obvious to you. You keep an example that made sense when you drafted the chapter and no longer matches the surrounding code. You cite a package because it was the right answer for a project you shipped two years ago, and you never checked whether it's still maintained.

None of this shows up on a reread. Rereading your own work is mostly pattern-matching against your own memory. You see what you meant, not what you wrote.

A reviewer who has never seen the manuscript reads what's actually on the page. That's the whole value, and it's not something more effort on my side can substitute for.

What the job actually is

You pick one book from the series. You read it properly — not skim it — and you flag what's broken.

Four things in particular:

Things that are outdated. The framework moved, the syntax changed, there's now a cleaner way to do the same thing. The advice isn't wrong exactly, it's just from an older world.

Things that are wrong. The code sample doesn't run. The explanation misstates how something works. This is the highest-value category and the one I most want to hear about.

Things that are abandoned. A package I recommended hasn't seen a commit in three years. A tool I told you to install no longer exists.

Things that are unclear. You read a section twice and still didn't follow it. That's not your failure, it's mine, and I need to know which sections do it.

You don't need to fix anything. Pointing is enough.

The feedback format

This is the part that's worth stealing even if you never apply.

Most book feedback arrives as prose: "Really enjoyed chapter 4, though I wondered about the routing bit." That's pleasant and almost impossible to act on. I don't know which page, what specifically, or what you'd rather see.

So reviewers use four columns. One row per issue.

Chapter / Page	Status	What's wrong	What you'd do instead
Ch. 4, p. 61	Outdated	`Route::resource` example uses Laravel 8 style	Show scoped route binding
Ch. 7, p. 118	Broken	Code sample fails — missing import for `expect()`	Add `use function Pest\Laravel\get;`
Ch. 2, p. 24	Unclear	Interface explanation stays abstract throughout	Replace with a payment gateway example

Three things this does that prose doesn't.

It forces specificity. You can't write a row without naming a location, so vague impressions get filtered out before they reach me.

It separates severity from opinion. "Outdated" and "Broken" are different problems with different urgency. A prose paragraph blends them together and I have to guess which is which.

It converts directly into work. A filled-in sheet is already a to-fix list. I sort by status, work top to bottom, and reply to each row. Nothing gets lost in a thread.

If you ever run a review process — for docs, a spec, a design, a codebase — some version of this table will serve you better than asking for thoughts.

Who I'm looking for

Anyone who writes code. That's the entire filter.

Seniority helps for some books and actively hurts for others. If you're three months into PHP and a chapter loses you, that's the single most useful signal I can get — I wrote it for you, and it didn't land. A senior engineer will read straight past the same gap because they can fill it from experience without noticing they're doing it.

The one thing I do need is bluntness. If a chapter is weak, I need you to write "this chapter is weak" rather than "this chapter has potential." I'm not sentimental about any of it. If a section should be cut entirely, say so and I'll cut it.

Reviewers who tell me it's all great are, with respect, not useful to me.

What you get

The full series. Not just the book you review — all of it, free, permanently.

Your name in the acknowledgements. Printed in every copy of the new edition, under whatever handle you choose.

Let me be honest about the exchange: reading a technical book carefully takes somewhere between four and eight hours depending on which one you pick. What I think does cover it is early access to the whole series, a permanent credit, and — if you're the kind of person who enjoys this — a few hours of deliberate close reading in your own field, which is not the worst way to spend a weekend.

Timeline


26 July	Applications close
2 August	Reviewers selected and books assigned
3 – 24 August	Review window
Late August	Final edition ships

Three weeks for the review itself. You can break it up however you like — nobody expects a single sitting.

Applying

The form takes about a minute. You'll pick which book you want, tell me roughly where your experience sits, and give me the handle you want in the acknowledgements.

👉 Apply Now

Applications close Sunday, 26 July.

Dev Log: 2026-07-19

Nasrul Hazim — Mon, 20 Jul 2026 01:54:59 +0000

TL;DR

Shipped an email broadcast module: audience filtering, suppression, queued per-recipient sends, delivery tracking.
Fixed a silent implicit-route-binding bug — the route param name didn't match the method parameter, so Laravel injected an empty model.
Lesson of the day: Laravel's implicit binding fails quietly, not loudly.

Email broadcasts

The bulk of today. A campaign resolves an audience filter into a contact query, passes it through a suppression gate (unsubscribed, do-not-contact, no email), materialises one recipient row per contact, then dispatches one queued job per row.

The design principle: the recipient row is the source of truth. Every job re-checks the row's status before sending, so a retry or a double dispatch is a no-op. No locks, no dedupe table.

Delivery webhooks sync back onto the same rows with a rank guard (sent < delivered < opened < clicked) so an out-of-order event never walks a status backwards. Terminal states — bounced, unsubscribed, failed — are handled separately.

Full write-up in the focused post.

The route binding bug that says nothing

A show page blew up with Call to a member function label() on null. The cause was two names that had drifted apart:

	Before	After
Route param	`{infraProvider}`	`{provider}`
Mount signature	`mount(InfraProvider $provider)`	`mount(InfraProvider $provider)`
Result	empty model injected	correct model

// route
Route::get('/{provider}', ProviderShow::class)->name('show');

// component
public function mount(InfraProvider $provider): void { /* ... */ }

Here's the part worth remembering: Laravel matches implicit route-model bindings by name. The URI segment {infraProvider} has to match the variable $provider. When it doesn't, you don't get an exception — you get a freshly instantiated, empty model. id is 0, every attribute is null, and the failure surfaces three layers later when something calls a method on a null enum.

It's a latent bug. The page had never been opened with real data before, so nothing had noticed. Seeding the first record surfaced it immediately.

The fix was renaming the param to match the sibling resource routes ({project}, {team}). Consistency across a route file is the cheap defence here — if every route uses the singular model name, the mismatch never happens.

it('resolves the provider on the show route', function () {
    $provider = InfraProvider::factory()->create();

    get(route('providers.show', $provider))
        ->assertOk()
        ->assertSee($provider->name);
});

One test hitting the real route would have caught it. Testing the component in isolation would not — the binding only happens when the router does the work.

Seeding as a smoke test

The other commit was an idempotent, config-driven seeder that provisions a realistic baseline environment rather than dummy rows. It earned its keep the same afternoon — it produced the first real record on a page nobody had exercised, which is how the binding bug surfaced. A good seeder is a smoke test that leaves useful data behind.

Takeaway

Failures that return a valid-looking empty object are worse than exceptions. Convention — matching names, consistent route params — is what keeps them from happening in the first place.

Building an Email Broadcast Engine That Survives Retries

Nasrul Hazim — Mon, 20 Jul 2026 01:53:51 +0000

TL;DR

Shipped an email broadcast feature: audience filter → suppression gate → one queued job per recipient → per-recipient status ledger.
The whole design rests on one idea: the recipient row is the source of truth, so retries and double dispatches are harmless.
Delivery webhooks sync back onto that ledger with a rank guard so a late event never downgrades a status.

The shape of it

Sending one email is easy. Sending 5,000 and being able to answer "what happened to contact #4127?" is the actual problem.

  Campaign (draft)
      |
      v
  Audience filter  ->  Suppression gate  ->  CampaignRecipient rows (pending)
                                                    |
                                              dispatch 1 job each
                                                    v
                                              SendCampaignEmail
                                                    |
                                        mail sent -> status: sent
                                                    |
                       webhook: delivered / opened / clicked / bounced
                                                    v
                                          recipient ledger updated

One job per recipient, not one job per campaign. A 5,000-recipient blast becomes 5,000 small units of work — the queue throttles naturally, and a failure blast-radius is one email, not the whole campaign.

The suppression gate

Audience filtering and eligibility are two different questions, and mixing them is how you email someone who unsubscribed last week.

Query	Includes	Used for
`baseQuery()`	matches the filter	preview counts in the UI
`eligibleQuery()`	filter + reachable	the actual send

public function eligibleQuery(array $audience): Builder
{
    return $this->baseQuery($audience)->emailReachable();
}

emailReachable() is a scope on the contact model — not do-not-contact, still subscribed, has an email. One scope, one place to change the rules, impossible to forget at the call site.

Idempotency lives in the row

The job takes IDs, not models, and every send re-checks the recipient's status before doing anything:

class SendCampaignEmail implements ShouldQueue
{
    public int $tries = 3;
    public int $backoff = 30;

    public function __construct(
        public readonly int $recipientId,
        public readonly int $tenantId,
    ) {}

    // ...
}

If the queue redelivers, the status guard makes the second attempt a no-op. That's the whole trick — no distributed lock, no dedupe table, just a state machine on a row you already have.

The failed() hook matters just as much. Without it, a recipient stuck in pending after retries are exhausted leaves the campaign hanging in sending forever. Mark it failed, recompute stats, let the campaign finish.

Never downgrade a status

Delivery webhooks arrive out of order. A delivered event landing after opened should not walk the status backwards.

private const RANK = [
    'sent' => 1, 'delivered' => 2, 'opened' => 3, 'clicked' => 4,
];

Monotonic progression, terminal off-ramps (bounced, unsubscribed, failed) handled separately. Two enums carry the vocabulary — one for the campaign lifecycle, one for the per-recipient state, both with label(), color() and description() so the UI never hardcodes a string.

Unsubscribe is a public route

The tokenised opt-out link has no auth, so it always renders the same generic confirmation — valid token or not. Otherwise you've built an oracle that tells an attacker which tokens exist.

The opt-out also back-fills any still-pending recipient rows to unsubscribed, so reports stay honest instead of counting a send that will never happen.

it('suppresses pending recipients when a contact unsubscribes', function () {
    $recipient = pendingRecipient();

    $recipient->contact->unsubscribeFromEmail('via link');

    expect($recipient->fresh()->status)
        ->toBe(CampaignRecipientStatus::UNSUBSCRIBED);
});

Takeaway

Broadcast systems get complicated because people try to make the sending reliable. Make the ledger reliable instead, keep every job small and re-runnable, and reliability falls out for free.

Your Seeder Should Describe a Shape, Not Your Laptop

Nasrul Hazim — Mon, 20 Jul 2026 01:53:39 +0000

TL;DR

Rewrote a bootstrap seeder so the deployment stack — DB engine, queue runner, PHP version — is config, not hardcoded.
Renamed it away from a phase-based name (MvpSeeder). If a class name describes when you wrote it, it expires.
Trimmed a CI matrix from three PHP versions to one. Matrix breadth should match what you actually deploy.

The seeder that only worked for me

Bootstrap seeders rot predictably. Version one seeds exactly the environment the author had open at the time: one database engine, one queue setup, one PHP version. It works, so nobody touches it. Six months later someone needs Postgres and discovers the choice was never a choice.

I hit that on a control-plane app — the thing that describes and provisions deployments. Its seeder encoded a single stack shape, so I pulled the variable parts into config.

'control_plane' => [
    'default_blueprint' => 'stack-laravel',   // or -ha, -single-node
    'database'    => env('CONTROL_PLANE_DB', 'mysql'),      // mysql | postgresql
    'queue'       => env('CONTROL_PLANE_QUEUE', 'horizon'), // horizon | default
    'php_version' => env('CONTROL_PLANE_PHP', '8.4'),

    'apps' => [
        // each entry may override blueprint / queue per app
    ],
],

Knob	Options	Default from
Blueprint	single-node, standard, HA	config
Database	MySQL, PostgreSQL	env
Queue runner	Horizon, plain `queue:work`	env
PHP runtime	8.3 – 8.5	env

Two rules kept it tidy. Every knob has a sane default, so a fresh clone still seeds without a populated .env. And every knob is overridable per app — the moment you have more than one workload, one will be the exception.

   config/seeder.php
        |
        v
   PrepareSeeder  ---->  ControlPlaneSeeder
                              |
                +-------------+-------------+
                v             v             v
           blueprint       database      queue runner
        (single/std/ha)  (mysql/pgsql)  (horizon/default)
                \             |             /
                 +-----> Workload + Deployment

Horizon or not is a real fork

Both options run under supervisord, but they're different operational bargains:

	Horizon	Plain `queue:work`
Dashboard	Yes	No
Auto-balancing across queues	Yes	Manual worker counts
Extra dependency	Redis required	Any queue driver
Config surface	`config/horizon.php`	Supervisor program blocks

Horizon is the better default for real queue load. But a single-node app running three jobs a day doesn't need Redis in the stack just for a dashboard nobody opens. Per-app key means neither choice forks the codebase.

Rename anything named after a phase

The seeder used to be MvpSeeder. It's now ControlPlaneSeeder.

MvpSeeder answers "when was this written". ControlPlaneSeeder answers "what does this do". The first stops being interesting the moment the MVP ships; the second stays true for the life of the class. Same for NewUserService, V2Controller, TempJob — timestamps pretending to be names.

While I was in there: the CI matrix

Related cleanup elsewhere. A test workflow was running PHP 8.3, 8.4 and 8.5. Trimmed to 8.5.

Matrix breadth should match your deployment surface. A published package genuinely needs to prove it works across versions — its users pick the runtime, not you. An application you deploy yourself runs exactly one PHP version, and testing two others buys nothing but Actions minutes.

Project type	Matrix
Published package	Every supported PHP/framework combo
Deployed application	The version you actually deploy

Also removed a duplicate workflow running the same suite twice per push. Free 50% cut, which is the best kind.

Test the knobs

Seeders are worth a test the moment they encode decisions rather than fixtures:

it('seeds the queue runner from config', function () {
    config(['seeder.control_plane.queue' => 'default']);

    $this->seed(ControlPlaneSeeder::class);

    expect(Deployment::first()->queue_runner)->toBe('default');
});

Without it, "the config knob works" is an assumption that holds until the one time you actually flip it — usually on a fresh server at an inconvenient hour.

Takeaway

A seeder is documentation that executes. If it says "this system runs MySQL with Horizon on PHP 8.4", it should be describing a default, not a constraint. Push the specifics to config, keep the shape in the class, and give every knob a default that works out of the box.

The differentiator test: if a rival can copy the claim, it isn't one

Nasrul Hazim — Thu, 16 Jul 2026 16:04:14 +0000

TL;DR

I rewrote a product's differentiators after noticing four of five were claims any competitor could paste onto their own page word-for-word.
The test: could a rival put this exact sentence on their site and have it be just as true? If yes, it's a category description, not a difference.
Keep only claims rooted in how the thing was built — structural facts a rival can't retrofit.
Same discipline for diagrams: if the reader has to decode it, redraw it so it states the argument literally.

The problem with a "differentiators" section

I was reworking a product landing page and stared at the differentiators block. Five confident claims. Then I ran each through one question: could a competitor put this exact sentence on their own page?

Claim	Rival can copy it?
On-prem, sovereign, your infrastructure	Yes
One line of accountability, one throat to choke	Yes
Governance-first architecture	Yes
Adopt at your pace, grows with you	Yes
Priced per deployment, not per seat	No

Four of five failed. Not because they're untrue — because they describe the category, not the product. Every serious vendor in the space says "governance-first" and "sovereign." A claim your rival can echo verbatim isn't a differentiator; it's table stakes wearing a badge.

Keep only what's structural

The fix isn't better adjectives. It's finding claims that come from how the thing was actually built — facts a competitor would have to rebuild their company to match. What survived:

Designed as one, not assembled from acquisitions. Most enterprise suites are bolted together from bought products, each with its own data model and directory, and seams nobody removes. "Built by one team as one system" is checkable and structural — you can't retrofit the absence of acquisitions.
The whole suite runs inside your perimeter. Sharpened from generic "on-prem" to "air-gappable in full" — not one self-hostable module while the rest phones home.
Products that stand on their own. Several products built inside the suite ship live under their own brands. That's proof, not a promise — and it answers the lock-in fear without having to name it.
Priced per deployment. The one that already passed.

The pattern: a good differentiator is a fact about your construction, phrased so a reader can check it. If it's an adjective anyone can claim, cut it.

Make the diagram say it out loud

Same day, same lesson on the visuals. Two diagrams were technically correct and practically useless.

One was drawn as a funnel — but the content was a sequence (order flowing through stages), not a filter narrowing down. Readers auto-read "funnel" as "we lose people at each step." Relabeled and redrawn to show order, not attrition.

The other was a balance scale (dacing) meant to convey per-deployment pricing. Too abstract — you had to stare to work out what it argued. I replaced it with a cost-vs-headcount line chart:

cost │              ╱ per seat (rises with headcount)
     │           ╱
     │        ╱
     │─────────────────── per deployment (flat)
     └───────────────────────────► users

The flat line and the crossover state the argument literally: the same fee whether ten people use it or ten thousand. No decoding required.

Takeaway

Two versions of one rule. For copy: if a rival can say it too, it isn't a differentiator — keep only the structural, checkable claims. For diagrams: if the reader has to decode the metaphor, it's failing — redraw until the shape is the argument. Both come down to the same thing: say the true, specific thing, and let it stand without decoration.

Dev Log: 2026-07-16

Nasrul Hazim — Thu, 16 Jul 2026 16:02:14 +0000

TL;DR

Rewrote a product's landing-page differentiators to only keep claims a rival can't copy — its own post today.
Made two server installers genuinely end-to-end and resumable, and taught them to probe SSH before doing any work.
Handled a Cloudflare-proxied origin so the installer talks to the real box, not the edge.
Fixed a Laravel cache config to use CACHE_STORE, and documented Redis ACL (username + password) auth.

Differentiators a rival can't copy

Most of a landing page's "differentiators" turned out to be claims any competitor could paste verbatim. I rewrote them to keep only structural, checkable facts, and redrew two diagrams to state their argument literally instead of hiding it in a metaphor. Full write-up in its own post today — the short version: if a rival can say it too, it isn't a differentiator.

Installers that survive being run twice

Spent the evening on provisioning scripts for a fresh server (a dedicated analytics database plus an API deploy). Two lessons worth keeping.

Resumable beats "run once, pray." An installer that dies halfway and leaves you with a half-built box is worse than no installer. The fix is to make every step idempotent — check whether the thing already exists before creating it — so re-running picks up where it left off instead of tripping over its own earlier work.

Probe before you provision. The script now checks SSH connectivity up front, before it starts changing anything. Failing fast on "I can't even reach this host" is far kinder than failing on step 14 with a half-configured server.

The Cloudflare-proxied origin trap

The API host sat behind a Cloudflare proxy, so the name resolved to Cloudflare's edge, not the origin box. An installer that SSHes to "the domain" ends up talking to the wrong thing entirely. Lesson: when a host is proxied, the deploy path needs the real origin address, not the public DNS name. Obvious in hindsight, a confusing 20 minutes in the moment.

Laravel: CACHE_STORE and Redis ACL

Small but worth noting. Laravel renamed the cache env var to CACHE_STORE (from the older CACHE_DRIVER); a config was still keyed off the old name, so the intended store wasn't being picked. Fixed the reference and documented the Redis setup alongside it — modern Redis supports ACLs, so auth is a username and password pair, not just a password. If you've only ever set REDIS_PASSWORD, that's the bit that bites you when the server enforces ACLs.

That's the day: sharper positioning copy, tougher install scripts, and two config gotchas documented so future-me doesn't rediscover them.

Dev Log: 2026-07-15

Nasrul Hazim — Thu, 16 Jul 2026 16:01:44 +0000

TL;DR

Shipped account suspension across two Laravel apps — an enum, a middleware, a policy check (own post).
Fixed a reverse-proxy gotcha: the proxy hid the gateway's real status behind NGINX's built-in 405.
Moved a DB transaction to wrap only the business write, so a rollback stops erasing the audit trail.
Added two agent (MCP) tools: read the source-of-truth record directly, and resolve a username to its owner.

Account suspension without deleting the user

Two apps needed the same thing: block a user from signing in without deleting the account. Same shape in both — an enum for the status, a middleware that rejects a suspended session mid-flight, and an admin toggle behind a policy. Its own post today, because the interesting part is the edge cases, not the toggle.

The NGINX 405 that lied

A reverse proxy sits in front of an API gateway. GET worked; anything non-GET came back as a flat 405 Method Not Allowed — but that 405 was NGINX's own, not the gateway's. The proxy was answering for a backend it should have forwarded to. The trap: a limit_except GET (or a stray error_page 405) makes NGINX intercept the method itself instead of passing it through.

	Before	After
POST/PUT reaches gateway	No — NGINX returns its own 405	Yes — forwarded
Status the client sees	NGINX built-in 405	The gateway's real status
Debuggability	"why is everything 405?"	Real upstream errors surface

Lesson: a proxy forwards; it shouldn't have opinions about methods. See a generic 405 on writes? Check the proxy before you blame the backend. I documented it in the config header so the next deploy doesn't reintroduce it.

Scope the transaction around the business write only

Subtle one. An operation did a business write and an audit write inside the same DB::transaction. Looks tidy. But when the business write failed and rolled back, the audit row rolled back with it — the one record meant to survive a failure vanished exactly when you needed it.

// before: audit dies with the thing it was supposed to witness
DB::transaction(function () {
    $this->applyChange($record);   // may throw
    $this->audit->log('change', $record); // rolled back too
});

// after: transaction guards the business write; audit is logged around it
$this->audit->log('change.attempt', $record);
DB::transaction(fn () => $this->applyChange($record));
$this->audit->log('change.done', $record);

Rule of thumb: an audit trail records attempts and outcomes — so it can't live inside the transaction whose failure it's meant to explain.

Two read-only agent tools

Also added two MCP tools over an internal system: one reads the source-of-truth record directly, one resolves a username to its owner across every source it might live in. Both read-only. Treating MCP tools as narrow, read-only lenses — rather than write endpoints — keeps them safe to hand an agent and easy to test.

That's the day: one security feature, one infra gotcha, one durability fix, two agent lenses.

Suspend a user in Laravel without deleting them

Nasrul Hazim — Thu, 16 Jul 2026 16:01:42 +0000

TL;DR

Suspension is not deletion: keep the row, block the sign-in.
Model it as a status enum, enforce it with middleware on every authenticated request, gate the toggle with a policy.
The bugs live in the edges: an already-authenticated session, and an admin suspending themselves.

I needed the same feature in two apps: an admin should be able to suspend a user — block them from signing in — without deleting the account. Soft-deleting is wrong here (it hides the record and cascades relationships); a boolean is_active is too thin once you want a reason or a timestamp. Here's the shape I landed on.

1. Model the state, not a flag

A nullable suspended_at timestamp carries more than a boolean — it tells you when, which you'll want for the audit trail and for the "suspended 3 days ago" UI.

// migration
$table->timestamp('suspended_at')->nullable();

// User.php
public function isSuspended(): bool
{
    return $this->suspended_at !== null;
}

public function suspend(): void
{
    $this->forceFill(['suspended_at' => now()])->save();
}

public function reinstate(): void
{
    $this->forceFill(['suspended_at' => null])->save();
}

If you already lean on an enum for user status (UserStatus::Active, UserStatus::Suspended) with label() and color(), derive the badge from that — but keep the timestamp as the source of truth so you don't lose when.

2. Enforce on every request, not just at login

The obvious spot is the login flow. But that only stops new sign-ins — a user suspended while already logged in keeps their session. So the check belongs in middleware on authenticated routes, not just the auth attempt.

class EnsureUserIsNotSuspended
{
    public function handle(Request $request, Closure $next): Response
    {
        if ($request->user()?->isSuspended()) {
            Auth::guard('web')->logout();
            $request->session()->invalidate();
            $request->session()->regenerateToken();

            return redirect()->route('login')
                ->withErrors(['email' => 'Your account has been suspended.']);
        }

        return $next($request);
    }
}

Register it in the authenticated group so it runs on the very next request after suspension — the session dies mid-flight, not at some future login.

3. Gate the toggle with a policy — including "not yourself"

Two rules: only an admin may suspend, and nobody suspends themselves (an admin locking themselves out is a support ticket waiting to happen).

public function suspend(User $actor, User $target): bool
{
    return $actor->isAdmin() && $actor->isNot($target);
}

$actor->isNot($target) is the whole edge case in one line — it's the bug you'd otherwise find in production.

4. Test the edges, not the happy path

The happy path barely needs a test. The edges do: a live session getting kicked, and self-suspension being refused.

it('kicks a user whose account is suspended mid-session', function () {
    $user = User::factory()->create();

    $this->actingAs($user)->get('/dashboard')->assertOk();

    $user->suspend();

    $this->get('/dashboard')->assertRedirect('/login');
    $this->assertGuest();
});

it('forbids an admin from suspending themselves', function () {
    $admin = User::factory()->admin()->create();

    expect($admin->can('suspend', $admin))->toBeFalse();
});

Takeaway

Suspension is three small pieces — a timestamp, a middleware, a policy — and one insight: enforce it on every request, because the user you most want to stop might already be inside. Model the state richly enough to answer "when?", gate the action so an admin can't lock themselves out, and let the tests live where the bugs do.

Dev Log: 2026-07-14

Nasrul Hazim — Wed, 15 Jul 2026 02:36:18 +0000

TL;DR

Fast-forwarded two Laravel apps off an old in-house skeleton — in layers, not one heroic merge.
Added a security-header middleware and a retention purge command whose guard rails are the real feature.
Built a reconciler for queued jobs that never ran (own post).
Shipped a 404 page and a QR-code redirect on the company website.

Fast-forwarding an app off an old skeleton

Both product apps were generated from an in-house skeleton (auth, roles, menus, audit). One had drifted ~30 minor versions behind. A skeleton is a starting point, not a dependency — once you generate from it, upstream fixes don't flow to you.

What made it tractable: layers, as separate commits.

Layer	What goes in	Risk
1. Packages	New composer packages, nothing wired	Low
2. Assets + docs	Icons, vendor assets, feature docs	Low
3. Config + env	Config files, `.env.example`, access control	Medium
4. Infrastructure	Queue/Horizon config, static pages	Medium
5. Wiring	Providers, middleware, menus	High
6. Cheap wins	Trusted proxies, UUID column on audits	Low

Each layer reverts independently. Compare that to one 68-file commit where the only rollback is "undo everything."

Underrated cheap win in there: a UUID column on the audit table. Auto-increment internally, UUID for anything leaving the system. Retrofitting that after other systems reference audit rows by integer id is far more painful.

Security headers, default-on

Nothing exotic here — the value is that it's a default, not a per-route decision:

$response->headers->set('X-Content-Type-Options', 'nosniff');
$response->headers->set('X-Frame-Options', 'DENY');
$response->headers->set('Referrer-Policy', 'strict-origin-when-cross-origin');
$response->headers->set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');

if (app()->environment('production')) {
    $response->headers->set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
}
// ...CSP, when enabled

One nuance worth stealing: CSP on in production, off locally. Vite's dev server and HMR trip over a strict policy, and an always-on CSP just teaches the team to disable it. Sensible default, env flag to override.

Retention purge: the guard rails are the feature

The data:purge command is boring — delete where created_at < cutoff. What matters is what it refuses to do.

Guard	Why
Retention from config, not hard-coded	A hard-coded `365` shreds years of history every night
Refuses the append-only audit trail	CRUD diffs are prunable; the governance log is not
`--dry-run`	Never point a delete loop at production blind

Two audit concepts, two lifetimes. A framework CRUD-diff table ("field X went A → B") is operational data — prune it. An append-only domain audit log is the record. Encoding that as an early return is cheaper than remembering it at 2am.

Reconciler for jobs that never ran

Rows stuck pending forever, nothing in failed_jobs — the job was dispatched once at creation and that dispatch got lost. Retries can't save a job that never entered the queue; a scheduled sweeper over stale, unclaimed rows can. That got its own post ("The Reconciler Pattern").

Bonus lesson: I registered the sweeper's cron from a deploy step, then reverted it an hour later. Deploy-time schedule seeding is convenient until a rollback re-registers a schedule you deliberately removed.

Website: a 404 and a redirect

On the public company website: a real 404 page, plus /company-profile — the URL printed on a QR code — redirecting to the profile document.

const url = import.meta.env.VITE_COMPANY_PROFILE_URL;

// External URL → full page navigation; <Navigate> only does in-app routes.
// Env unset → fall back home rather than dead-end a printed URL.
if (!url) return <Navigate to="/" replace />;

The fallback is the point. Any URL living outside your codebase — QR code, email footer, business card — is a permanent public API. Treat it like one.

Takeaway

Accidental theme: defaults and fallbacks. Layered upgrades so rollback is cheap. Headers on by default. A purge that refuses the dangerous table. A redirect that never dead-ends. Not clever — just the stuff that prevents a 2am page.

The Reconciler Pattern: When a Queued Job Simply Never Runs

Nasrul Hazim — Wed, 15 Jul 2026 02:36:00 +0000

TL;DR

A job dispatched once, at row-creation time, has a silent failure mode: if that dispatch is lost, the row sits pending forever — and never appears in failed_jobs.
Retries only exist for jobs that ran. A job that never entered the queue has nothing to retry.
Fix: a reconciler — a scheduled sweep for stale, unclaimed rows that re-dispatches them. The database is the source of truth; the queue is just delivery.

The bug that leaves no trace

Records stuck in pending. No error, no failed job, no log line. The shape of the code:

$status = SyncStatus::create([...]);   // sync_status = 'pending'
ProcessSyncStatus::dispatch($status->id);

One dispatch, at creation. Fine 99% of the time. The 1%:

What happened	Where the job went	What you see
`queue:clear` during an incident	Payload deleted	Stuck `pending`, no error
No worker running at dispatch	Flushed	Stuck `pending`, no error
Redeploy dropped the connection mid-enqueue	Never enqueued	Stuck `pending`, no error
Job ran and threw	`failed_jobs`	An error you can act on

Only the last row is visible. The first three are invisible failures — dashboards green, data quietly rotting.

The bad mental model: "the queue is durable, so a dispatched job will eventually run." Your database row is the durable thing. The queue is a delivery hint.

Retry ≠ reconcile

	Retry	Reconcile
Triggered by	A job that ran and failed	A state that looks wrong
Source of truth	The queue / `failed_jobs`	The database
Catches lost dispatches?	No	Yes

Retry is a queue-level mechanism. Reconciliation is a domain-level one. You need both.

The reconciler

Periodically ask the database "does anything look stuck?", and fix it.

  every 15 min
       |
       v
+----------------------------+
|  sweep pending rows        |
|  updated_at < now()-15m    |  <- stale
|  AND claimed_at IS NULL    |  <- never picked up by a worker
+----------------------------+
       | touch(row)   <- so the next tick won't sweep it again
       v
   re-dispatch ProcessSyncStatus

Two predicates carry the weight. Stale: updated_at older than a threshold — fresh pending rows are just working, give the queue time. Unclaimed: the job stamps the row the moment a worker picks it up, so a pending-and-claimed row is in flight right now; leave it alone. Pending and unclaimed after 15 minutes was never delivered.

final class ReconcilePendingSync extends Command
{
    protected $signature = 'sync:reconcile-pending
                            {--minutes=15 : Only sweep rows untouched this long}
                            {--limit=200  : Cap re-dispatches per run}
                            {--dry-run}';

    public function handle(): int
    {
        $rows = SyncStatus::query()
            ->where('sync_status', 'pending')
            ->whereNull('claimed_at')
            ->where('updated_at', '<', now()->subMinutes((int) $this->option('minutes')))
            ->limit((int) $this->option('limit'))
            ->get();

        foreach ($rows as $row) {
            if ($this->option('dry-run')) { continue; }   // ...report only

            $row->touch();                                // don't sweep again next tick
            ProcessSyncStatus::dispatch($row->id);
            Log::info('reconciler: re-dispatched', ['id' => $row->id]);
        }

        return self::SUCCESS;
    }
}

Three things that are easy to get wrong:

touch() before dispatch. Otherwise the next tick sees the same stale row and dispatches it again — a job multiplier, not a reconciler.
--limit. If something breaks for a day, the first sweep shouldn't dump 40,000 jobs into Redis.
Idempotent job. Reconciliation will occasionally re-run something that was fine. That must be a no-op: claim the row at the top of handle(), make the work an upsert.

Tests

Queue::fake() plus a backdated updated_at covers the cases that matter:

function agePendingRow(SyncStatus $row, int $minutes): void
{
    // Bypass Eloquent timestamps to backdate updated_at.
    DB::table('sync_status')->where('id', $row->id)
        ->update(['updated_at' => now()->subMinutes($minutes)]);
}

it('re-dispatches a stale unclaimed pending row', function () {
    Queue::fake();
    $stale = SyncStatus::factory()->create(['sync_status' => 'pending', 'claimed_at' => null]);
    agePendingRow($stale, 60);

    $this->artisan('sync:reconcile-pending', ['--minutes' => 15])->assertSuccessful();

    Queue::assertPushed(ProcessSyncStatus::class, 1);
});

it('skips a pending row already claimed by a worker', function () {
    Queue::fake();
    $claimed = SyncStatus::factory()->create(['sync_status' => 'pending', 'claimed_at' => now()]);
    agePendingRow($claimed, 60);

    $this->artisan('sync:reconcile-pending', ['--minutes' => 15])->assertSuccessful();

    Queue::assertNotPushed(ProcessSyncStatus::class);
});

Plus a third: a fresh pending row must be left alone. Anyone can write a sweeper that re-dispatches everything — the value is in what it refuses to touch.

Takeaway

If a database row implies "a job should be running for this", something needs to check that claim on a schedule. Dispatch-on-create is a happy-path optimisation, not a guarantee.

The rule I'm keeping: the queue delivers, the database decides. Any state that can only be advanced by a queued job needs a reconciler behind it — otherwise "eventually consistent" really means "usually consistent, and silent when it isn't."

DEV Community: Nasrul Hazim

One folder shape for every course: a lifecycle monorepo convention

TL;DR

The lifecycle, as folders

_TEMPLATE/: a course starts as a copy

_ARCHIVED/: park it, don't delete it

CLAUDE.md: the convention, machine-readable

The takeaway

Stop Screenshotting Architecture Diagrams: Build Them as Single-File HTML

TL;DR

Why not just export a PNG?

Separate the data from the drawing

Layout: Grid for the boxes, SVG on top for the wires

The bit learners actually respond to

Trade-offs, honestly

Next

Ebook Reviewer Wanted: Help Me Find What's Gone Stale

Why I can't do this alone

What the job actually is

The feedback format

Who I'm looking for

What you get

Timeline

Applying

Dev Log: 2026-07-19

TL;DR

Email broadcasts

The route binding bug that says nothing

Seeding as a smoke test

Takeaway

Building an Email Broadcast Engine That Survives Retries

TL;DR

The shape of it

The suppression gate

Idempotency lives in the row

Never downgrade a status

Unsubscribe is a public route

Takeaway

Your Seeder Should Describe a Shape, Not Your Laptop

TL;DR

The seeder that only worked for me

Horizon or not is a real fork

Rename anything named after a phase

While I was in there: the CI matrix

Test the knobs

Takeaway

The differentiator test: if a rival can copy the claim, it isn't one

TL;DR

The problem with a "differentiators" section

Keep only what's structural

Make the diagram say it out loud

Takeaway

Dev Log: 2026-07-16

TL;DR

Differentiators a rival can't copy

Installers that survive being run twice

The Cloudflare-proxied origin trap

Laravel: CACHE_STORE and Redis ACL

Dev Log: 2026-07-15

TL;DR

Account suspension without deleting the user

The NGINX 405 that lied

Scope the transaction around the business write only

Two read-only agent tools

Suspend a user in Laravel without deleting them

TL;DR

1. Model the state, not a flag

2. Enforce on every request, not just at login

3. Gate the toggle with a policy — including "not yourself"

4. Test the edges, not the happy path

Takeaway

Dev Log: 2026-07-14

TL;DR

Fast-forwarding an app off an old skeleton

Security headers, default-on

Retention purge: the guard rails are the feature

Reconciler for jobs that never ran

Website: a 404 and a redirect

Takeaway

The Reconciler Pattern: When a Queued Job Simply Never Runs

`_TEMPLATE/`: a course starts as a copy

`_ARCHIVED/`: park it, don't delete it

`CLAUDE.md`: the convention, machine-readable