DEV Community: Dmitry Isaenko

Meet Krokq: a light, adaptable task tracker and chat with a built-in AI assistant

Dmitry Isaenko — Mon, 13 Jul 2026 15:23:04 +0000

The pain this grew out of

I help one client with blog support, and their team was working across four different messengers at once. Some people in one, some in another, part of them on a phone only. There was no single place to track anything. Every subproject landed in one shared chat, and it turned into a mess: tasks got lost, agreements were forgotten, and results were written down nowhere.

The big systems are supposed to fix this. But Odoo, monday, ClickUp and the heavy ERPs are too much for a small team, packed with features nobody there will ever touch. By the time you finish setting one up, any wish to actually use it is gone.

I wanted something light that fit this exact problem. That is how Krokq started.

What Krokq is

Krokq (krok means step) is a light and completely free task tracker and chat under one shell, with a built-in AI assistant.

The chat is built to feel like the messengers people already use, WhatsApp, Telegram, Viber. That matters more than it sounds: nobody has to learn a new tool, it is familiar from the first minute, and the barrier to entry is almost zero. It takes the parts that actually get used: messaging, drafts, comments, voice notes, drag and drop files, reactions. But the main thing is moving freely between the two modes, Chat and Tasks.

Turn a chat message into a Task in one click.
Jump from a Task straight into a private chat with that person.
Or keep the discussion right inside the Task, whichever fits.

The Tasks side

Create a task by voice with the built-in AI assistant (more on that below).
A real workflow: New, In progress, Rework, In review, Done, plus Trash and Archive.
Custom task types to match how a team works.
A board with columns, with urgent items standing out.
Threaded comments under a task, with reactions, editing and deleting.
Attachments on a task, uploaded or pulled from a connected source.
Search across tasks.
Status based permissions: an assignee goes read only once a task is accepted or archived, for example.
Assigning an owner, accepting work, or sending it back for rework.

The Chat side

Private conversations with colleagues.
Drafts, editing, deleting and forwarding messages.
Reactions on messages.
Voice messages with a waveform.
Attachments: drag files into a thread and back out, paste an image from the clipboard.
Presence indicators and read receipts.
Quoting and replying to a message.

The AI assistant

There is a built-in AI assistant for creating tasks by voice. You tap the button, say what you need in plain words, something like "new task for Sveta to check the banners, urgent, by Friday", and it opens a ready to save task form with the title, the assignee, urgency and the due date already filled in. You look it over, fix anything, and save.

It works in any of the 10 languages the app speaks, and you can pin the language you dictate in from your profile when it differs from the interface language. Under the hood the clip is transcribed and turned into a structured intent by Gemini, then mapped onto real people and task types from your company. For now it does one thing, creating a task, and it does it well. More intents are next.

Adaptable through connections

This is the part I am most happy with, and the reason Krokq stays light without being limited. Krokq connects to the services a team already uses, and their content shows up right inside the app as a built in source.

Two connections are ready so far, both to WordPress:

Gallery: browse and search a connected site's media library, read only, through the app backend.
Posts: the list of the site's posts.

Everything goes through the backend over the WP REST API and Application Passwords, you can connect several sites at once, and access is set per company. The useful bit: right from there you can build a Task or drop a message into Chat, without exporting or copying anything by hand.

Under the hood each connection is a small descriptor class. Here is the WordPress Gallery one, trimmed to the essentials:

// A Krokq connection is just a small descriptor. This one pulls a
// WordPress media library into the app, read-only, through the backend.
final class WpGalleryPlugin extends AbstractPlugin
{
    public function id(): string   { return 'wp-gallery'; }
    public function name(): string { return 'WordPress Gallery'; }

    public function multiInstance(): bool { return true; }  // connect several sites
}

Adding a new one for another service is the same kind of descriptor, so the list keeps growing around real requests. That is what adaptable means here: the tool shapes itself to the work, not the other way around.

An app, not just a website

Installs as an app through Chrome on Android and Safari on iOS, and on desktop too. If the system allows standalone, Krokq offers to install itself.
Web Push notifications, with an unread counter right on the icon.
Share files into the app: the system lists Krokq among the share targets for most file types.
10 languages, more as they are needed.
No mobile app yet, but the whole base for it is in place: an API plus Sanctum. So it is a matter of time.

Sign in and demo

Sign in with a login and password or through Google OAuth. Signing in on another device by QR code is next on my list.
Right after signing in you can fill the app with demo data in one click (the vertical is retail, in any of the 10 languages). The demo lives for 24 hours and then deletes itself, so the sandbox is always clean.

What this runs on

Krokq runs on my own engine package, LaraFoundry, a core for spinning up SaaS projects fast: companies, users, roles, authentication. Krokq is the third application on that engine, and the Krokq side itself took me about three days. The engine already runs in production on other apps, and I keep polishing it in parallel.

The domain is covered by tests (Pest and PHPUnit), with the usual CI on top.

What is next

Bigger things in progress: bulk actions on messages and attachments, data export, an admin layer for oversight, and more service connections. I will show them as they land.

Follow along

If a light tracker plus chat is something your small team keeps improvising in group messengers, give Krokq a try and tell me what is missing.

I extracted a Laravel SaaS engine from my own app, then rebuilt the app on top of it. Here is what stood up, and the bug that fooled me

Dmitry Isaenko — Tue, 16 Jun 2026 14:03:03 +0000

A bit of backstory, because it is the whole point of this post.

Kohana.io came first. It is a CRM I built. I pulled its foundations out into LaraFoundry, a reusable Laravel SaaS package, and now I am building Kohana.io a second time, this time on top of that package. The app the engine came from, rebuilt on the engine, before the package goes out to anyone else. If it cannot carry its own birthplace, it has no business carrying yours.

So this is the real test, and the part most write-ups skip: not the first laravel new, not the launch, but the day you wire a real product shell on your own foundation and find out whether it holds. I stood up the whole host (shell, theming, auth, profiles, account lifecycle), then spent an hour chasing a profile form that lied to me.

No secret sauce here. The actual business logic of Kohana.io (the CRM domain) is still ahead. Everything below is the scaffolding any SaaS needs, so I can be open about all of it.

The setup: engine vs host

Two repos do the work, and they share a bloodline.

LaraFoundry is the engine. It is a Composer package (dmitryisaenko/larafoundry) extracted from the original Kohana.io, with real production mileage behind that code. Auth, multi-tenancy, roles, settings, notifications, tickets, legal and GDPR, a billing seam, all live in the package now with their own Pest suite.

Kohana.io is the host: the same product, rebuilt clean. A normal Laravel 13 app that consumes the engine it once gave birth to, then adds its own skin and, eventually, its own domain back on top. Dogfooding in the most literal sense.

Locally the host pulls the engine through a Composer path repository, so I can edit the package and the app side by side:

"repositories": [
    { "type": "path", "url": "../larafoundry" }
],
"require": {
    "dmitryisaenko/larafoundry": "*"
}

composer require dmitryisaenko/larafoundry, and the engine arrives with its dependencies in tow:

Inertia 3 and Vue 3 for the frontend, no separate API client to babysit
Tailwind CSS v4 for styling
Laravel Fortify for the auth backend (login, registration, password reset, two-factor)
Laravel Sanctum for token and same-origin API auth (this is what lets a future mobile app and the QR login share one guard)
Ziggy so the Vue side can name routes
vue-i18n for the multilanguage UI
Pest for the tests

One command, and the host has a working auth backend, a tenancy model, a roles system and a design system. That is the whole point of the package.

Skinning, not rebuilding

Here is the part I was nervous about and turned out to be the easy part.

The package ships a real design system: Tailwind v4 design tokens, layouts, and around 60 pages already built on semantic tokens (bg-surface, text-ink, border-border, and so on). It is intentionally neutral so the whole ecosystem can reuse it.

So skinning Kohana.io did not mean rewriting pages. It meant one override layer in the host app.css: restate the same semantic tokens in the Kohana palette (cool neutral surfaces, a blue brand, Inter as the font) and add a dark layer. Tailwind v4 merges @theme blocks, so the host values win over the package defaults, and every package page recolors itself.

@theme {
    --color-brand-500: #3b82f6;
    --color-surface: #ffffff;
    --color-ink: #1a2334;
    /* ...the rest of the palette... */
}

/* dark layer, toggled by html.dark */
html.dark {
    --color-surface: #121a2b;
    --color-ink: #e7ecf6;
}

On top of that I built the host shell by hand, because the shell is where a product gets its personality: a full-width top bar, a collapsible sidebar rail, an account pullout, and a small overlay system for the mobile drawer, search and language menus.

Auth, almost for free

Because Fortify and Sanctum came with the package, the auth surface was mostly wiring and skinning, not building from zero. What Kohana.io now has:

Email and password registration and login
Google sign-in (OAuth)
QR cross-device login: the login card flips to a QR panel, you scan it with an already signed-in device, and the browser session is approved
Two-factor authentication (TOTP) through Fortify, with recovery codes
A session PIN lock: an authenticated session can lock itself, and unlocking uses an iPhone-style keypad

The PIN screen was the one place I let myself fuss over the details, because a lock screen is something you touch a lot. A row of dots, a round number pad, a digit that flashes then collapses into a dot, a shake plus a short haptic buzz on the wrong code, real hover states on a pointer and pressed states on touch.

Theming that follows the system, then obeys you

Default behavior: the app follows your OS or browser theme. No cookie set means it reads prefers-color-scheme before first paint (an inline script in the Blade root sets the class so there is no flash of the wrong theme), and it keeps following the OS live, so flipping your system to dark flips the page without a reload.

The moment you press the theme toggle, that becomes your choice. For a signed-in user it is stored in their settings. For a guest it rides a small appearance cookie (light or dark), re-stamped on every visit so it effectively never lapses. Once you have chosen, the OS no longer overrides you.

This runs everywhere a guest can land: the marketing landing, the auth screens, the lock screen. The dark sections of the landing lighten in light mode and keep their branded navy in dark mode.

Profile and account lifecycle

The profile hub is the kind of thing that is easy to demo and easy to get subtly wrong. Changing your email asks for your current password, resets email verification, and revokes your other sessions. There is an avatar, an appearance tab, active sessions, and a danger zone that does the GDPR work: export your data, or delete your account.

Account lifecycle is enforced server-side by the package middleware, not by hiding buttons. A blocked or deleted account is logged out on its next request. A super-admin is kept inside the operator console. If a Terms page is published, a re-accept gate makes sure consent is current. All of it is no-op for a normal signed-in user and never trusts the client.

The bug that fooled me

Now the part I actually want to remember.

I opened the profile form, changed my last name, my phone, my country, my date of birth, hit save. Green toast: saved. Refreshed. Everything except name and email was gone. The toast was not lying about the request succeeding. The data really was being dropped.

Database row: only name and email had changed. So the request reached the server, validation passed, and most fields quietly evaporated.

The cause was a shadow. The Laravel starter kit that seeded the host had scaffolded its own App\Actions\Fortify\UpdateUserProfileInformation, a stub that does forceFill(['name', 'email']) and nothing else. And in the host's FortifyServiceProvider, a single line bound it over the package:

// host app, FortifyServiceProvider::boot()
Fortify::updateUserProfileInformationUsing(UpdateUserProfileInformation::class);

That call is a singleton rebind. It runs after the package registers its own full action, so it wins. The package action that knows how to persist every profile field never ran. Fortify dutifully called the stub, the stub saved two fields, everyone went home happy except the database.

The fix was deletion, not addition: drop the override line, delete the dead scaffold file, and let the package contract resolve. Then a regression test so it can never come back quietly:

it('persists every profile field', function () {
    $user = User::factory()->create();

    $this->actingAs($user)->put('/user/profile-information', [
        'name' => $user->name,
        'email' => $user->email,
        'lastname' => 'Doe',
        'phone' => '+10000000000',
        'country' => 'US',
        'birth_date' => '1990-01-01',
    ])->assertSessionHasNoErrors();

    expect($user->fresh()->lastname)->toBe('Doe');
});

The lesson generalizes. When a host extends a package, the danger is rarely a conflict you can see. It is scaffolded code, generated months ago by a starter kit, silently overriding a contract the package expected to own. Now I grep for ...Using( rebinds in a host before I trust anything.

Proof: the tests

Every change runs against Pest. The host has its own integration suite (167 tests at the time of writing) that exercises the package through the real app: auth flows, tenancy, profile, tickets, the waitlist, the lifecycle middleware. The engine itself ships well over 700 tests. CI runs both, and the frontend has to build clean before anything merges.

That regression test above is now one of the 167. It went red the moment I reproduced the bug and green the moment I deleted the override, which is exactly the feedback loop you want when a framework is quietly working against you.

What is next

The scaffolding is up: the app the engine came from, rebuilt on the engine, with auth, theming, profiles and account lifecycle all wired and tested. That is the part I most wanted to prove, because if the package can carry its own birthplace it can carry someone else's app too. None of it is the product though. The product is the CRM domain that goes on top, and that is what comes next.

If you like watching a SaaS get rebuilt on a foundation you can install yourself, this is a good time to follow along.

Follow along

LaraFoundry on GitHub: https://github.com/dmitryisaenko/larafoundry
Kohana.io public repo: https://github.com/dmitryisaenko/kohana_public
The engine and its story: https://larafoundry.com
The product being built on it: https://kohana.io

Building a SaaS engine in public: an affiliate program that isn't one hardcoded scheme

Dmitry Isaenko — Thu, 11 Jun 2026 08:49:48 +0000

For most of this series I have been shipping the parts of a SaaS that you can see: auth, multi-tenancy, an admin console, billing. The affiliate program is the part I deliberately left for last, because it is the one most likely to get built as a special case and regretted later. This post is about finishing it without that regret.

LaraFoundry is a reusable Laravel SaaS core I am extracting in public from a CRM that already runs in production, one module at a time. The core is free and stays free for everything except money. The day a business wants to charge its own customers, that is the paid billing add-on. An affiliate program is squarely on the paid side: it is a way to grow paid revenue, so it ships inside that add-on, on top of the billing engine I wrote about a few posts back.

Here is what "done" means concretely. A partner identity with a unique referral code. A capture link that attributes a new tenant to the partner who sent them. Commission that accrues when a referred tenant pays, on rules you choose. A clawback when that payment is refunded or fails. A super-admin payout console with per-currency totals and a CSV export. And a self-serve dashboard where a partner sees their own referrals and balance. All of it under 314 Pest tests.

Two decisions shaped every line, and they are the whole point of the post.

Decision one: an engine, not a scheme

The easy way to build an affiliate program is to encode the one you want. Twenty percent, recurring, paid on every invoice. It works, you ship in a day, and you have just fenced every host that uses your core into your commission policy. A reusable core cannot do that. So instead of a scheme I built an engine, configured along three axes that do not know about each other.

'affiliate' => [
    'enabled'     => true,
    'eligibility' => 'auto',          // auto | self_serve | admin
    'commission'  => [
        'trigger'       => 'recurring', // first_payment | recurring | lifetime
        'window_months' => 12,
        'basis'         => 'per_plan',  // per_plan | percent | fixed
    ],
],

Eligibility answers who becomes a partner. auto mints a code for every user so anyone can share a link. self_serve lets users opt in but holds them pending an admin approval. admin means partners are invited only. Trigger answers which payments pay out. first_payment is a one-time bounty per referral. recurring keeps paying for a window, twelve months by default, then stops. lifetime never stops. Basis answers how the amount is figured. per_plan reads a commission amount from the plan dictionary, percent takes a share of the net payment, fixed is a flat fee. A per-partner override can raise or lower the percent rate for a specific affiliate.

Because the three axes are orthogonal, any combination is valid and the engine does not branch into a tangle of special cases. The trigger decides whether a given payment is eligible at all; the basis, independently, decides the amount once it is. The default is the sensible one (a code for everyone, recurring for a year, priced per plan) but it is a default, not a law.

Decision two: zero host code

The part I am happiest with is that turning a partner program on does not add a single line of PHP to the host application. It rides two events that already existed before the affiliate program did.

// Free core, public: fired whenever a tenant is created.
event(new CompanyCreated($company, $owner));

// Paid add-on, fired whenever a company payment is processed.
event(new CompanyPaymentProcessed($payment));

CompanyCreated is part of the free core. It fires on every signup regardless of billing or affiliates, because the core needs it for its own bookkeeping. CompanyPaymentProcessed is the billing add-on's own event, fired by the gateway webhook listener when a charge settles. Neither was invented for the affiliate program. The affiliate program simply subscribes to them.

Event::listen(CompanyCreated::class, AttributeReferral::class);
Event::listen(CompanyPaymentProcessed::class, AccrueAffiliateCommission::class);

AttributeReferral reads the referral cookie set by the capture link and locks the new company to a partner. AccrueAffiliateCommission runs the trigger and basis logic and writes a commission row. Both listeners, and the engine behind them, are the proprietary part of the add-on, so I am describing them rather than dumping them. The shape is what matters here: the add-on registers these listeners from its own service provider, gated behind the affiliate.enabled flag. A host turns the feature on in config, publishes the two Inertia pages, and is finished. There is no controller to write, no event to fire by hand, no model to touch. The seam was already in the core; the add-on plugs into it.

Attribution is lock-once, and not an oracle

A referral link is /r/{code}. Hitting it drops an encrypted cookie and redirects. The redirect is uniform: it goes to the same place whether the code is real or not, so the endpoint never becomes an oracle you can poke to enumerate valid codes. When that visitor later creates a company, AttributeReferral fires.

Attribution locks once. The first partner to refer a company keeps it; a later link cannot steal an existing tenant, because the referral row is keyed unique on the referred company. Self-referral is blocked, so a partner cannot sign up under their own code. And the partner gets exactly one bounty per referral under the first_payment trigger, tracked so an out-of-order webhook cannot pay it twice. That last one was a real bug an adversarial review pass caught before it shipped: the idempotency key was per payment, not per referral, which under a replayed or out-of-order webhook could have accrued two first-payment bounties. The fix was to make "first payment" mean "this referral has no live commission yet," and a regression test now guards it.

Money stays honest

Commissions are stored per currency, in integer minor units, with no converter anywhere. This is the same rule the rest of the billing engine follows. A partner who refers customers paying in euros, zlotys and dollars accrues three separate balances, and the console reports three separate totals. There is no FX rounding turning real money into an approximation of a dollar figure.

Payout is manual on purpose, and I want to be clear that this is a feature, not a gap. The add-on has no money-out payment provider, and it does not pretend to have one. What it gives the operator is the truth: a report of who is owed what, per currency, with a state machine they drive by hand. A commission starts pending when it accrues. The operator approves a batch (pending to approved), then marks them paid once the money has actually left, attaching a payout reference (approved to paid). A commission can be voided manually for a refund the automatic clawback could not catch. Speaking of which: when a payment is refunded or fails, the matching commission for that same invoice is clawed back automatically, unless it has already been paid out, in which case it is left alone for a human to reconcile.

The console exports the current filtered report as a CSV, and that CSV neutralises spreadsheet formula injection: any cell whose text starts with one of the dangerous characters is prefixed so a spreadsheet treats it as literal text, not a formula. A payout reference an operator typed should never execute in Excel.

The two surfaces

There are two UI surfaces, both Inertia and Vue pages the host publishes, the same delivery pattern the rest of the core's frontend uses, so the add-on does not drag in a second build pipeline.

The super-admin gets the payout console: the commission report with per-currency totals by status, the bulk approve / mark-paid / void actions, and the CSV export. The partner gets a self-serve dashboard scoped strictly to their own user id: their code, their referrals, and their balance by currency and status. The dashboard never leaks another partner's numbers, which the tests assert directly.

The proof, because every release claims one

314 Pest tests in the add-on, Pint clean, and a two-agent adversarial review (one for security, one for correctness) before this could be called done. The security pass came back with no high findings: the partner dashboard scope is airtight, the console is gated three ways (route, policy, form request), the payout state machine is safe against id tampering, and attribution is self-referral-blocked and oracle-free. The correctness pass found the out-of-order double-bounty I described above, plus a quieter one: a percent rate provided through an environment variable arrives as a string, and the coercion had been rejecting numeric strings and silently falling to zero percent, which would have paid nobody. Both are fixed with regression tests. A payout you cannot trust is worse than no program at all, and the failure modes here are the quiet kind.

The honesty section

Every post in this series gets one. This is the new code, not the proven-by-years code. The core underneath the affiliate program comes out of a CRM that runs in production, but the affiliate engine itself is greenfield, written for this milestone, and proven by tests rather than by time. Its accrual rides on CompanyPaymentProcessed, which is driven by the billing gateways I have built and tested but not yet run against a live merchant account end to end. So I am not going to tell you commissions have been earned and paid in production, because they have not. They have been earned and paid across 314 tests.

And it is a lean engine, not a full affiliate platform. There is no automated money-out, no fraud scoring, no tiered partner ladders. Those are deliberate non-goals for a first version. What is here is the spine: attribution, a configurable accrual engine, clawback, a payout console and a partner dashboard, drawn so a host can grow it without forking it.

The thread, again

Every phase in this series lands on the same shape. The interesting engineering is fine, but the real lesson is always a default that was right for one app and wrong for a reusable one. For the affiliate program it was the commission scheme itself. The CRM I extracted from would only ever have needed one policy, because it serves one business, and hardcoding twenty-percent-recurring would have been completely reasonable there. In a reusable core it would have quietly become everyone's policy. The work was not building referral tracking. It was refusing to bake in one company's idea of what an affiliate program owes, and wiring the whole thing so a host turns it on without touching their own code.

Follow along

Code, versioned and Pest-tested before each tag: github.com/dmitryisaenko/larafoundry
The project and roadmap: larafoundry.com

GDPR as a seam: when the right to access and the right to be forgotten are the same shape

Dmitry Isaenko — Wed, 10 Jun 2026 09:38:10 +0000

I am building LaraFoundry, a reusable Laravel SaaS core, in public. It is extracted from a CRM that already runs in production, and I ship it phase by phase. This post is phase 5.3, the legal and GDPR layer. It bundled editable legal pages, cookie consent, a Terms gate, personal-data export, and account erasure.

GDPR work is usually the least loved part of a SaaS. It lands at the end, as a checkbox, as something you bolt on once a customer in the EU asks. I wanted it to be a seam from the start instead, and building it that way surfaced something I did not expect: the right to access and the right to be forgotten are the same shape.

What shipped in phase 5.3

Five pieces, each with its own review pass:

Legal pages: a super-admin editor for Terms, Privacy and Cookie policy, stored in the database, with versioning and a public /legal/{slug} route.
Cookie consent: a banner that is off by default, plus the plumbing to record a decision for guests and authenticated users.
Terms gate: middleware that asks a user to re-accept when the published Terms version changes.
Data export: a synchronous JSON download of everything the app holds about a user.
Account erasure: the right to be forgotten, as a grace-period soft-delete with an irreversible anonymise at the end.

The export and erasure pair is the interesting one, so it gets most of this article.

Export and erasure are the same seam

The same additive-provider idiom shows up all over LaraFoundry. The menu is built from menu providers. The dashboard is built from widget providers. So when it came to GDPR, I reached for the same idea twice.

A module that owns user data implements one small contract to export it:

interface ExportsUserDataProvider
{
    // The exportable data this provider holds for the given user.
    public function exportFor(Authenticatable $user): array;

    // Unique section key under which this data is filed (e.g. 'profile', 'tickets').
    public function key(): string;

    public function priority(): int;
}

And the mirror contract to erase it:

interface PurgesUserData
{
    // Erase or anonymise the data this purger owns. Must be idempotent.
    public function purgeFor(Authenticatable $user): void;

    public function key(): string;

    public function priority(): int;
}

Look at them side by side. exportFor() returns a slice, purgeFor() destroys a slice, and everything else is identical. Two methods with the same signature pointing in opposite directions. The core ships providers for the identity it owns (profile, sessions, settings, consent). The notifications module ships a provider for the inbox. The tickets module ships one for tickets. None of them know about each other, and neither the export flow nor the erasure flow knows the full list.

That symmetry is the whole point. When I add an orders module later, I register one exporter and one purger, and both GDPR rights light up for orders at once. There is no central place to update, no checklist to forget. The compliance surface grows with the app, automatically, because access and forgotten are wired the same way.

A registry collects each side:

public function exportFor(Authenticatable $user): array
{
    $sections = [];

    foreach ($this->sortedProviders() as $provider) {
        $sections[$provider->key()] = $provider->exportFor($user);
    }

    return $sections;
}

The export endpoint streams that as a JSON file, rate-limited so it cannot be hammered. The erasure registry walks the mirror set the same way.

Erasure is a grace period, not a DELETE

Deleting your account does not delete a row. It sets a user_deleted_at timestamp, signs you out, and hides you everywhere at once. That is a reversible soft-delete, and it starts a clock. A super-admin can still restore you during the window, which is the difference between a rage-quit you regret on Tuesday and a permanent loss.

The actual erasure happens later, on a daily cron:

$model::query()
    ->whereNotNull('user_deleted_at')
    ->whereNull('user_purged_at')
    ->where('user_deleted_at', '<', now()->subDays($graceDays))
    ->chunkById(100, function ($users) use ($registry): void {
        foreach ($users as $user) {
            DB::transaction(function () use ($registry, $user): void {
                $registry->purge($user);
                $user->forceFill(['user_purged_at' => now()])->save();
            });
        }
    });

Three things matter here.

It anonymises, it does not hard-delete the row. The core purger blanks the name, rewrites the email to a reserved unreachable address, drops the password, the two-factor secrets, the OAuth tokens, revokes the sessions and personal access tokens, and removes the avatar file. The row survives, faceless. That keeps foreign keys intact and lets legal records that must survive (think invoices) stay attached to an anonymised identity instead of dangling.

It is idempotent. A purged account is stamped with user_purged_at and drops out of the query forever. A row whose purge threw half-way is left unstamped and retried on the next run, and because every purger is written to be safe to run twice, the retry just finishes the job.

And each provider decides delete versus anonymise for itself. Personal data the user owns gets deleted outright. Records that have to survive get anonymised and kept. The contract does not force one policy on everyone.

The one thing I deliberately do not erase

The activity log.

It would feel tidy to scrub every trace of a user on erasure. It is also the wrong move. The audit trail of what happened, including the fact that an erasure ran, is exactly the evidence you need to show you honoured the request. So identity is anonymised everywhere, but the log of actions stays. Anonymise the who, keep the what. That is the line, and it was a decision, not an oversight.

Legal pages, the Terms gate, and a banner that stays quiet

The legal pages reuse work from an earlier phase. They are edited in the admin console, stored in the database per language, and rendered through the same HTML sanitizer the email template editor uses, so a stored legal page cannot smuggle a script into a public page. Each save bumps a version.

That version feeds the Terms gate. It is a piece of middleware, and the important property is that it is fail-open. It only forces re-acceptance once a Terms page is actually published with a version. Until then it does nothing. You never get a redirect loop into a Terms page that does not exist yet, and a fresh install is not held hostage by a feature nobody configured. When you do publish and later bump the version, every signed-in user is asked to re-accept once, then continues exactly where they were.

The cookie banner ships off. The core sets only strictly necessary cookies (session, CSRF, locale, the appearance toggle), and those do not require consent under GDPR. So there is nothing to ask about until you add analytics or marketing cookies yourself. The banner, the recorded decision and the consent state are all wired and waiting, you just flip one config flag the day you actually need it. No dark-pattern banner nagging people about cookies you never set.

Tests, because that is the proof

Every phase ships with its tests green and an adversarial review pass before merge. Phase 5.3 brought the suite to 743 backend tests in Pest and 164 on the frontend. Then the whole layer was wired into the host app and covered again with its own integration test: a published legal page is public, the Terms gate redirects a stale user on a real route, registration requires the checkbox only when Terms are published, the erasure cron anonymises past the grace window, and the consent state reaches the frontend.

GDPR is one of those areas where "it looks done" and "it is correct" are far apart, so the tests are not decoration here. They are the difference between a checkbox and a feature.

Free core stays free

LaraFoundry's core is open. Everything in this post is in the package, snippets and all. The plan is a free core that funds itself through a separate paid add-on, not by paywalling the basics. GDPR plumbing is about as basic as it gets, so it lives in the free core where it belongs.

Follow along

Star or follow the build on GitHub: https://github.com/dmitryisaenko/larafoundry
Project and updates: https://larafoundry.com

Letting admins edit email templates without handing them code execution

Dmitry Isaenko — Tue, 09 Jun 2026 13:38:22 +0000

I am building LaraFoundry, a reusable Laravel SaaS core, in public. It is extracted from a CRM that already runs in production, and I ship it phase by phase. This post is phase 5.1, which bundled three service modules: a settings store, a profile hub, and a database-backed email template editor. The email editor is the one with the interesting security story, so it gets most of this article.

What shipped in phase 5.1

Three pieces, each its own sub-phase with its own review pass:

Settings: one generic key-value store with three scopes (app, company, user), driven by a config registry.
Profile hub: a single tabbed page for name and email, password, two-factor, PIN, sessions, avatar and UI preferences.
Email templates: a super-admin editor for the subject and HTML body of the core emails, per language, stored in the database.

The email template editor, and why rendering is the scary part

The feature itself is mundane: let an operator change the wording of the verification email, the password reset, the welcome message and the company invitation, without a deploy, in each supported language. Store it in a table, edit it in the admin console.

The danger is in how you render it. The lazy version is to push the stored string through Blade or some expression engine so {{ $user->name }} just works. The moment you do that, an admin-authored string becomes executable. Anyone with an admin session, or anyone who steals one, can type their way to remote code execution. Server-side template injection is exactly this mistake.

So the renderer does not use Blade and does not use eval. It is a literal single pass over {{name}} tokens and nothing else:

public function render(string $template, array $data, bool $keepUnknown = false): string
{
    return (string) preg_replace_callback(
        '/\{\{\s*(\w+)\s*\}\}/',
        function (array $matches) use ($data, $keepUnknown) {
            $key = $matches[1];

            if (array_key_exists($key, $data)) {
                return (string) $data[$key];
            }

            return $keepUnknown ? $matches[0] : '';
        },
        $template,
    );
}

A few properties fall out of this that matter:

The substitution is a single pass. The replacement value is never re-scanned, so if a piece of data happens to contain {{something}}, it cannot trigger a second round of substitution. No recursive expansion games.

The stored string never reaches an expression engine. There is no compile step, no eval, no Blade. A template in the database is structurally incapable of executing code, by construction, not by a blacklist I have to keep patching.

Unknown tokens are emptied by default, so a recipient never sees a raw {{token}} leaking into their inbox. The preview path passes keepUnknown so an operator can still see what is wired up.

That renderer is the primary safety boundary. Everything else is defense in depth:

Strict variable whitelist. Each template declares the variables it is allowed to use. On save, every {{variable}} referenced by the subject and body is checked against that whitelist across all languages. Reference something undeclared and you get a 422, not a silent surprise at send time.

HTML sanitizing. The body is run through HTMLPurifier with an email-friendly allowlist (tables, inline styles, the things email actually needs) on write and on preview. Scripts, event handlers and javascript: URLs are dropped. This is built on the purifier directly rather than a framework wrapper, so the core does not get dragged along by a wrapper package's major releases.

Sandboxed preview. The live preview renders inside an iframe with sandbox and scripts off, so even the preview surface is a second independent barrier, not the only one.

The threat model is honest about who the actor is. The super-admin is a trusted operator, not a hostile end user. The renderer that cannot execute code is the real defense; the purifier and sandbox exist for the residual case of a compromised operator account or an honest paste of broken markup. I wrote the threat model down before building so the layers had a reason to exist instead of being security theatre.

A generic settings store with three scopes

The second piece is a single key-value store that serves three scopes: platform (app), company, and user. Rather than a table per concern, there is one table and one config registry that is the single source of truth:

'settings' => [
    'support_email'       => ['scope' => 'app',     'type' => 'string',  'public' => true],
    'signups_enabled'     => ['scope' => 'app',     'type' => 'boolean', 'public' => true],
    'timezone'            => ['scope' => 'company', 'type' => 'string',  'validation' => ['timezone']],
    'email_notifications' => ['scope' => 'user',    'type' => 'boolean'],
],

The registry is fail-closed: only declared keys can be read or written, so an arbitrary key never reaches the table, and every value is cast and validated against its declared type and rule before it lands. App settings are edited by the super-admin. Company settings are gated by RBAC permissions and always scoped to the active company, resolved on the server, never taken from the request. User settings are implicitly the caller's own, so there is no cross-user write.

Keys can also be marked public, and the host surfaces those to the frontend, which is how something like "are sign-ups open" reaches a guest page without exposing anything private.

The profile hub

The third piece pulls every self-service account screen into one tabbed page: profile fields, password, two-factor, PIN, active sessions, avatar and appearance.

The part I care about most is the boring hygiene. Changing your email asks for your current password, resets email verification, and revokes your other sessions. UI preferences are written through an allowlist (the donor code let any key into that column, which is the kind of thing you only notice when you go to extract it). Avatars go through the existing media service. And the account deletion and data export seams are already in place, ready for the GDPR phase that comes next.

Testing and integration

Every sub-phase landed green and went through an adversarial review pass before it merged: 667 backend tests in Pest and 151 on the frontend by the end of the phase. Then the whole thing was integrated into the host application (migrations, published pages, the new dependency, a frontend build) and tested again end to end, because "passes in the package" and "works in a real app on top of the package" are not the same claim.

Follow along

This is one phase of an ongoing build-in-public series. The core is free and open.

GitHub: https://github.com/dmitryisaenko/larafoundry (star or follow the build)
Project: https://larafoundry.com

I shipped a support desk by deleting a dependency

Dmitry Isaenko — Mon, 08 Jun 2026 15:22:42 +0000

I added a support desk to LaraFoundry this week. The first commit in the slice removed a package instead of adding one.

LaraFoundry is a reusable SaaS core for Laravel that I'm extracting in public from an older app of mine. Auth, multi-tenancy, roles, activity log, notifications, billing seam, and now support tickets. The rule for every module is the same: lift the proven idea out of the old code, modernise it, harden it, and make it something you can composer require into a fresh Laravel app without inheriting a pile of assumptions.

Tickets is where that rule got interesting, because the old code didn't own its ticket model. It leaned on a third-party ticket library.

Why a ticket package is wrong for a reusable core

A third-party ticket package is a perfectly reasonable choice when you're building one app. You get tables, a model, a status enum and a UI scaffold for free.

It's the wrong choice for a core that other apps install. Pull it into the core and every host app inherits that package's migrations, its table names, its status vocabulary and its idea of what a ticket is. The dependency becomes load-bearing in projects that never asked for it, and the day it lags a Laravel release, every downstream app waits.

So I cut it (decision D-4.2-1 in my notes) and wrote the model by hand. The model is about 180 lines. There is no magic. Two tables, a uuid, a status, a couple of scopes. The diff against "depend on the package" was less code in the core, not more, because I only kept the behaviour I actually use.

Here's the top of the model, with the extraction notes I leave for future me:

/**
 * A support ticket: the channel between a host user and the platform operator.
 *
 * Extracted from the donor App\Models\Ticket, which sat on a third-party
 * ticket package. That dependency is cut: this is a self-contained model.
 * Categories and labels are JSON slug arrays driven by config, not pivot
 * tables. The dead assigned_to column and the donor's invalid-operator
 * query are dropped.
 */
class Ticket extends Model
{
    use Filterable;

    public const STATUS_WAIT_MODERATOR = 'wait-moderator';
    public const STATUS_WAIT_CUSTOMER = 'wait-customer';
    public const STATUS_RESOLVED = 'resolved';

    protected $table = 'larafoundry_tickets';
}

The part worth keeping: a status nobody sets

The one genuinely good idea in the donor was its status flow, and it's the thing I kept.

Most ticket systems give the operator a status dropdown. Open, pending, on hold, waiting, closed. The list grows, two of the values mean the same thing, and half of them are wrong at any given moment because somebody forgot to change the dropdown after they replied.

LaraFoundry tickets have three statuses and you never pick one. The status is derived from who acted.

  user opens a ticket
        |
        v
  wait-moderator  <-----------------------+
        |                                 |
        | operator replies                | user replies
        v                                 |
  wait-customer  --------------------------+
        |
        | operator resolves
        v
  resolved  ----> user replies ----> reopens (wait-moderator)

In code it's just this, in the two reply paths:

// User replies. It needs the operator's attention again, whatever it was before.
$ticket->update(['status' => Ticket::STATUS_WAIT_MODERATOR]);

// Operator replies. The ball is back with the customer.
$ticket->update(['status' => Ticket::STATUS_WAIT_CUSTOMER]);

Replying to a resolved ticket reopens it, because a reply to a closed thing means it wasn't actually closed. No dropdown, no stale state, nothing to forget.

That same derived status drives the operator queue ordering. Open before resolved, brand-new before answered, high priority first, most recently updated last. I do it in one scope so the list always reads top to bottom as "deal with me first":

public function scopeWorkflowOrder(Builder $query): Builder
{
    return $query
        ->orderByRaw("CASE WHEN status = 'resolved' THEN 1 ELSE 0 END asc")
        ->orderByRaw("CASE
            WHEN created_at = updated_at THEN 0
            WHEN priority = 'high' THEN 1
            WHEN priority = 'standard' THEN 2
            ELSE 3 END asc")
        ->orderByRaw("CASE
            WHEN status = 'wait-moderator' THEN 1
            WHEN status = 'wait-customer' THEN 2
            ELSE 3 END asc")
        ->orderBy('updated_at', 'desc');
}

created_at = updated_at is a cheap trick for "nobody has touched this since it was opened", so a brand-new ticket floats to the very top without an extra column.

Extraction is a free code review

The other thing extraction gives you, and nobody advertises this, is a forced reading of code you wrote a long time ago and then stopped looking at.

To lift the ticket logic out cleanly I had to read every line of the donor. I found bugs I'd been running without noticing:

A query method built a filter with '!==' as its SQL operator. '!==' is JavaScript. In SQL it's a syntax error, which means that code path had never actually run. I dropped the method.
A queue filter was inverted. The flag that was supposed to show all tickets was being read the wrong way round, so the "all" view and the "open" view were quietly swapped in one branch.
There was an assigned_to column that nothing wrote to and nothing read. A leftover from the package's model that my app never used. Gone.

None of these were dramatic. That's the point. They were the kind of quiet wrongness that survives for years because the feature mostly works and nobody re-reads it. Extracting a module into a place where it has to stand on its own is the cheapest code review I know.

Config, not pivot tables

Categories and labels are the kind of thing you reach for a pivot table for by reflex. A categories table, a ticket_category pivot, a model, a seeder.

For a core that other people configure, that's heavy. So categories and labels are JSON slug arrays on the ticket, driven by config:

// config/larafoundry-tickets.php
'categories' => ['general', 'billing', 'feature', 'bug'],
'labels' => ['quick', 'complex'],

A host app adds a category by editing an array. No migration, no new model, no seeder. The slugs you allow are validated against that same config on the way in, so a request can't invent a category that isn't on the list. When a host eventually wants database-managed categories, the column is already JSON and the swap is local. Until then, this is the lightest thing that works.

The one screen a suspended customer must still reach

Here's the product decision I spent the most time on, and it's a one-line decision in the routes file.

The ticket routes sit behind auth and nothing else. No verified gate, and no account-active gate.

Route::middleware(['web', 'auth'])
    ->prefix('tickets')
    ->name('tickets.')
    ->group(function () {
        // the customer's own tickets
    });

The reason is support is the last channel. When a company gets suspended (say their billing lapsed and the tenant is blocked from the rest of the app) the support page is the one screen they must still be able to open, because it's their only line back to me. Gate it like everything else and you've locked a paying-again customer out of the room where they'd tell you they want to pay again.

There's a sharp edge here that only showed up when I integrated the module into the host app, and I like it as an example of why integration tests earn their keep.

The host applies a global middleware that hard-logs-out blocked or deleted accounts on every web route. So I had two ideas of "blocked" colliding:

A company suspended for billing. The user's own account is fine. They should reach support.
An account an operator personally banned. That one should be gone everywhere, support included.

The middleware that enforces the second one looks only at identity (is this account banned or deleted), and it deliberately knows nothing about companies. A company suspension never reaches it, so a billing-blocked user sails through to the ticket page. An operator-banned account is stopped at the door on every route. Two kinds of blocked, one deliberate line between them, and the only way I trusted that line was a test that drives the real host middleware stack and checks both.

Reusing last month's seam

Phase 4.1 was an in-app notification centre with a small service seam: hand it some users, a code and a couple of translation keys, and it delivers an in-app notification.

The ticket module didn't grow its own notification logic. When an operator replies, it calls that seam:

app(NotificationService::class)->system(
    users: [$ticket->user],
    code: 'info',
    titleKey: 'larafoundry::tickets.notify.reply.title',
);

The author gets a bell notification that an operator answered, localised to their language, and the ticket module stays out of the notification business entirely. Seams from one phase paying off in the next is the whole reason I freeze them.

The security pass

Self-written means I own the security, so the module got the same review gate every module gets: a few independent agents reading the diff adversarially before it merges. The things that mattered:

The route key is the uuid, never the sequential id, so a customer's URL never leaks how many tickets exist. On top of that an ownership policy authorises every action, so asking for someone else's ticket is a 403, not a peek.
Message bodies render as text, never v-html. A ticket is user-submitted content and the operator reads it in their console, so an unescaped body is a stored XSS straight at the admin. The message list component renders the body with text interpolation and whitespace preserved, and a Vitest test pins that escaping so a future refactor can't quietly turn it into HTML.
Opening tickets and replying are throttled, with the limits in config, so a script can't flood the support queue.

Testing

Tickets added 30 Pest tests to the core (it now sits at 556) and 8 Vitest tests for the Vue side (132). The model, the policy, the user flow, the operator console, the filter, and the two reply transitions all have coverage.

Then there's one more layer that I've come to rely on: a host integration test. The package has its own test suite against a bare test app, but the host app is where the real middleware stack, the real user model and the real tenancy live. The integration test opens a ticket as a real user, has an operator reply, and asserts the author got the notification, that a second user gets a 403 on someone else's ticket, that an unverified user can still reach support, and that the support menu item shows up for the operator. That's the test that caught the two-kinds-of-blocked edge above.

It's free

Tickets is FREE core, like auth and tenancy and notifications. The paid part of LaraFoundry is the billing add-on, not the things every SaaS needs. So all of the code in this post is exactly what ships, and you can read the rest in the repo.

The next step is writing the reference doc for the module while the details are still fresh, which is its own small discipline I'll write about separately.

Follow along

GitHub: github.com/dmitryisaenko/larafoundry (star or follow the build)
Project: larafoundry.com

"Notifications without WebSockets: an in-app centre and broadcasts on shared hosting

Dmitry Isaenko — Mon, 08 Jun 2026 11:22:39 +0000

Every "add notifications to your Laravel app" tutorial seems to start the same way: install Pusher or Reverb, wire up Echo, maybe spin up Redis. That is a fine setup once you actually need a live feed. But for an in-app notification centre, a bell with an unread badge and an inbox, it is a lot of moving infrastructure for something you can do with a queue and a cron line.

LaraFoundry, the reusable SaaS core I am extracting in public from a CRM that already runs in production, has a hard rule: it must run on plain shared hosting. No mandatory Redis, no Horizon, no long-running daemons. So when I built the notifications module (phase 4.1, tag v0.14.x) I had to deliver a real notification centre and super-admin broadcasts under that constraint. Here is how it went together.

The bell does not need a socket

The unread badge is a poll, not a push. The bell hits a tiny unread-count endpoint on a light interval, and only while the tab is actually visible, so a backgrounded tab goes quiet. The recent list is fetched when you open the dropdown, not on a timer. The full inbox is a normal paginated page.

That is genuinely enough for an in-app centre. A user who has the app open sees their count refresh within a minute, and sees everything the moment they open the bell. Realtime delivery is a nice upgrade to layer on later through the channels seam, but it is not a dependency you need to start with. Shipping the 90 percent that works on any host beats blocking on infrastructure most small SaaS never provision.

Broadcasts that do not block the request

The interesting half is super-admin broadcasts. An operator drafts a message with per-locale text, picks an audience, and sends. The audience filters are the domain-independent ones the core can own: verified users, recently active users, or users holding a given RBAC role. Demographic targeting (country, age) stays in the host, where that data lives.

The naive version of "send to everyone" attaches every matched user in one synchronous insert inside the request. On a large user base that blocks the request and balloons memory. So the send queues a job, resolves the audience from the stored filters, walks it in id-ordered chunks, and inserts each chunk with insertOrIgnore.

// A broadcast fans out to its audience, queued and chunked. insertOrIgnore keeps a retried job idempotent, no giant insert.
$this->recipientQuery($notification)
    ->select('id')
    ->chunkById(1000, function ($users) use ($notification) {
        DB::table('larafoundry_notification_user')->insertOrIgnore(
            $users->map(fn ($user) => [
                'notification_id' => $notification->id,
                'user_id' => $user->id,
                'created_at' => now(),
            ])->all()
        );
    });

Two details matter here. insertOrIgnore against a unique (notification_id, user_id) index means a retried job can never double-deliver. And the job only acts while the broadcast is in a sending state: once it finishes and flips to sent, a retry returns early instead of re-firing the audited "broadcast sent" event. The fan-out is idempotent, and so is the audit trail. It all runs on the database queue, so a single queue:work under cron is the only moving part.

A notification is content someone else wrote

This is the part I cared about most. A broadcast body and a system notification both end up as stored text that gets rendered into a user's browser. That is attacker-adjacent input, so I treated it that way.

Titles and bodies render as text, never v-html. A notification can carry actions, but each action is reduced to an internal, same-origin GET link before it ever reaches the frontend: a single leading slash, never a protocol-relative //host, never a backslash that a browser would normalise back off-site. The HTTP method is dropped, so a stored action can never drive a POST or a DELETE or bounce you to another origin.

And the inbox itself is scoped. Every read and every mutation goes through the user's own relation, so asking for another user's notification id simply finds nothing and returns a 404. No "mark as read" on a row you do not own.

The host pushes notifications through one seam

Your application should not write notification rows by hand. It calls one service, with translation keys instead of baked strings, so the message localises per recipient at read time.

// Send an in-app notification from your own domain event. Wording is translation keys, localised per recipient.
app(NotificationService::class)->system(
    users: $company->users,
    code: 'success',
    titleKey: 'Welcome to :company',
    params: ['company' => $company->name],
);

In the host I wired this to a domain event: when a company is created, its owner gets a welcome notification. The whole integration on the host side is small. Add a trait to the user model for the inbox relation, run the migration, publish the pages, and the bell shows up in the header because it ships in the core layout. Sending from your own events is the six lines above.

Proof, not vibes

None of this ships on faith. The module is covered with Pest on the backend and Vitest on the frontend, both green before the tag went out, plus the inbox scoping, the IDOR check, the broadcast fan-out and the super-admin exclusion are all asserted end to end against a real tenancy in the host app. The XSS-escaping of titles and bodies has its own frontend tests. Test count went up by a few dozen on this phase alone.

Building in public means the green suite is part of the story, not a footnote.

Follow along

Star or follow the build on GitHub: https://github.com/dmitryisaenko/larafoundry
Project site: https://larafoundry.com

How a solo dev builds like a team: freeze the seams, not the plan

Dmitry Isaenko — Mon, 08 Jun 2026 08:52:22 +0000

I build LaraFoundry alone. One person, one branch, one task at a time. A reusable SaaS engine for Laravel, extracted out of a real CRM (Kohana.io) that I am building in public.

Working solo, I never hit the question that breaks most teams: how do two people build two parts of the same system at the same time without stepping on each other.

Then I asked myself that question anyway, just as a thought experiment. And the answer changed how I see my own codebase.

The trap I almost fell into

When you imagine handing a big project to a team, the instinct is obvious. You think: I need a giant document first. Every route, every file name, every method, what it takes in, what it returns, every test and what it should assert, every security rule. One huge map of the whole thing, so two people never collide.

That feels like the grown-up way to do it. It is not. It has a name in the industry, Big Design Up Front, and teams moved away from it on purpose.

Two reasons it fails:

The map rots faster than you can write it. By the time you finish specifying every method of module E, building module A teaches you that three of those methods are wrong and two are missing. You wrote a document just to throw it away.

Detail is not the same as safety. A risky project does not get safer because the plan has more words in it. It gets safer when you test the expensive assumptions early. Writing a method signature is cheap and proves nothing. Building one vertical slice that actually runs through tenancy, billing and auth is expensive and proves everything.

So the giant upfront diagram is not the ideal you failed to reach. It is the thing you were right to skip.

What actually lets two people work in parallel

Teams do not write the giant map. They do three things instead.

They split the system by seams, not by phases. My phases (A, then E) are just one person slicing time. A team slices by module with clear borders. Auth, Tenancy, Billing, Navigation. Each one owned by someone, each one with a small public contract, and total freedom inside. You can parallelize exactly as much as your borders are clean.

They freeze contracts, not implementations. This is the key. To stop team B waiting on team A, you fix the interface between them and nothing else. Not every method of a class. Just the one contract through which A and B talk. An interface plus a DTO. Team B writes against the interface, team A implements it. B does not wait, B mocks the interface and keeps going.

They track dependencies as a graph, not a wall of text. Task E depends on contract C, which A must freeze. Once C is frozen (frozen, not implemented), E can start against a mock. Most of the time you discover that 80 percent of the "dependencies" only need a frozen contract, not a finished implementation, and you can parallelize almost everything.

"Freeze" does not mean carved in stone

Freezing a contract means: from this point, other people build on this shape, and nobody changes it silently and alone.

It is not forbidden to change. The cost just jumped. Before you freeze, change it however you like, it is your draft, nobody leans on it, free. After you freeze, you can still change it, but it is no longer your private decision. You are breaking someone else's work. So there is a protocol: announce it, agree with whoever depends on it, ship it as a versioned change, let everyone migrate.

That is the whole point of a freeze. It is the moment a change stops being an edit in your editor and becomes an event with a protocol. That jump in cost is exactly what gives everyone else permission to build on top of you in peace.

And you freeze the shape, not the guts:

interface PaymentGatewayManager
{
    // Frozen: the name, the inputs, the return type.
    public function charge(Money $amount, Customer $customer): ChargeResult;
}

Frozen: the method is called charge, it takes Money and Customer, it returns a ChargeResult. Not frozen: how it works inside, Stripe or Paddle, how many private methods it has. Team A can rewrite the guts ten times and team B never notices, because the contract did not move. You freeze the narrow border and leave full freedom behind it.

The plot twist on my own code

Here is what hit me. I went looking through LaraFoundry for the parts that would survive a team. And they were already there.

The billing add-on talks to the free core through a contract called EntitlementResolver. Navigation plugs into the app through a MenuProviderInterface. The admin dashboard accepts widgets through a DashboardWidgetProvider. Events carry a fixed payload.

I had been calling these "seams" the whole time. I built the billing add-on entirely against the core's contracts, and the core did not change while I did it (the tag stayed put). That is a freeze in action. The add-on leaned on a shape, the shape held, the add-on shipped on its own track.

So I had stumbled into the exact mechanism a team uses to work in parallel. I just was not using its main superpower, because solo and sequential I never needed to.

This is the honest version of the story. Not "I planned it all perfectly from day one." I did not. My seams were born inside the phase where I first needed them, not frozen ahead of time. The realization is the other way around: the question "how would this survive a team" showed me that the thing I already do for decoupling is the same thing teams do for parallelism.

What I would change the day a second person shows up

Not "write the giant map." This:

Pull the contracts into a frozen layer earlier. Right now my seams appear together with the phase that first needs them. On a team you flip it: one session where you freeze all the cross-module interfaces and event payloads first, with null stubs behind them, then the phases fan out to people.

Write decisions down as records, not as my own memory. Solo, my decisions live in my head and my notes. A team needs the same decisions as small versioned records in the repo, so everyone can see why tenancy is fail-closed without asking me.

Mark each dependency as "blocks on a contract" or "blocks on an implementation." The first unblocks the moment you freeze. The second actually waits. You usually find most of them are the first kind.

How to think about depth of planning

Planning depth is not uniform.

Module borders and the contracts between them: detailed and early. Expensive to change, they block other people.

Module internals: a sketch, details as you go. Cheap to change, they block nobody.

Tests: written as an executable spec, not described in prose. A Pest test is the formal record of what goes in and what comes out. That is why teams do not write "which tests and what they return" in a plan. They write the tests. My core sits on a Pest suite for exactly this reason, the tests are the contract, not the paragraph about the tests.

One picture for it: you plan the doorways between rooms in detail, where they are, how wide, because otherwise the walls will not meet. You do not plan the furniture inside a room. Whoever moves in decides that.

So where did I go wrong

Mostly nowhere. Extract, increment, seams. That is the right shape for a non-trivial project.

The giant upfront schema is an anti-pattern, not an ideal I missed. The secret to parallel work is not "write everything down." It is freeze the narrow contracts at the borders before the implementations diverge, and work against mocks. My seams were that mechanism the whole time. The only thing I would add for a team is to freeze them earlier, and to write down which dependencies are real and which dissolve the moment a contract is frozen.

If you are building solo and wondering whether you are doing it "properly" for a real project: look at your own decoupling points. The interfaces you made just to keep modules apart. Those are your freeze points. You are closer to how a team works than the giant-document instinct would ever get you.

Follow along

Star or follow the build on GitHub: https://github.com/dmitryisaenko/larafoundry
Project and updates: https://larafoundry.com

Extracting a QR login from a production app and closing 11 security holes before merge

Dmitry Isaenko — Mon, 08 Jun 2026 08:41:50 +0000

QR login is one of those features that looks tiny on the roadmap and turns out to be a security minefield. You show a QR code in the browser, scan it with a phone you are already signed in on, and the web session logs itself in. WhatsApp Web, Telegram Web, Steam. Everyone has used it. Nobody thinks about what happens behind it.

I had a working version of this in an app I already run in production. So when it came time to add cross-device login to the LaraFoundry core, I did what I do with every module: I extracted the real code instead of writing a fresh one from a blog post. Extracting beats greenfield because the logic already survived contact with real users. But there is a catch, and it is the whole point of this post: code that works is not the same as code that is safe. The donor version worked fine and had eleven things I was not willing to ship.

This is the list. Every hole, and what it became.

The flow, in one paragraph

The browser (a guest, not logged in) asks the backend for a sign-in request and renders it as a QR. A second device that is already authenticated scans the code and hits a verify endpoint to approve it. Meanwhile the browser polls until the request flips to approved, then logs the user in. Three endpoints: generate, verify, poll. Simple shape, lots of sharp edges.

The eleven

#	The donor did this	The core does this
1	Stored the raw token in the DB and put it in the QR URL	Stores a SHA-256 hash; the plaintext lives only in the QR image
2	No rate limit on any endpoint	Throttle on generate, poll and verify (verify is the brute-force surface)
3	`axios.get(decodedText)` on whatever the QR decoded to	Validates the scanned URL (same origin plus the exact verify path) before any request
4	TTL slid forward forever on reuse	Absolute cap measured from creation, so a code dies even if it keeps refreshing
5	Expired rows piled up forever	A prune command the host schedules
6	`Auth::login()` then `session()->regenerate()`	Regenerate first, then log in (session fixation)
7	No audit of attempts	Every approve, fail and block goes to the activity log
8	No indexes on the columns it queried	Indexes on the poll and prune predicates
9	Decrypted the id from the URL, so a bad value threw a 500	No decryption at all; a bad code is a clean 404
10	Encrypted the token AND the id into the session, twice	Stores only the row id, once
11	An unexplained `subSeconds(13)` fudge on the expiry check	Gone; a plain `expires_at > now()`

Three of these are worth showing in code, because they are the ones people get wrong everywhere, not just here.

Hole 1: the token was plaintext in the database

The donor generated a UUID, stored it as-is, and embedded it in the QR URL. If your database leaks, every live QR code leaks with it. The token is a bearer secret, so it gets the same treatment as a password: hash it, compare hashes, never persist the original.

// generate(): the plaintext only ever lives in the QR, the DB gets a hash
$plain = (string) Str::uuid();

$signInRequest = SignInRequest::create([
    'token'      => hash('sha256', $plain),
    'expires_at' => now()->addMinutes($this->ttlMinutes()),
    'ip_address' => $request->ip(),
    'user_agent' => $request->userAgent(),
]);

// verify(): look the row up by the hash of the token from the URL
$signInRequest = SignInRequest::query()
    ->where('id', $id)
    ->where('token', hash('sha256', $token))
    ->where('approved', false)
    ->where('expires_at', '>', now())
    ->first();

A nice side effect of dropping the encrypt/decrypt dance: there is nothing left to throw. The donor wrapped the id in Crypt::encrypt(), so a malformed value blew up with a 500 (hole 9). Hashing is a string compare. A wrong code just does not match, and you return a clean 404.

Hole 3: the scanner fetched whatever it decoded

This one made me wince. The mobile side did this:

// the donor: fetch literally anything the camera decoded
const onScanSuccess = async (decodedText) => {
    await axios.get(decodedText)
    location.reload()
}

A QR code is attacker-controlled input. Point the camera at a malicious code and the page will happily issue a request to any URL it contains. That is a server-side request forgery and open-redirect vector handed to you for free. The fix is to refuse to fetch anything that is not our own verify endpoint, same origin, right path, real scheme:

function safeVerifyUrl(decoded) {
    let url
    try {
        url = new URL(decoded, window.location.origin)
    } catch {
        return null
    }
    // reject blob:/data:/javascript: before anything else
    if (url.protocol !== 'https:' && url.protocol !== 'http:') return null
    if (url.origin !== window.location.origin) return null

    return /^(?:\/[^/]+)?\/larafoundry\/qr\/verify\/\d+\/[^/]+$/.test(url.pathname)
        ? url.toString()
        : null
}

The URL parser normalizes encoding and path traversal before the regex ever runs, so the ..%2f tricks do not get through. Origin is checked against the live origin, not a string match, so localhost.evil.com and userinfo tricks like app@evil.com fail too. A reviewer later threw 25 bypass vectors at this and every dangerous one bounced.

Hole 6: log in first, ask questions later

The donor logged the user in and then regenerated the session. That ordering is a session-fixation invitation: an attacker who fixes the session id before login keeps a valid handle after it. Flip the two lines and the fixated id is thrown away before the user is ever attached to it.

// poll(): new session id BEFORE the identity is attached to it
$request->session()->regenerate();
Auth::guard('web')->login($user);

$signInRequest->delete(); // single-use: the approved code cannot be replayed

The delete() is its own small fix. The donor left the approved row sitting there, so the same code could be polled again. One use, then it is gone.

The thing the donor never had: the super-admin block

There is a rule in the platform that the operator account cannot sign in by QR. The donor checked a raw is_admin column. The core already has a single resolver for "is this the platform super-admin", with a case-insensitive email allow-list on top of the flag, so a flipped column alone cannot grant it. The QR verify reuses that one resolver instead of inventing a second check that can drift:

if ($this->visitorStatus->isAdmin($approver)) {
    // audited, then refused
    return response()->json(['error' => __('larafoundry::auth.qr.admin_forbidden')], 403);
}

One source of truth for a security decision beats two that agree today and disagree after a refactor.

While I was in there: page or modal

The same phase shipped a small unrelated quality-of-life thing. The auth screens (login, register, forgot, reset) can now render either as a full page or as a modal over the host's content, switched by one config value:

'presentation' => env('LARAFOUNDRY_AUTH_PRESENTATION', 'page'), // page | modal

Default is page, so nothing changes for anyone who does not opt in. The donor only had modals, the core only had pages. Neither had the switch. Now one config key picks the surface and the same screen component renders both ways. An unknown value falls back to page, so a typo can never produce an undefined surface.

Proof, not vibes

Every module in the core ships with Pest tests, and a security feature gets the heaviest coverage. The QR backend has a test that runs the full two-device handshake inside one process (two independent sessions): a guest generates, an approver verifies, the guest polls and ends up authenticated, the row is consumed. On top of that: the token is stored hashed and never in plaintext, an expired code is refused, the absolute cap holds, a super-admin is blocked with a 403, a bogus token returns a clean 404 and never a 500, the verify works under both a web session and a Bearer token, and the prune command clears the right rows. The full core suite is 497 tests green.

The part I am proudest of is the part that caught me

Here is the build-in-public bit. Every sub-phase of this work went through two adversarial reviewers before merge, whose job is to try to break it, not to praise it. On the QR backend they caught a HIGH that I had missed: the verify URL carries the token, and the activity log was recording the full request URL. So the token I had so carefully hashed in the database was sitting in plaintext in the audit log. The hashing was undone by the logging.

The fix was systemic, not a patch on one line: the activity context now redacts secret path segments (by route-parameter name) the same way it already redacted query-string secrets. One reviewer, one HIGH, one better fix than I would have written if I had shipped on my own confidence. That is the whole reason the review gate exists.

Follow along

This is part of LaraFoundry, a reusable SaaS/CRM core for Laravel that I am extracting in public from real, production code.

GitHub (star and follow the build): https://github.com/dmitryisaenko/larafoundry
Project: https://larafoundry.com

The guard-agnostic verify endpoint (one controller that serves both a web session today and a mobile Bearer token tomorrow) deserves its own short write-up. That is the next post in the series.

Building a SaaS engine in public: a billing engine that isn't married to Stripe

Dmitry Isaenko — Mon, 08 Jun 2026 08:30:39 +0000

A while back in this series I shipped the billing seam and was very careful to say it was not billing. The free core got the whole shape of a subscription system, a gateway contract, a driver manager, a real access gate, and it could not take a single cent. That was on purpose. The cent-taking part lives in a separate paid add-on, and this post is about finishing the Lean MVP of that add-on.

LaraFoundry is a SaaS core I am extracting in public from a CRM that already runs in production, one module at a time. The core is free and stays free for everything except money. Auth, multi-tenancy, RBAC, the admin console, the activity log, i18n, files: all free. The day a business wants to charge its own customers, that is the paid part. So billing could not be "just another module." It had to split down a clean line: the free side carries the structure, the paid side carries the parts that actually move money.

Here is what "Lean MVP done" means concretely. Plans with real prices. Checkout that opens a real hosted payment page. Promo codes and a free first month. Subscription enforcement that blocks access when the money runs out. An owner-facing billing portal and a super-admin console to watch payments and manage promo codes. A reminder cron before a subscription lapses. And the single decision that shaped every line of it: none of it is married to one payment provider, and nothing is priced in one hardcoded currency.

The constraint that shaped everything

Most Laravel SaaS starters are Stripe-only. Stripe is excellent, and for a lot of builders that is the right and only answer. But Stripe reaches roughly 46 countries, and the market I build for is not one of them. If I bake Stripe into the call sites, I have quietly built a core that only serves the countries Stripe serves.

So the brief I gave myself was uncomfortable on purpose: build billing as if I do not know which provider the host will use, and as if the host's customers do not all pay in dollars. Everything below falls out of taking that seriously.

One contract, many drivers

The free core ships a single contract that describes only the mechanics of moving money:

interface PaymentGatewayInterface
{
    public function subscribe(Tenant $tenant, string $planId, string $period, array $options = []): array;
    public function cancel(Tenant $tenant, bool $atPeriodEnd = true): void;
    public function refund(string $chargeReference, ?int $amount = null): void;
    public function subscriptionStatus(Tenant $tenant): string;
    public function verifyWebhook(Request $request): array; // returns the verified payload, throws if not authentic
}

That is the entire surface. Notice what is not in it: nothing about tax, nothing about invoicing. That omission is deliberate. Tax responsibility differs by the kind of provider. With a PSP like Stripe the business is the merchant of record and owns its own VAT. With a merchant of record like Paddle, the provider owns the tax. If I folded a chargeTax() or an invoice() into the gateway method, I would bake one of those two models into both, and it would be wrong for the other half of my providers.

The paid add-on registers real drivers against that contract, in the same style as Laravel's own Mail or Queue managers:

// In the add-on's service provider. The form is public API; the driver bodies are the add-on.
$manager->extend('stripe', fn () => new CashierStripeDriver(/* ... */));
$manager->extend('paddle', fn () => new CashierPaddleDriver(/* ... */));

A config key picks the active driver. The call sites that start a subscription or read its status never know which gateway they got. A host in a country neither Stripe nor Paddle reaches can register its own local PSP against the same contract and change one config value. Swapping the entire payment provider is not a refactor, it is a string.

Both real drivers are built on Laravel Cashier (the Stripe one on laravel/cashier, the Paddle one on cashier-paddle). Cashier and not Spark, because Spark is an opinionated whole-app billing UI and I needed a gateway, not a front end. The driver bodies, the webhook verification, the column mirroring, are the proprietary part of the add-on, so I will describe them rather than dump them. The shape is: the driver opens a hosted checkout and hands back a redirect, and a webhook listener mirrors the provider's subscription state back onto the company's own columns, so the rest of the app reads one set of columns no matter which provider wrote them.

Stripe and Paddle are not the same animal, and the contract has to absorb that without leaking it. Stripe's subscribe returns a hosted Checkout URL to redirect to. Paddle's overlay wants a payload handed to its JavaScript instead of a server redirect. Both satisfy the same method signature and return shape, and the caller treats them identically. The one honest seam in the contract is refund: against a merchant of record, a programmatic refund goes through the provider's own adjustments flow, so that path is stubbed to throw clearly rather than pretend.

Plans are priced per currency

The other half of "not US-first" is the money itself. A plan in LaraFoundry does not have a price. It has a price per currency:

$plan = $plans->find('business');

$plan->priceFor('month', 'EUR'); // 1900   (minor units, 19.00 EUR)
$plan->priceFor('year',  'PLN'); // 79000  (790.00 PLN)

There is no single USD figure with a converter bolted on at display time. A customer in Warsaw is billed in their currency, with a price I actually chose for that currency, not a live FX-rounded approximation of a dollar amount. The currency is part of the plan definition, decided up front, not computed in the view. The PlanContract and priceFor live in the open core, so a free self-host gets the currency-first shape for free; the paid add-on supplies the config-backed plans and maps each plan and currency to the right provider price ID.

Where the free/paid line falls

This is the part I keep coming back to across the whole series. The free core ships the seam: the gateway contract, the access gate on the company model, and the subscription columns themselves (trial_ends_at, subscription_ends_at, plan_id). With billing turned off, which is the default, the gate is always open and the core is a complete multi-tenant app with no paywall anywhere. That is the entire promise of the free core.

The paid add-on fills the seam. It binds the real gateways, it writes those columns from webhooks, and it closes one more loop: entitlements. Access in a SaaS is really two independent questions, and collapsing them is a classic bug. RBAC answers "can this user do it." Entitlement answers "did this company's plan pay for it." A manager can legitimately hold production.view in RBAC while the company sits on a plan that never bought the Production module. So a route is gated by both at once:

Route::middleware([
    'can:production.view',           // RBAC: who in the company may
    'entitlement:production.module', // billing: what the plan paid for
])->get('/production', ProductionController::class);

The free core ships an entitlement resolver that is open by default. The add-on rebinds it to read the plan's features and refuse anything the plan did not buy. Billing off, every feature is open. Billing on, it is fail-closed and resolved server-side, with nothing to spoof from the request.

Enforcement of an expired or unpaid subscription has two modes the host picks. Soft mode lets the request through but surfaces the state, so you can nudge before you lock. Hard mode redirects to a blocked page. One case is always hard regardless of mode: if the account owner's own access is revoked, the block cascades to the whole company, because a company cannot operate on a banned owner's seat. A daily cron warns owners a few days before a subscription lapses, idempotently, so nobody gets the same reminder twice.

The surfaces, briefly

Two UI surfaces shipped with the MVP. The owner gets a billing portal: pricing, checkout, payment history, and the blocked page. The super-admin gets a console: a read-only list of payments (totalled per currency, with no converter, because the per-currency truth is the honest one) and full CRUD over promo codes. Both are built as Inertia + Vue pages the host publishes, the same delivery pattern the rest of the core's frontend uses, so the add-on does not drag in a second build pipeline.

The proof, because every release claims one

All of this sits under Pest. 241 tests in the add-on alone. I lean on tests hard here for a specific reason: a billing gate you cannot trust is worse than no gate, and the failure modes are quiet. A webhook listener that writes a null expiry date silently revokes a paying customer. A fail-open guard silently gives away the paid tier. Several of those exact bugs got caught by a test or an adversarial review pass before they ever shipped, and that is the whole argument for writing them.

The honesty section

Every post in this series has one, and this one earns a big one because "billing is done" is an easy thing to overclaim.

This is a Lean MVP, not a finished billing product. There is no affiliate program yet; that is a deliberately later milestone. The entitlement loop checks plan membership, the "is the subscription still alive" axis is enforced separately, and I am not pretending those are the same check.

And the big one: I have built and tested all of this, but I have not yet run a live charge against a real Stripe or Paddle account end to end. The drivers are exercised against the providers' test surfaces and a wall of Pest tests, not against a production merchant account with a real card. That last mile, real keys, a real webhook tunnel, a real subscription, is a separate step I have not taken yet, and I am not going to call the engine battle-tested until I have.

One more, on what is open. The core seam is open source and you can read all of it: the contract, the manager, the access gate, the entitlement resolver, the currency-first plan shape. The add-on is a paid, proprietary package, so the driver bodies, the webhook verification, and the enforcement internals are described here, not dumped. The free core staying genuinely free is what pays for that line existing at all.

The thread, again

Every phase in this series lands on the same shape: the interesting engineering is fine, but the real lesson is in a default that was right for one app and wrong for a reusable one. For billing it was two defaults at once. One provider, because the app I extracted from only ever needed one. One currency, because its one user paid in one. Both were perfectly fine for a CRM with a single customer, and both would have quietly fenced the reusable core into a single market. The work was not building Stripe support. It was building billing so that Stripe is one swappable cartridge, and so the price tag is not in dollars by assumption.

Follow along

Code, versioned and Pest-tested before each tag: github.com/dmitryisaenko/larafoundry
The project and roadmap: larafoundry.com

Building a SaaS engine in public: suspending a tenant without locking out the bystanders

Dmitry Isaenko — Thu, 04 Jun 2026 12:59:01 +0000

I tagged v0.10.0 of LaraFoundry this week: the admin companies console. It is the second screen of the operator panel, after admin users a few releases back, and the headline feature is that a platform operator can suspend a whole tenant now. Blocking the company turned out to be the easy half. The half worth writing about is not locking out the people who belong to other companies too.

LaraFoundry is a SaaS core I'm extracting in public from a live CRM, one module at a time. An earlier version of that CRM already runs in production, so most phases are less "invent a feature" and more "lift a feature out, and notice the habit that was fine for one app and wrong for a reusable core." This phase had a good one.

How the donor "blocked" a company

The honest answer is that it didn't, not directly. There was no company-level block in the admin at all. If you needed to cut off a tenant, you banned its owner, and a middleware then denied access to anyone whose owner was banned. The company went dark as a side effect of a person being punished.

That works right up until it doesn't. Banning the owner and suspending the company are two different operator actions with two different meanings. An owner can be a bad actor while their company keeps paying and keeps a dozen innocent employees working. A company can be suspended for non-payment while nobody did anything wrong. Folding both into "ban the owner" means you can never express one without implying the other, and the audit trail records the wrong story either way.

So the rule for this phase was to make a company block a first-class thing, separate from a user block, and to put its enforcement somewhere a future me can't accidentally route around.

One column, enforced at one boundary

A blocked company is one nullable timestamp on the companies table:

public function isBlocked(): bool
{
    return $this->company_blocked_at !== null;
}

That column is not in $fillable, so no tenant can POST its way back to active. Setting it is an operator-only action behind a policy, and it writes an entry to the activity log so there is a record of who suspended what and why.

The interesting decision is where the block is enforced. The tempting answer is "add an if ($company->isBlocked()) check to the controllers that matter." That is exactly the donor's scattered-middleware pattern in a new coat, and it rots the same way: the day someone adds a new tenant-scoped route and forgets the check, the block has a hole.

LaraFoundry already has a single place every tenant-scoped request must pass: the middleware that resolves and requires an active company. That is the one chokepoint where "this tenant is suspended" has to be true or false for the whole request. So the block lives there. One column, read at one boundary, takes the entire tenant down. There is nothing to forget on the next route.

The part that actually took the thought

Here is the trap. A user is not a member of one company. They can own one, be an employee of two others, and have an active company selected out of those. If an operator suspends the company that happens to be active for that user, a naive enforcement check does the worst possible thing: it blocks the request, the user gets bounced, and because their active company is still the suspended one, every subsequent request bounces too. You have effectively logged out and locked out a person who did nothing wrong and still has perfectly good companies to work in.

So the enforcement is not a wall, it is a self-heal:

protected function handleBlocked(User $user, Request $request): RedirectResponse
{
    // promote the next company that ISN'T blocked, then replay the request
    if ($user->setNextAvailableCompany()) {
        return redirect($request->fullUrl());
    }

    // no other company to fall back to: drop the active one and show the
    // blocked screen. no logout, no redirect loop.
    $user->clearActiveCompany();

    return redirect()->route('larafoundry.tenancy.blocked');
}

If the user has another company that isn't blocked, the middleware quietly switches them into it and replays the original request, so they land where they were headed in a tenant that still works. Only if there is genuinely nowhere to go does it clear the active company and show a "this company is suspended" screen. It never logs them out, because logging out a multi-company user over one suspended company is wrong, and it never loops, because the fallback state is stable.

Making "the next available company" actually skip blocked ones is a one-line addition that is easy to miss:

$next = $this->companies()
    ->whereNull('company_blocked_at')   // don't promote a user INTO a blocked company
    ->first();

And the company switcher gets the same guard, so a user can't manually select a suspended company from the dropdown either.

The review earned its keep, again

Every phase in this series has a moment where the code review catches something I was about to ship, and this one had two, both in exactly this area.

The first cut of the enforcement had a redirect loop: it bounced a blocked-company request to a safe route, but that route ran through the same middleware, saw the same still-blocked active company, and bounced again. The fix is the self-heal above, which changes the active company before redirecting, so the next pass sees a different, valid tenant.

The second was the promotion query. My first setNextAvailableCompany happily promoted whatever company came first, including a blocked one, which meant an operator could suspend a tenant and the affected user would get auto-switched right back into it. The whereNull('company_blocked_at') clause is small and it is the whole point.

There was also a duller but real bug the review flagged on the way through: the company list filters took array query parameters like ?status[]=x and blew up with a 500 because the base filter assumed scalar values. That one wasn't even about blocking, but the fix (skip any non-scalar filter value instead of trying to bind it) hardened the admin users filter at the same time.

The read-only line, on purpose

The console also shows each company's subscription status, classified into a small fixed vocabulary: on trial, active, expiring soon, expired, or never activated. An operator can see, at a glance, which tenants are about to lapse.

What the console deliberately cannot do is manage any of that. There is no "extend this subscription," no "change the plan," no "grant a manual trial" button. The status is read-only, computed from the billing columns the free core already carries, and the UI says as much in plain text: subscription management lives in the billing add-on.

This is the same free-versus-paid line I drew when I shipped the billing seam two phases ago. The free core is a complete multi-tenant operator console: list your tenants, inspect them, suspend the ones you need to. The moment the job becomes moving money and changing what a customer is entitled to, that is the paid larafoundry-billing add-on, a separate package. Showing the status is reading state the core already owns. Changing it is the product I'm going to charge for. Drawing that line through a single screen, so the free half is genuinely useful and the paid half is genuinely separate, is most of the design work.

The honesty section

A few things this phase is not. The company detail view is read-only: you can inspect a tenant, you cannot edit its details from the operator panel yet. The block stores a reason on the backend and audits it, but the reason-capture UI is minimal, not a polished workflow. And the admin dashboard with platform-wide metrics is deliberately deferred, because half its widgets want modules that don't exist in the core yet and the revenue half wants the billing add-on. Better an honest second console screen than a dashboard padded with two real numbers and a lot of "coming soon."

What shipped is the screen, green: the package is at 398 Pest tests and 81 Vue tests at the v0.10.0 tag, the security review came back clean, and six review findings (the two above among them) are fixed with regression tests.

The thread, again

The recurring lesson of this series is that the bug is almost never in the feature, it is in the default. Here the feature was easy: suspend a tenant. The default that needed unlearning was the donor's, where blocking a company meant banning a person, and the trap that needed avoiding was the obvious enforcement check that would have locked out everyone standing nearby. A block that takes down the right tenant and quietly steps the bystanders aside is a much smaller diff than it sounds, and it is the entire difference between an operator tool you can trust and one that generates support tickets.

Follow along

Code, versioned and Pest-tested before each tag: github.com/dmitryisaenko/larafoundry
The project and roadmap: larafoundry.com

Building a SaaS engine in public: shipping the billing seam, not billing

Dmitry Isaenko — Thu, 04 Jun 2026 09:58:28 +0000

I tagged v0.9.0 of LaraFoundry this week: billing. Except the honest headline is that I shipped the billing seam, not billing. The free core now has the whole shape of a subscription system, a payment-gateway contract, a driver manager, a real access gate over subscription columns, and it cannot take a single cent. That is on purpose, and the reason is the most interesting part of the phase.

LaraFoundry is a SaaS core I'm extracting in public from a live CRM, one module at a time. The deal I made with myself early on: the core is free and stays free for everything except money. Auth, multi-tenancy, RBAC, the admin console, the activity log, i18n, files: all free. The day a business wants to charge its customers, that is the paid part. So billing could not just be "another module." It had to split cleanly down a line, with the free side carrying real, useful structure and the paid side carrying the parts that actually move money.

The donor habit I would not carry

Here is what the original CRM did when a company "paid" for its subscription:

// TODO: real payment gateway integration
// TEMPORARY: every payment is successful, for testing
$paymentStatus = 'success';

That success was hardcoded. There was no Stripe, no Paddle, no gateway at all. "Paying" wrote a row into a company_payments table and flipped the subscription date forward. For a CRM I run myself, with one real user, that was fine: I never needed the real thing, so the placeholder sat there indefinitely.

The moment this becomes a reusable core, that placeholder is poison. A success that is always true is worse than no gateway, because it looks like billing works. So the rule for this phase was simple: the fake gateway does not get extracted. Whatever stands in its place has to be honest about the fact that it takes no money.

What the seam actually is

The free core ships a PaymentGatewayInterface: subscribe, cancel, refund, status, and verify a webhook. It describes only the mechanics of moving money. It deliberately says nothing about tax or invoicing, because that responsibility differs by gateway type (with a PSP like Stripe the client is the merchant of record and owns the VAT; with a merchant-of-record like Paddle the provider owns it). Folding tax into a gateway method would bake one wrong model into both.

The core registers exactly one driver against that contract: the null gateway. It refuses every money operation, loudly:

public function subscribe(Tenant $tenant, string $planId, string $period, array $options = []): array
{
    throw $this->notConnected();
}

No silent success. If something calls it without a real driver bound, it fails fast and tells you to install the add-on. The driver is resolved by a manager in the same style as Laravel's Mail or Queue manager: a config key picks the driver, the add-on registers real ones (stripe, paddle) via extend(), a host in a country those don't reach can register its own local PSP. Swapping providers is one config value, and no call site knows which gateway it got. That gateway-agnostic shape is the part I think matters most for non-US builders: most Laravel SaaS starters are Stripe-only, and Stripe reaches roughly 46 countries.

The gate that does the real work

The one piece of "billing logic" that genuinely belongs in the free core is the access decision. Before this phase, Company::hasAccess() was a stub that returned true, a seam planted back in the RBAC phase so call sites would not change when billing landed. Now it reads real state:

public function hasAccess(): bool
{
    if (! LaraFoundryBilling::enabled()) {
        return true;
    }

    return $this->subscriptionState()->hasAccess();
}

With billing disabled (the default), it is always true. The free core is a complete multi-tenant app with no paywall, and that is the whole promise. Turn billing on and it reads the subscription columns: a live trial or an active subscription grants access, anything else denies. Fail-closed when enabled, fully open when not.

The subscription columns (trial_ends_at, subscription_ends_at, plan_id, ...) ship in the free core's migration, not the add-on's. That is a deliberate call: the gate has to read real state with no add-on installed, and a free self-host should be able to grant a trial by hand. The add-on only writes those columns (its webhook keeps subscription_ends_at current). It adds no column of its own to the core table. And those columns are not mass-assignable, so a tenant can never POST its way to a free year of subscription.

The honesty section, because every release has one

The thing I am most careful not to overclaim: this phase wires the gate but no caller consults it yet. The intended loop is that the RBAC policy checker, or a "subscription required" middleware, asks hasAccess() before letting a request through. That wiring is not in this phase. So today, enabling billing makes the gate answer correctly, but nothing in the core enforces it. Returning real state now means those future call sites won't have to change when they arrive, which was the entire point of planting the stub two phases ago. But "the paywall enforces itself" is not a claim I get to make yet, and I'm not making it.

And the obvious one: there are no real payments here. No Stripe, no Paddle, no Cashier, not even as a dependency. No plans, no promo codes, no trial UI, no billing portal, no revenue metrics. All of that is the paid larafoundry-billing add-on, a separate package, a later milestone. What shipped is the contract those things stand on.

The thread, again

Every phase in this series lands on the same shape. The interesting engineering is fine; the lesson is in a default or a habit that was right for one app and wrong for a reusable one. This time it was a hardcoded success: a placeholder that worked perfectly for a CRM with one user and would have been a quiet disaster in a core other people deploy. The fix was not to build a real gateway. It was to build the honest absence of one: a seam that takes no money and says so.

The billing engine is the add-on. Drawing the free/paid line so the core stays genuinely free was the work.

Follow along

Code, versioned and Pest-tested before each tag: github.com/dmitryisaenko/larafoundry
The project and roadmap: larafoundry.com