DEV Community: NorfolkD

Fintech Frontend Engineering: What You Need to Know Before Building in Financial Services

NorfolkD — Sat, 27 Jun 2026 20:10:21 +0000

Most frontend engineers entering fintech underestimate how much the domain changes what good looks like. It's not just stricter security requirements or more complex forms. The regulatory, compliance, and payments context fundamentally reshapes how you architect UI, how you reason about state, how you handle errors, and what "done" means.

This post is a reference for frontend engineers — particularly those operating at staff level, where you're expected to contribute credibly beyond UI concerns — moving into or deeper into fintech. It covers the conceptual terrain: compliance constraints, payments flows, and the architectural patterns that emerge from them.

Why Domain Fluency Matters at the Frontend Layer

At staff level, you're expected to make architectural decisions that won't rot under you. In fintech, those decisions carry regulatory surface area. A poorly designed state machine for a payments flow isn't just a UX bug — it can result in double charges, incomplete settlements, or audit failures.

Frontend engineers who treat fintech as "the same job with stricter validation" tend to build systems that handle happy paths correctly but crack under the domain's actual failure modes:

Idempotency violations from optimistic UI updates
Race conditions between transaction state and UI state
Accessibility failures that violate regulatory obligations (WCAG is a legal requirement in financial services in several jurisdictions)
Audit trail gaps caused by insufficient event logging at the client layer

Domain fluency means you can anticipate these failure modes before they're filed as incidents.

The Compliance Layer Is an Architectural Constraint

In most product domains, compliance is a checklist you run through late in a feature cycle. In fintech, it's a first-class architectural input.

KYC and KYB Flows

Know Your Customer (KYC) and Know Your Business (KYB) verification flows are often the first complex frontend engineering problem you'll encounter. They look like multi-step forms, but they behave like state machines with external dependencies.

A KYC flow typically involves:

Document collection (government ID, proof of address)
Submission to a third-party verification provider (e.g., Persona, Onfido, Jumio)
Asynchronous verification (taking minutes to days)
Status polling or webhook-triggered state transitions
Remediation loops for rejected submissions

The frontend architecture needs to handle the async nature explicitly. A naive implementation that treats verification as a synchronous form submission will fail badly. You need a durable state model:

type KYCStatus =
  | { stage: 'not_started' }
  | { stage: 'documents_pending' }
  | { stage: 'submitted'; submittedAt: string }
  | { stage: 'under_review' }
  | { stage: 'approved'; approvedAt: string }
  | { stage: 'rejected'; reason: string; retryAllowed: boolean }
  | { stage: 'manual_review' };

This discriminated union pattern forces every rendering path to handle every state explicitly. When the backend team adds a new status, TypeScript surfaces every unhandled case in the UI. In regulated flows, "we missed a status" is not an acceptable postmortem entry.

Audit Trails and Immutability

Regulatory frameworks — PCI-DSS, SOX, GDPR, FCA rules — often require that financial actions be attributable, timestamped, and non-repudiable. This has direct implications for how you design frontend event logging.

Client-side events that touch payment initiation, consent recording, or document submission should be:

Emitted as structured, typed events
Correlated with a server-side trace ID
Stored immutably (no update or delete semantics at the log layer)

This is not analytics. It's an audit trail. Design it accordingly.

Payments Flows: The State Machine Problem

A payments flow is a distributed state machine with multiple participants: the user, your frontend, your backend, and a payments processor (Stripe, Adyen, Braintree). The frontend's job is to accurately reflect state transitions that it does not fully control.

Idempotency and Optimistic UI

Optimistic UI — updating local state before server confirmation — is a standard pattern for improving perceived performance. In payments, it's dangerous without careful design.

Consider a "Pay Now" button. If a user taps it and the network is slow, they may tap again. Without idempotency keys on the backend and request deduplication on the frontend, you risk two charges.

The correct pattern:

const usePaymentSubmit = () => {
  const idempotencyKey = useRef(crypto.randomUUID());
  const [status, setStatus] = useState<'idle' | 'submitting' | 'success' | 'error'>('idle');

  const submit = async (paymentDetails: PaymentDetails) => {
    if (status === 'submitting' || status === 'success') return;
    setStatus('submitting');

    try {
      await initiatePayment({
        ...paymentDetails,
        idempotencyKey: idempotencyKey.current,
      });
      setStatus('success');
    } catch (err) {
      setStatus('error');
      // Do NOT reset idempotencyKey — allow retry with the same key
    }
  };

  return { submit, status };
};

The idempotency key persists across retries intentionally. If the first request succeeded but the response was lost in transit, a retry with the same key returns the original result rather than creating a second transaction.

Terminal vs. Non-Terminal States

Transaction states divide into terminal (no further transitions possible) and non-terminal (may still change). SETTLED and REFUNDED are terminal. PENDING and PROCESSING are not.

UI that treats a non-terminal state as final is incorrect. A payment showing PROCESSING needs a polling mechanism or a WebSocket subscription to eventually converge to SETTLED or FAILED. Users who close the browser and return need to see the current state, not a cached intermediate state.

Your state management layer needs to distinguish between local UI state and remote transaction state, and it needs a reconciliation mechanism:

// TanStack Query handles staleness and refetching cleanly
const { data: transaction } = useQuery({
  queryKey: ['transaction', transactionId],
  queryFn: () => fetchTransaction(transactionId),
  refetchInterval: (data) => {
    // Stop polling once we reach a terminal state
    const terminalStates = ['settled', 'failed', 'refunded', 'cancelled'];
    return data && terminalStates.includes(data.status) ? false : 2000;
  },
});

Regulatory UI Obligations

Accessibility Is Not Optional

In the UK, the Equality Act 2010 requires that financial services be accessible. In the EU, the European Accessibility Act came into full force in June 2025. In the US, the DOJ has increasingly cited WCAG 2.1 AA as the standard for ADA compliance in financial services litigation.

WCAG compliance in fintech is a legal obligation, not a nice-to-have. A payment form with poor focus management, missing ARIA labels on error states, or keyboard traps isn't just a bad experience — it's a liability.

For complex flows (multi-step forms, modal confirmation dialogs, dynamic error states), you need to:

Manage focus programmatically on step transitions
Announce dynamic content changes via aria-live regions
Associate error messages with their inputs via aria-describedby
Test with actual screen readers, not just automated scanners

Consent and Disclosure UI

Many financial actions require explicit, recorded consent: terms of service acceptance, fee disclosures, risk warnings. The UI patterns here are legally significant.

A pre-checked checkbox, an auto-dismissing modal, or a disclosure hidden below the fold can each invalidate consent in regulatory terms. These components need compliance review, not just product review.

When building consent components, treat the consent event as a domain event with a typed payload:

type ConsentEvent = {
  type: 'consent_recorded';
  userId: string;
  consentType: 'terms_of_service' | 'fee_disclosure' | 'risk_warning';
  documentVersion: string;
  timestamp: string; // ISO 8601
  ipAddress: string; // captured server-side
  userAgent: string;
};

The frontend initiates this event; the backend records it immutably.

Architecture Patterns That Emerge from Fintech Constraints

Strict Data Flow and Validation

Financial data has tight schemas. An amount field that accepts string when it should be number in minor currency units, or an ambiguously formatted date, can cause downstream failures in payment processing. Use Zod (or an equivalent schema library) to validate API responses at the boundary:

import { z } from 'zod';

const TransactionSchema = z.object({
  id: z.string().uuid(),
  amountMinorUnits: z.number().int().positive(),
  currency: z.string().length(3), // ISO 4217
  status: z.enum(['pending', 'processing', 'settled', 'failed', 'refunded']),
  createdAt: z.string().datetime(),
});

type Transaction = z.infer<typeof TransactionSchema>;

This validation belongs at the API client layer, not scattered across components. When a backend team changes a field type, you catch it at the boundary — not in a production error report.

Feature Flagging and Progressive Rollouts

Financial features can't be safely rolled back mid-transaction. A user who has started a payment flow under version A of your app cannot safely complete it under version B if the flow structure has changed. Feature flags and cohort-based rollouts are therefore critical infrastructure, not optional.

Design new payment flows as entirely separate routes or experiences, keeping the old flow live until the rollout is complete and all in-flight transactions have resolved.

Sensitive Data Handling on the Client

Card numbers, bank account details, and government ID numbers should never pass through your application's JavaScript. Use iframe-based tokenization (Stripe Elements, Adyen Web Components) so sensitive data travels directly from the browser to the processor. Your app receives a token, not the raw data.

This isn't just a security best practice — it substantially reduces your PCI-DSS compliance scope.

What This Means for a Frontend Engineer in Practice

Building in fintech means accepting that:

Every flow has a failure mode that matters more than the happy path. Design for settled, failed, and pending, not just success.
State machines are load-bearing structures. Informal state management — boolean flags, nested conditionals — will break in a domain with this many states and transitions.
Compliance constraints are design constraints. Engage with them early, not at the end of a sprint.
The TypeScript type system is a compliance tool. Exhaustive unions and strict validation at API boundaries catch domain errors before they become incidents.

Frontend engineers who understand the domain can challenge product decisions, identify compliance risks in designs, and write code that reflects the actual semantics of financial operations. That's the difference between owning a UI layer and being a full contributor to a fintech product.

The investment in domain knowledge pays back quickly — and in fintech, the cost of not making it is measured in real money.

Prefer duplication over the wrong abstraction

NorfolkD — Tue, 23 Jun 2026 03:18:00 +0000

Sandi Metz wrote The Wrong Abstraction in 2016. It keeps resurfacing — in high-scoring HN threads, architecture Slack channels, and code review comments — whenever a team is staring at a function that started as a clean DRY consolidation and has since acquired seven parameters, three feature flags, and a comment that says # don't touch this.

The core argument is simple: duplication is far cheaper than the wrong abstraction. Once you've built the wrong abstraction, you're not starting from a clean slate — you're inheriting someone else's sunk cost, and every new requirement gets jammed into a shape that doesn't quite fit.

I've spent a lot of time at the intersection where this matters most: design systems, editor foundations, and cross-team API contracts. These are exactly the contexts where the abstraction temptation is strongest — and where getting it wrong is most expensive.

Why the wrong abstraction is so easy to create

Abstractions don't usually start wrong. They start reasonable.

You have two components that render a card. They share 80% of their structure. You extract a Card component, parameterize the differences, and ship it. Six months later, Card has a variant prop with eight values, a withBorder flag, a compact prop, a headerSlot, and a suppressDefaultPadding escape hatch added by someone who needed the component to do something the abstraction never anticipated.

The problem isn't that the original extraction was wrong. The problem is what happened next: every new use case was treated as a reason to extend the existing abstraction rather than a signal to question whether the abstraction still fit.

Metz identifies the specific failure mode: the abstraction is not the thing itself, it's a theory about the thing. When the theory is wrong, new data doesn't correct it — it gets explained away by adding parameters.

The cost of inline duplication is lower than it looks

When two components share markup, the instinct is to extract immediately. But consider what you actually know at extraction time:

You know what the two existing callers need.
You don't know what the third caller will need.
You don't know which parts of the shared structure are incidentally similar versus structurally equivalent.

Incidental similarity is the trap. Two things can look identical for completely different reasons. A StatusBadge and a CategoryTag might render the same pill shape today. That doesn't mean they'll evolve together. Extracting them into a shared Pill component couples their evolution even if their domains have nothing in common.

Duplication, in this case, is not laziness — it's preserving optionality. Each component can change shape independently when its domain requirements diverge, which they will.

// Two components that look identical today
const StatusBadge = ({ status }: { status: OrderStatus }) => (
  <span className={`badge badge--${status}`}>{STATUS_LABELS[status]}</span>
);

const CategoryTag = ({ category }: { category: ProductCategory }) => (
  <span className={`badge badge--${category}`}>{CATEGORY_LABELS[category]}</span>
);

// Six months later, StatusBadge needs a tooltip and an ARIA live region.
// CategoryTag needs a remove button and a count indicator.
// The shared abstraction would now be a liability.

If you'd extracted a Pill component on day one, you'd now be untangling it. Instead, two independent components diverge cleanly.

When shared primitives are genuinely correct

None of this means "never abstract." The argument is about wrong abstractions, not abstractions generally. There's a category of shared code that genuinely belongs together: primitives that are structurally equivalent by design, not incidentally similar by coincidence.

In a design system, a Button component is a real abstraction. It exists because button behavior, accessibility semantics, focus management, and visual consistency are supposed to be uniform across every surface. The shared implementation isn't an accident — it's the point. When the design system updates the focus ring to meet WCAG 2.2 criteria, you want every button in the product to update from one change.

The test for a real abstraction is whether its callers are supposed to be coupled. If coupling them is a feature — consistent behavior, enforced constraints, centralized correctness — the abstraction earns its place. If coupling them is just an artifact of current visual similarity, it's a liability.

A useful heuristic for architecture reviews:

Does this abstraction encode a rule, or does it encode a coincidence?

A Button encodes a rule: interactive elements with this semantic role should behave this way. A Pill extracted from StatusBadge and CategoryTag encodes a coincidence: these two things look the same right now.

The parameter accumulation signal

You rarely see a wrong abstraction clearly at creation time. The signal appears later, in how the abstraction responds to pressure.

Right abstractions absorb new requirements gracefully. You add a new button variant: <Button variant="ghost">. The existing API handles it cleanly. The abstraction was modeling something real, and the new case fits the model.

Wrong abstractions resist new requirements. You need the card component to suppress its default padding in one specific context. There's no clean way to express that, so you add suppressDefaultPadding={true}. The prop name itself is a confession — it's not modeling a concept, it's punching an escape hatch through the existing model.

Parameter accumulation — especially boolean flags or parameters that only matter to one caller — is the clearest signal that an abstraction has outlived its theory.

// This function signature is a warning sign
function formatUserName(
  user: User,
  options: {
    includeTitle?: boolean;
    shortForm?: boolean;
    uppercaseLastName?: boolean; // added for the export feature
    omitMiddleName?: boolean;    // added for the badge component
    legalFormat?: boolean;       // added for contract generation
  }
): string

This function is doing five jobs. It's no longer a formatting function — it's a dispatch table that routes to five different formatting strategies based on flags. The right move is to inline the relevant logic at each call site, or to create five clearly-named functions that each do one thing.

The recovery path: inline before you re-extract

Metz's prescription is specific: when you recognize a wrong abstraction, don't refactor it — inline it. Copy the abstraction's code back to each call site, restore the parameters to their concrete values, delete the dead branches, and see what you actually have.

This is uncomfortable. It feels like moving backward. But what you get after inlining is the truth: the actual logic each caller needs, without the mediation of a theory that no longer fits.

From that position, you can see whether a new abstraction is warranted. Sometimes the call sites look very different after inlining — which tells you the old abstraction was hiding real divergence. Sometimes they look nearly identical — which means a better abstraction is now obvious, because you're working from real requirements rather than accumulated historical ones.

I've done this with editor extension configurations, design token resolution logic, and API response normalization layers. Every time, the inline step was the uncomfortable-but-necessary precondition for getting the abstraction right.

The cross-team dimension

At staff level, wrong abstractions have a social dimension that makes them harder to fix. When an abstraction is owned by one team and consumed by three others, inlining it requires coordination. The owning team has to be willing to let go of something they built. The consuming teams have to accept temporary duplication. Everyone involved has to resist the pull toward "let's just add another parameter."

This is where architecture reviews and RFCs earn their keep. The time to debate whether an abstraction is modeling the right thing is before three teams build on top of it — not after. A good RFC process forces the question: is this abstraction encoding a rule that should govern all callers, or is it encoding one team's current needs in a shape that will constrain everyone else later?

The answer isn't always to avoid the shared abstraction. Sometimes the shared primitive is genuinely the right call. But asking the question explicitly, with concrete examples of what future callers might need, catches a lot of wrong abstractions before they get adopted.

The actual takeaway

Metz's essay persists because it names something that's easy to see in retrospect and hard to see in the moment. The wrong abstraction feels like good engineering when you create it. It reduces line count, eliminates repetition, and looks clean. The cost shows up later, incrementally, as each new requirement gets shoe-horned in.

The discipline it requires is specific: resist the extraction until you understand what the shared structure actually represents. Duplicate freely when the similarity is incidental. Extract confidently when the abstraction encodes a real rule. And when you inherit something that's accumulated enough parameters to be unreadable, have the resolve to inline it before you try to fix it.

Duplication is recoverable. The wrong abstraction is a debt that compounds.

When an AI Agent Joins Your Yjs Room, Three Assumptions Break

NorfolkD — Sun, 21 Jun 2026 03:18:14 +0000

Wiring an LLM as a first-class Yjs peer is architecturally sound — but it invalidates three silent assumptions your collaboration stack already makes about peer symmetry: throughput, undo ownership, and presence cadence.

You've tuned a Yjs provider under real collaborative load. You know the feeling before you can name it — one heavy client starts lagging the room, presence updates stutter, and you end up adding a debounce somewhere and calling it done.

Now imagine that client generates text at 3,000 words per minute, never goes offline, and has its own awareness cursor.

That's not a sidebar feature. That's a new class of peer, and your collaboration architecture wasn't designed for it.

The Demo Is Real — But It Skips the Hard Parts

In April 2026, a working demo wired an LLM as a genuine server-side Yjs document peer — same transport as the human editors, same CRDT, its own awareness state. The implementation uses y-prosemirror and the standard awareness protocol directly. If you've shipped TipTap collaboration, you already have every dependency it needs.

The architecture is correct. Making the agent a server-side peer — rather than a client-side bolt-on posting diffs over a REST endpoint — gives you one convergence model instead of two, real presence semantics for the agent, and a clean separation between the LLM streaming layer and the document state layer.

But the demo establishes the peer model. It doesn't stress-test what happens to your existing assumptions once that peer is running.

The Silent Assumption Every CRDT Implementation Makes

Here it is — the assumption baked into the Yjs awareness protocol, the undo manager, and your backpressure strategy, the one nobody wrote down because it was always true until now:

All peers produce operations at roughly human speed.

Not identical speed. Human typists vary. But they land in the same order of magnitude. The entire design space — how often you broadcast awareness, how you scope undo history, whether you need per-peer rate limiting at the application layer — rests on that implicit contract.

An AI agent at 1,000–4,000 words per minute is 25–100× outside that range. It doesn't just stress your transport. It invalidates the mental model.

Here's what actually breaks.

1. Backpressure: The Chokepoint You Don't Have

A central OT server can throttle any client trivially — it's the authority, it controls the queue. A CRDT peer model has no natural chokepoint. That's the tradeoff you accepted when you chose Yjs, and it's usually fine because human peers self-limit.

An agent peer doesn't self-limit. Left unrestricted, its doc.transact() calls will flood the sync cycle and starve human-paced operations of their share of the convergence window. This is write starvation — the same class of problem as database concurrency — and it manifests as cursor lag and dropped presence updates for everyone else in the room.

The fix doesn't belong at the transport layer. It belongs between the LLM's streaming output and the Yjs document write:

// Token bucket between LLM stream and Yjs write
const agentBucket = new TokenBucket({
  capacity: 50,     // max queued ops
  refillRate: 10,   // ops per 100ms — keeps agent below human starvation threshold
});

llmStream.on('token', async (token) => {
  await agentBucket.consume(1);
  ydoc.transact(() => {
    ytext.insert(insertionPoint, token);
  }, agentOrigin);
});

The numbers are illustrative — tune them against your provider and room size. The point is that the rate limit lives at the application layer, scoped to the agent's origin, so human operations always get a guaranteed share of the convergence window regardless of how fast the model is generating.

This is also where the CRDT-vs-OT debate gets re-litigated in 2026. The peer model is still right for human collaboration. For AI agents specifically, you're adding a lightweight central constraint back in — not for correctness, but for fairness.

2. Undo History: The Origin Problem You Probably Already Have

y-undomanager scopes undo history by origin. This is correct behavior and it's documented. But "correct" and "deliberate" aren't the same thing.

If the agent's operations share an origin with the user's, Ctrl+Z becomes a coin flip. If the agent gets its own origin — which it should — you now have a second question: should user-facing undo ever surface agent operations, and if so, in what order relative to the user's own history?

There's no universal answer, but there is a clear principle: give the agent a separate UndoManager with its own trackedOrigins, and expose agent-undo as a distinct UI affordance, not the default Ctrl+Z path.

const userUndoManager = new Y.UndoManager(ytext, {
  trackedOrigins: new Set([userOrigin]),
});

const agentUndoManager = new Y.UndoManager(ytext, {
  trackedOrigins: new Set([agentOrigin]),
});

// User's Ctrl+Z only touches userUndoManager.
// "Reject AI suggestion" calls agentUndoManager.undo().
// These stacks don't interfere.

This is the same design decision you face when adding comment marks or tracked-change marks to ProseMirror — marks that describe content rather than being content need a separate lifecycle from marks the user controls directly. The agent peer is the document-level version of that same pattern.

If you've ever had a user accidentally undo a comment thread someone else left, you've already felt this problem. The fix is the same: make the ownership boundary explicit at the manager level, not implicit in a if (origin === agentOrigin) return buried in a command handler.

3. Presence and Awareness: Coalesce or Drown

The awareness protocol was designed for human-paced cursor updates. A few broadcasts per second per peer is normal; the rendering layer handles it fine.

An agent generating 3,000 wpm produces position changes at a rate no human can visually process. Broadcasting all of them is noise on the wire and in the React render cycle.

Two things to do. First, coalesce awareness updates on a fixed interval for agent peers — not per-operation:

let pendingAwarenessUpdate: ReturnType<typeof setTimeout> | null = null;

function updateAgentAwareness(pos: number) {
  if (pendingAwarenessUpdate) return;
  pendingAwarenessUpdate = setTimeout(() => {
    provider.awareness.setLocalStateField('cursor', { anchor: pos, head: pos });
    pendingAwarenessUpdate = null;
  }, 300);
}

Second, add a type field to the agent's awareness state so the rendering layer can distinguish it from a human cursor without conditional logic scattered across components:

provider.awareness.setLocalState({
  type: 'agent',
  streaming: true,
  name: 'AI Assistant',
  cursor: { anchor: insertionPoint, head: insertionPoint },
});

"AI is writing" and "another person is typing" are different affordances. They deserve different visual treatments and different update rates. Encoding that distinction in the awareness state lets the rendering layer make the right call in one place.

What This Means for Your RFC

The agent-as-peer pattern is the right architecture. Connecting the LLM to Yjs is not the hard part.

The hard part is going back through every assumption your collaboration system makes about peer symmetry and making those assumptions explicit — so you can break them deliberately for the agent peer without breaking them for everyone else.

Concretely: your backpressure strategy assumed no single peer can dominate the convergence cycle, so it needs an application-layer token bucket scoped to the agent's origin. Your undo history assumed all tracked origins belong to the user, so the agent needs a separate UndoManager surfaced as a distinct UI action. Your awareness rendering assumed cursor updates arrive at human speed, so agent presence needs coalescing and a type discriminant in the awareness state.

None of these are hard to implement once you've named them. The risk is shipping the integration without naming them and finding the failure modes through user reports six weeks later when the collaborative load is real and the undo history is a mess.

Treat rate limiting, undo isolation, and presence coalescing as first-class line items in the RFC. Not edge cases caught in code review.

The April 2026 demo and companion repo are at electric.ax/blog/2026/04/08/ai-agents-as-crdt-peers-with-yjs. The y-prosemirror + awareness setup maps directly onto a TipTap stack — worth reading alongside the Yjs UndoManager docs if you're planning the integration.

Why this, why now: The April 2026 demo is the first working implementation of the agent-as-Yjs-peer pattern on a production-equivalent stack (y-prosemirror, awareness protocol, Durable Streams), and it landed just weeks ago. The "agent velocity problem" it surfaces is genuinely new — CRDT literature has no prior answer for asymmetric peer throughput at this scale — and every team currently building collaborative AI editing features will hit the same three failure modes. Writing this now, before the pattern calcifies into bad defaults, is exactly the right time.

Global Precision & Financial Calculations

NorfolkD — Sat, 30 May 2026 02:17:28 +0000

Global Precision and how it could impact the financial calculations

When you're building anything that handles money, someone eventually asks:
"how many decimal places should we use?" The tempting answer is to pick a
number — 2, or maybe 5 to be safe — set it globally, and move on. It feels
like a reasonable call. It's not.

I've debugged precision bugs that traced back exactly to this decision.
Once you understand why a single global precision fails, you can't unsee it.

The core problem is that different parts of a financial system have genuinely
different precision requirements, and treating them the same introduces errors
at the boundaries.

Billing calculations that appear on invoices need 2 decimal places. That's
cent precision. That's what customers see, what they're charged, what appears
on the contract. Showing 4 decimal places here is wrong for a different reason —
you're creating a number that can't be represented in any real currency.

Analytics calculations — revenue attribution, cohort aggregations, lifetime
value — need more precision. When you're summing thousands of transactions
before producing a final figure, rounding to 2 places at each step accumulates
error that compounds in ways that matter at scale.

Internal calculations — intermediate values mid-computation — should use the
highest precision you can reasonably sustain, precisely because they feed into
further operations. Rounding early and then doing arithmetic on the rounded
value is one of the most common sources of financial calculation bugs I've
encountered.

If you apply a global setting, you're either truncating precision your
analytics pipeline actually needs, or you're putting 4-decimal numbers on
customer invoices. Neither is acceptable.

The model that works is precision as an explicit input to each domain calculator,
with sensible per-domain defaults:

type PrecisionConfig = {
  internalCalcPlaces: number;
  displayPlaces: number;
  storagePlaces: number;
};

const BILLING_PRECISION: PrecisionConfig = {
  internalCalcPlaces: 5,
  displayPlaces: 2,
  storagePlaces: 2
};

The engine computes everything at internal precision. It rounds to display
or storage precision only when producing output — at the domain boundary,
not in the middle of a calculation chain.

This brings us to what I think is the subtlest and most consequential mistake
in financial arithmetic: rounding order.

Consider a line item. Unit price $10.333..., quantity 3, 10% discount.

Round early: you get $10.33 × 3 = $30.99, apply discount, round to $27.89.

Round late — maintain full precision through the chain: $10.333... × 3 × 0.9 = $27.899...,
round only at output: $27.90.

One cent difference on one line item. Across a large pricing table with currency
conversion also in the chain, accumulated rounding error is real, customer-visible,
and extremely difficult to debug once it's in production — because the bug is
in the order of operations, not in any individual calculation.

Round at output boundaries. Never in the middle of a computation chain.

Currency conversion adds another layer to this. Rates are typically 4–6 decimal
places. If you convert and immediately round to 2 decimal places before doing
further arithmetic, you've thrown away precision you needed. Convert at full
internal precision, display-round last.

And never convert and re-convert. Round-trip currency conversion
(USD → EUR → USD) with intermediate rounding will not give you back the
original number. If any part of your system displays a converted value and
then uses that displayed value in further calculation, you have a latent
bug waiting for the right combination of exchange rate and amount to surface it.

The practical steps are straightforward: define precision per domain, make
it an explicit parameter rather than global configuration, add a lint rule
that forbids raw Number arithmetic in your calculation package, and treat
output boundaries as the one and only place where rounding is allowed.

It sounds like ceremony until you've spent a day debugging a $0.01 discrepancy
on a $50,000 contract that a customer has already signed and is asking why
the numbers don't match.

Precision bugs that involve accumulated rounding are the hardest to reproduce
consistently — they depend on exact input combinations and operation order.
Has anyone built regression suites specifically for these? Property-based
testing feels like the right tool but I'm curious what others have actually shipped.

Pricing logic feels boring until it's wrong.

NorfolkD — Thu, 21 May 2026 03:03:11 +0000

Build it like infrastructure from day one.
Most pricing engines are built wrong. Here's what I'd do instead.
If you're building a CPQ product — or any SaaS tool where users configure and price deals — your pricing logic is probably living in the wrong place.
It's in a component. Or a utility function called from three different places. Or worse, duplicated between your frontend table renderer and your backend invoice service, silently drifting apart until a customer notices the numbers don't match.
I've thought a lot about how to architect this properly. Here's what I'd do.

First: treat pricing as infrastructure, not a feature
The moment you have billing frequency, line-item discounts, currency formatting, and tax rules composing together, you don't have a utility anymore. You have a domain. It deserves its own package, its own test suite, and its own ownership.
A shared @your-org/pricing-engine package — published internally, consumed by your frontend, your backend, and your export pipeline — means one place where

unitPrice × quantity × frequency = subtotal

is defined. Not three.
Why does this matter in practice? Consider this scenario:
A sales rep quotes a client €90/month per seat for a SaaS tool, after a 10% discount, converted from USD. That number needs to be:

Identical in the live proposal table the rep is editing
Identical in the PDF the client downloads and signs
Identical in the invoice the billing system generates on day one
Identical in the revenue report the finance team pulls at month end

If your frontend, your PDF export service, and your billing backend each have their own implementation of applyDiscount() and convertCurrency(), you will eventually have a discrepancy. Not maybe. Eventually.

Never use floating-point arithmetic for money. Ever.

0.1 + 0.2 === 0.30000000000000004

This isn't a JavaScript quirk. It's IEEE 754 — the way binary floating-point works at a hardware level. And it will silently corrupt your customer invoices.
A real example of how this surfaces: a pricing table with 7 line items, each with a percentage discount and a currency conversion applied. By the time you sum those rows, the float drift compounds. Your table shows $1,200.00. Your invoice says $1,199.99. Your customer notices. Your support team gets a ticket. Your engineers spend a day debugging something that was never going to work correctly.
Use decimal.js or equivalent to it. Treat it as a hard rule, not a code style preference. Decimal arithmetic is slower — negligibly so at any realistic pricing table scale. There is no valid argument for floating-point in customer-facing money calculations.

Keep your engine pure
A pricing engine should be a pure function:

inputs → outputs

No Redux. No React. No HTTP calls. No side effects. Just data in, calculated data out.
What the engine looks like from the outside

const result = computeTablePricing({
  rows: [
    {
      id: "row-1",
      unitPrice: new Decimal("100.00"),
      quantity: new Decimal("5"),
      billingFrequency: "monthly",
      discount: { type: "percentage", value: new Decimal("10") }
    }
  ],
  currency: { code: "EUR", symbol: "€", symbolPosition: "front", decimalPlaces: 2 },
  settings: { taxRate: new Decimal("0") }
});

// result.rows["row-1"].subtotal === Decimal("450.00")
// result.frequencyTotals.monthly === Decimal("450.00")
// result.grandTotal === Decimal("450.00")

This matters more than it sounds. A pure engine:

Runs identically on web, server, React Native, and in a unit test
Can be validated against your old implementation in shadow mode before touching production
Can be reasoned about without understanding your component tree
Can be tested with plain input/output assertions — no mocking, no rendering, no Redux store setup

The billing frequency problem — a concrete example of why this matters
Let's say you want to add billing frequency to your pricing table. Line items can be one-time, monthly, or annual. The footer should show a subtotal per frequency group.
In a component-centric architecture, you add grouping logic to your table renderer. Then you realize your PDF export also needs frequency subtotals, so you add it there too. Then billing needs it. Three implementations. Three places to get out of sync.
With an engine, billing frequency is just a first-class input field on each row:

billingFrequency: 'one-time' | 'weekly' | 'monthly' | 'quarterly' | 'annual'

The engine computes frequency subtotals as outputs. The table reads them. The PDF reads them. The billing service reads them. Same numbers everywhere, because it's the same function.

The discount composition problem — where things really break
Discounts are where scattered pricing logic becomes a genuine product risk.
Consider what a real CPQ discount model looks like:

A rep can apply up to 10% at line-item level without approval
Anything above 10% needs manager sign-off
There's a volume discount: 5+ seats get an additional 5% off
There's a seasonal promotion: 15% off annual plans in Q4
These can stack — but only in specific combinations

If discount logic lives in your table component, how does your catalog apply the same rules? How does your billing service validate that the agreed discount is still applied at invoice time? How do you write a unit test for the approval threshold without rendering a table?
The answer is: you can't, cleanly. You end up with discount logic scattered across five files, each with slightly different behavior.
In an engine architecture, discount application is a shared rule:

// shared/discount-application.ts
export function applyDiscount(
  baseAmount: Decimal,
  discount: { type: 'percentage' | 'fixed'; value: Decimal }
): { discountedAmount: Decimal; discountAmount: Decimal } {
  const discountAmount =
    discount.type === 'percentage'
      ? baseAmount.mul(discount.value).div(100)
      : discount.value;

  return {
    discountedAmount: baseAmount.minus(discountAmount),
    discountAmount
  };
}

One function. Tested once. Used by the table calculator, the catalog calculator, the billing service, and the approval workflow validator. Identical behavior everywhere by definition.

The feature composition problem — this is the real ceiling
Individual features are manageable. The problem is when they compose.
A line item that has:

Billing frequency: monthly
Discount: 10% off
Currency: EUR, converted from USD at current rate
Tax: 20% VAT applied after discount

...needs to produce exactly the same number in your live editor, your PDF, your invoice, and your analytics pipeline. Every combination of features multiplies the number of cases where scattered logic can diverge.
This is what actually blocks CPQ roadmaps. Not any individual feature — the combinatorial explosion of feature interactions when your calculation logic is spread across the codebase.

Let your state layer stay clean
In a Redux architecture, the pattern that actually works:

Redux stores confirmed inputs only (what the user committed — prices, quantities, discounts, frequencies)
Selectors derive all calculated values by passing those inputs through the engine
Components never calculate — they only display

// selector reads inputs from Redux, derives outputs via engine
const selectTablePricingResult = createSelector(
  [selectTablePricingInputs],
  (inputs) => computeTablePricing(inputs) // pure function, memoized automatically
);

This eliminates an entire class of bugs where your displayed subtotal disagrees with what gets saved, invoiced, or exported. The Redux store is always clean data. Derived values are never persisted. There is no ambiguity about whether a stored subtotal field is a user input or a computed value — a distinction that causes real bugs in collaborative editing and undo/redo flows.

The migration play — how to get there without breaking production
If you're refactoring an existing system rather than greenfielding, shadow mode is your best friend.
Run the new engine in parallel with your old implementation. For every calculation your old code produces, the engine produces the same calculation independently. Log any divergence. Ship zero user-facing changes until the outputs match exactly — across every row type, every discount combination, every currency, every edge case you can throw at it.
Silent arithmetic regressions on customer invoices are not a recoverable situation. Shadow mode gives you mathematical certainty before you flip the switch.
The sequencing I'd recommend:

Engine package first — pure functions, no UI changes, full test coverage
New features through the engine — billing frequency, discounts, anything net-new goes through the engine from day one, minimizing regression risk on existing behavior
Shadow mode on existing features — validate the engine matches current behavior exactly
Migrate existing consumers — replace old calculations one surface at a time, behind a feature flag
Remove the old code — only after full coverage and monitoring confirms correctness

What this unlocks long-term
Once you have a pure, shared pricing engine, a lot of things that were hard become straightforward:

Backend adoption: Your invoice service imports the same npm package your frontend uses. Calculation discrepancies between frontend and backend become structurally impossible
Mobile: React Native consumes the same engine. No separate mobile pricing logic
Analytics: Revenue reports use the same calculation rules as the proposals that generated the revenue
Formula engine: User-programmable pricing formulas

(=quantity * unitPrice * (1 - discount))

become an extension of the engine, not a rewrite of it.

The point
Pricing logic feels boring until it's wrong. Build it like infrastructure from day one — pure, shared, tested, and decoupled from your UI layer. The payoff isn't visible immediately. It's visible when your fifth pricing feature composes correctly with your first four without a single edge case meeting.
Have you tackled pricing complexity at scale? Curious what patterns have worked — especially around currency and tax.