DEV Community: DimiDan

React Server Components - The Mental Model Shift

DimiDan — Mon, 20 Jul 2026 14:22:05 +0000

React Server Components are not a performance trick. They are not a simpler way to do SSR. They represent a genuine renegotiation of where computation lives in a React application — and if you approach them as an incremental upgrade, you will architect yourself into corners that are painful to escape.

After working through RSC adoption in production Next.js applications, I want to lay out what actually changes at the architectural level: data fetching patterns, bundle composition, state management boundaries, and how teams need to think about component ownership.

How Shift did happened

Before RSC, the React component tree was a client-side concept. Server rendering was a serialization step — you ran the same component code on the server, emitted HTML, then React rehydrated it on the client. The component tree was fundamentally one thing that happened to run in two places.

RSC breaks this. The component tree now has two genuinely distinct zones with different capabilities, different execution environments, and a one-way data boundary between them. Server Components run exclusively on the server. They can access databases, filesystems, and secrets directly. They never ship to the browser. Client Components are the subset of your tree that runs in the browser — they receive serialized props from the server boundary and manage their own state and effects.

The key constraint is that this boundary is not symmetric. You can compose Client Components inside Server Components by passing them as props (including children). You cannot import a Client Component into a Server Component and expect it to remain a Client Component — it gets treated as a Server Component unless explicitly marked with 'use client'. And you cannot import a Server Component into a Client Component at all.

This asymmetry has real architectural consequences.

Data Fetching: Colocation at Scale

The most immediate change is to data fetching strategy. In a pre-RSC Next.js app, data fetching was pushed to page boundaries — getServerSideProps, getStaticProps, or client-side fetches with TanStack Query. Components deep in the tree couldn't fetch their own data without either prop-drilling from a page or reaching for a client-side solution.

RSC removes that constraint. A deeply nested Server Component can fetch exactly the data it needs:

// app/dashboard/RecentActivity.tsx
// No 'use client' directive — this is a Server Component

import { getRecentActivity } from '@/lib/db/activity';

interface Props {
  userId: string;
}

export async function RecentActivity({ userId }: Props) {
  const activity = await getRecentActivity(userId);

  return (
    <ul>
      {activity.map((item) => (
        <li key={item.id}>
          <span>{item.label}</span>
          <time dateTime={item.timestamp}>{formatRelative(item.timestamp)}</time>
        </li>
      ))}
    </ul>
  );
}

This is genuinely useful. Components declare their own data dependencies. There is no prop-drilling waterfall through parent components that don't need the data. React can parallelize sibling server fetches.

But colocation at this level has an architectural cost: it distributes data access logic across the component tree. In large codebases, this creates pressure toward duplicated query logic, inconsistent caching behavior, and data layer concerns bleeding into rendering concerns. The discipline that kept data fetching at page or feature boundaries was a forcing function for clean separation.

The practical answer is a service or repository layer that Server Components call into — not raw database queries inside JSX files. This is not a new idea, but RSC makes it newly necessary to enforce.

Bundle Optimization Is Now Structural

The bundle benefits of RSC are real but understated. It is not just that dependencies don't ship to the client. The server/client boundary is the module graph split point.

Consider a rich-text editor scenario. You have a document viewer that renders stored content, and a document editor that allows mutation. Pre-RSC, both likely live in the client bundle because rendering document content requires the same parser/renderer used for editing. With RSC, the viewer becomes a Server Component that runs the parser on the server and emits HTML. The editor, which genuinely needs client interactivity, is a Client Component. The parser library ships to zero browsers for the view-only case.

This pattern — server for read paths, client boundary for write and interactive paths — maps cleanly onto a lot of B2B SaaS product structures. Dashboards, reports, document feeds: mostly reads. Editors, forms, collaborative tools: require client boundaries.

What changes architecturally is that bundle composition is now a first-class design decision, not a post-hoc optimization. When you create a component, you are deciding which execution environment it belongs to. That decision needs to be visible in your component design conventions, code review checklists, and module organization.

State Management Boundaries

State management under RSC requires explicit rethinking, not just adaptation.

The instinct to reach for Zustand or Redux for shared state runs into a hard constraint: stores initialize and live in the Client Component subtree. Server Components cannot access them. This is correct behavior — but it means you need a clear model for what kind of state lives where.

URL state — search params, filters, pagination — becomes a first-class citizen. Server Components can read URL parameters directly and use them to parameterize data fetches. This moves a lot of state that previously lived in client stores back to the URL, which improves shareability and reduces client-side complexity.

// app/invoices/page.tsx
import { InvoiceList } from './InvoiceList';

interface SearchParams {
  status?: 'paid' | 'pending' | 'overdue';
  page?: string;
}

export default async function InvoicesPage({
  searchParams,
}: {
  searchParams: SearchParams;
}) {
  const status = searchParams.status ?? 'pending';
  const page = Number(searchParams.page ?? '1');

  return <InvoiceList status={status} page={page} />;
}

Server-owned state — user session, feature flags, tenant configuration — can be fetched once in a root Server Component and passed down as props, or accessed directly in any Server Component that needs it, without a context provider.

Client state remains appropriate for: ephemeral UI state (hover, focus, open/closed), optimistic updates, real-time collaboration state (Yjs documents, presence), and anything that responds to user input before a server round-trip.

The architectural mistake to avoid is treating the client state layer as a cache for server data. TanStack Query handles this well, but under RSC the primary data loading path moves to the server. Client-side query caches are better scoped to mutations, optimistic updates, and cases where you genuinely need background refetching without a navigation event.

The Client Boundary as an API Contract

Every 'use client' directive is an interface declaration. The props a Client Component accepts are serializable data flowing from the server domain into the client domain. This is a meaningful constraint: you cannot pass functions (unless they are Server Actions), class instances, or non-serializable objects across this boundary.

Architecturally, this forces clarity. When you design a Client Component, you are defining what the server needs to provide — the same problem as API design. What is the contract, and who owns the schema?

For complex components, this pushes toward explicit prop types that mirror your data model, rather than passing rich objects and picking fields inside the component:

// Clear boundary contract — serializable, explicit
interface DocumentCardProps {
  id: string;
  title: string;
  status: 'draft' | 'published' | 'archived';
  lastEditedAt: string; // ISO string, not Date — must be serializable
  collaboratorCount: number;
}

'use client';

export function DocumentCard({
  id,
  title,
  status,
  lastEditedAt,
  collaboratorCount,
}: DocumentCardProps) {
  // interactive behavior, local state, event handlers
}

This is good discipline regardless of RSC. But RSC turns violations into runtime errors rather than code smell.

Team and Collaboration Implications

At the team level, RSC introduces a new axis of component ownership: server versus client. In organizations where backend and frontend responsibilities overlap — product teams owning full features end-to-end — this is largely positive. Engineers can write data access directly without an API contract mediation step.

In organizations with stronger frontend/backend splits, it creates friction. Server Components that access databases or internal services blur the ownership model. You need explicit team agreements about what Server Components are allowed to call and where the service boundary sits.

RFC-driven engineering practices help here. Before RSC adoption, it is worth writing down:

Which data sources Server Components may access directly versus through an API layer
Conventions for when client boundaries should be introduced (interactive features, real-time state, third-party SDKs)
How Server Actions fit into your mutation story alongside existing API routes
Testing strategy — Server Components require different test infrastructure than Client Components

What This Is Not

RSC does not eliminate the need for a client-side data fetching library. TanStack Query remains the right tool for mutation state, optimistic updates, polling, and any data that needs to stay fresh without a navigation event.

RSC does not make SSR obsolete. Streaming SSR and RSC are complementary. Suspense boundaries work across both.

RSC does not simplify everything. The dual execution model adds cognitive overhead. Developers need to reason about which environment their code runs in, what is available there, and where the serialization boundary sits. That cost is real and needs to be weighed against the benefits for your specific application.

Where It Lands

RSC is the most significant change to React's execution model since hooks. It draws a clear line through the component tree and assigns different capabilities to each side. The teams that will benefit most are those building data-heavy, read-path-dominant applications — dashboards, document tools, B2B reporting surfaces — where the separation between "fetch and render" and "interact and mutate" maps cleanly to the server/client split.

The architectural work is not in learning the API. It is in auditing your existing component and data fetching patterns, defining clear conventions for boundary placement, and communicating those conventions to your team before the codebase drifts into inconsistency.

Done deliberately, RSC moves meaningful computation server-side in a way that is maintainable at scale. Done reactively, it produces a confusing mix of fetching strategies, inconsistent boundary placement, and components that are harder to reason about than what you had before.

The paradigm is sound. The architectural investment is on you.

A Staff Engineer's Critical Look at AI Terminal Coding Assistants

DimiDan — Mon, 20 Jul 2026 14:01:09 +0000

Every few weeks a new AI coding assistant lands on Hacker News with a wave of "this changes everything" comments. OpenCode is the latest terminal-first entry in this space, and the demo looks compelling. But after spending real time with it on a production TypeScript codebase, I want to offer something more useful than another glowing first-impression post: an honest accounting of where these tools help, where they hurt, and what the design decisions of tools like OpenCode reveal about the tradeoffs you're actually accepting.

This isn't a hit piece. It's the kind of evaluation I'd want before spending two weeks integrating a tool into my workflow.

What OpenCode Is Actually Doing

OpenCode is a terminal UI (TUI) coding assistant that wraps an LLM with file-system access, shell execution, and a diff-apply loop. You describe a change in natural language, it reads context from your repo, generates code, and applies it. The pitch is that it stays in the terminal where many engineers already live, avoiding the context-switch to a browser-based chat interface.

The core loop is:

You provide a prompt
The tool reads relevant files (via its own heuristics or your explicit direction)
The LLM generates a diff or full file replacement
OpenCode applies the change and optionally runs a verification command

This is not fundamentally different from what Aider, Claude Code, or Cursor's agent mode do. The differentiation is in the UX layer, the model routing, and the assumptions baked into the context-gathering step — and those assumptions are where things get interesting.

The Context Problem Is Not Solved

The most critical failure mode for any agentic coding tool is context selection. If the model doesn't see the right files, it will generate plausible-looking code that violates your actual constraints — wrong types, ignored abstractions, duplicated logic.

OpenCode, like its peers, uses a mix of:

Git history and file recency
Import graph traversal
Keyword and embedding similarity search
Whatever you explicitly paste in

The problem is that in a real TypeScript monorepo — a Turborepo setup with shared packages, for example — the most important constraints often live outside the file being edited. Your Zod schema in packages/validation, your design token types in packages/tokens, your shared component API in packages/ui. These are the files that determine whether the generated code is actually correct.

When I asked OpenCode to extend a form component, it generated perfectly valid TypeScript that was completely inconsistent with the validation schema the form was bound to. It looked right. It compiled. It was wrong.

// What OpenCode generated — valid TS, wrong contract
type FormValues = {
  email: string;
  role: string; // Should be constrained to z.enum(['admin', 'member', 'viewer'])
};

// What the actual Zod schema required
const formSchema = z.object({
  email: z.string().email(),
  role: z.enum(['admin', 'member', 'viewer']),
});

The tool didn't know about the schema because it wasn't imported in the component file — it was injected via a form context provider three layers up. This is a structural limitation. The import graph traversal is shallow, and the tool has no model of React's runtime dependency patterns.

The Trust Gradient Problem

Here's a subtler issue that doesn't get enough attention: AI coding tools create an uneven trust gradient that's dangerous for code review culture.

When a junior engineer writes code, experienced reviewers bring appropriate skepticism. When an AI tool produces a clean, well-formatted diff with a tidy commit message, it looks more authoritative than it is. I've watched PRs get merged faster when they're AI-assisted because the surface presentation is polished. That's backwards.

AI-generated code requires more scrutiny in specific areas, not less:

Edge case handling: LLMs optimize for the happy path
Security boundaries: Input validation, authorization checks, secrets handling
Performance characteristics: N+1 queries, unnecessary re-renders, missing memoization
Long-term maintainability: Generated code often solves the immediate problem in a way that accumulates tech debt

If your team hasn't explicitly recalibrated review standards for AI-assisted code, do that before adopting any of these tools at scale.

Where Terminal-First Actually Wins

There is genuine value here. Terminal-first AI assistants are meaningfully better than browser chat for a specific category of tasks: exploratory refactoring with tight feedback loops.

Tasks like:

Migrating from one API shape to another across 40 files
Applying a consistent pattern (logging, error boundaries, analytics events) across many components
Converting a class-based module to functional with a known target shape

For these, the apply-verify-iterate loop in a terminal tool is faster than copy-pasting between a chat window and your editor. You stay in one context. You can run your test suite as the verification step. You see diffs without context-switching.

# This kind of workflow works well
opencode "Find all fetch() calls in src/ and wrap them with our
  httpClient utility from lib/http-client.ts, preserving error handling"

# Run tests as verification
npm test -- --watch=false

For mechanical, well-defined transformations with a narrow constraint space, these tools earn their keep.

The Autonomy Dial Is Set Wrong

Most of these tools default to too much autonomy. OpenCode will, by default, apply changes without a confirmation step if a verification command is configured and passes. That sounds reasonable until your verification command is npm run build and the generated code introduces a subtle runtime bug that doesn't surface at build time.

The right default is more conservative: show the diff, wait for approval, then apply. Autonomy should be opt-in per task, not a global opt-out. The tools that get this right — Cursor's agent mode with explicit step approval, Claude Code with its default confirmation prompts — feel fundamentally safer on anything touching production paths.

If you're evaluating OpenCode or similar tools, check the default autonomy settings before you start. Understand exactly what --auto-apply and equivalent flags are doing.

What a Staff Engineer Actually Wants From These Tools

After using several of these tools across real projects, here's what actually matters:

Respects existing conventions. The tool should read your ESLint config, your component patterns, your naming conventions — and follow them without being told explicitly every time. Most tools do this poorly.

Understands project-specific abstractions. If you have a useFormField hook or a DataTable component, the tool should use them, not generate a new implementation from scratch.

Doesn't hide complexity. Generated code should be readable and auditable. A clever solution that works but is hard to reason about is not a win.

Fails loudly, not silently. If the tool can't gather enough context to be confident, it should say so. Hallucinated-but-plausible code is worse than an honest "I don't have enough context for this."

Integrates with your existing feedback loop. Your test suite, your type checker, your linter — not a parallel system.

OpenCode scores well on the last point and poorly on the first two.

The Honest Verdict

OpenCode is a competent implementation of a tool category that is genuinely useful for a subset of tasks. It's not a reason to overhaul your primary workflow, and it's not a substitute for understanding your codebase.

Engineers who get real value from tools like this treat them as accelerators for well-scoped, mechanical work — not as autonomous collaborators on design decisions. The engineers who get burned are the ones who trust the polish of the output over the quality of the reasoning behind it.

Before adopting any AI coding assistant on a production team, answer these questions:

What is the verification gate before AI-generated code merges?
Have we updated code review expectations explicitly?
Do we have a clear list of task types where we won't use AI assistance — auth flows, payment logic, data migrations?
Can the tool understand our project-specific abstractions, or will it work against them?

If you can't answer those confidently, the tool will make things slower, not faster.

The promise of AI coding assistants is real. The current implementations require more critical evaluation than they typically receive.

GPT-5 and Convex Optimization: What the Claims Actually Mean for Engineering Tooling

DimiDan — Mon, 20 Jul 2026 13:58:44 +0000

GPT-5 and Convex Optimization: What the Claims Actually Mean for Engineering Tooling

A recent thread hit 482 points and 312 comments on the claim that GPT-5 has made meaningful progress on convex optimization problems that have been largely intractable for thirty years. The reaction split cleanly: researchers excited about specific benchmark results, engineers skeptical about practical implications, and a third camp arguing the framing was misleading from the start.

All three groups have valid points. Here's an attempt to untangle them.

What Convex Optimization Actually Is (And Why It's Everywhere)

Convex optimization is the class of problems where you minimize a convex function over a convex set. The key property: any local minimum is a global minimum. That makes convex problems tractable in a way that general optimization problems are not.

This shows up constantly in engineering infrastructure:

ML training — loss surfaces are often non-convex, but large subproblems (SVM training, certain regularization schemes) are convex and solved with specialized solvers like CVXPY or Gurobi
Compiler backends — register allocation and instruction scheduling have convex relaxations that inform heuristics
Resource allocation — cloud schedulers, network routing, and capacity planning often reduce to linear or quadratic programs
Financial modeling — portfolio optimization under constraints is a textbook convex problem

The "30-year gap" framing refers to open problems around scalability and solver efficiency — specifically, the gap between what interior-point methods can handle in theory and what's practical at production scale.

Solvers like MOSEK and SCS are excellent. They're also slow at scale, sensitive to problem conditioning, and require expert formulation. That last point is the friction that actually matters for engineering teams.

What the GPT-5 Results Actually Show

The specific claims center on GPT-5's ability to:

Correctly formulate optimization problems from natural-language descriptions
Identify when a problem has convex structure that allows efficient solving
Generate CVXPY or similar solver code that compiles and runs correctly
In some benchmarks, suggest reformulations that meaningfully improve solver performance

This is not "GPT-5 solved convex optimization." It's closer to: GPT-5 has become a competent co-pilot for the formulation step, which is where most engineering time actually goes.

To make this concrete — if you're building a job scheduler and need to minimize total latency subject to resource constraints, writing that as a proper LP or QP has always required knowing the vocabulary: decision variables, objective function, constraint matrices. That knowledge barrier is real. Most backend engineers reach for heuristics not because an optimal formulation wouldn't be better, but because they don't want to spend three days reading Boyd and Vandenberghe.

# What you used to need domain knowledge to write:
import cvxpy as cp
import numpy as np

# Job scheduling: minimize makespan across n jobs, m machines
n_jobs, n_machines = 10, 3
processing_times = np.random.randint(1, 10, (n_jobs, n_machines))

x = cp.Variable((n_jobs, n_machines), boolean=True)
makespan = cp.Variable()

constraints = [
    cp.sum(x, axis=1) == 1,  # each job assigned to exactly one machine
    makespan >= cp.sum(cp.multiply(processing_times, x), axis=0)
]

objective = cp.Minimize(makespan)
problem = cp.Problem(objective, constraints)
problem.solve()

GPT-5 can now generate that correctly from a plain-English description of the scheduling problem. More importantly, it can flag when you've accidentally written a non-convex constraint that will cause the solver to fail silently or return garbage.

The Skepticism in the Thread Is Legitimate

The 312-comment thread wasn't just noise. The pushback clustered around several real concerns.

"Benchmark performance doesn't transfer to production problems." True. The benchmarks use well-conditioned, textbook-scale problems. Real scheduling problems have messy side constraints, integer variables, and numerical conditioning issues that stress even expert formulations. GPT-5 generating plausible-looking CVXPY code is not the same as that code solving your actual problem.

"This conflates formulation assistance with algorithmic progress." Also true. The headline "closing a 30-year gap" implies progress on solver algorithms — faster interior-point methods, better preconditioning, novel dual decompositions. That's not what's being described. What's being described is better tooling around using existing solvers. Valuable, but a different category of claim.

"LLMs hallucinate constraints." This is the one that should give you pause before deploying any of this. GPT-4 can generate convex-looking constraint sets that are subtly non-convex — the kind of error that doesn't throw an exception, but silently returns a wrong answer. GPT-5 is better at catching these, but "better" doesn't mean "safe to run unsupervised in a production resource allocator."

The honest framing: this is a significant improvement in the accessibility of optimization tooling, not a breakthrough in optimization theory.

What This Actually Changes for Engineering Teams

If you're building backend infrastructure, developer tooling, or any system that currently uses heuristics because "setting up a proper solver seemed like too much work," the calculus has shifted.

The formulation barrier is lower. You can describe your problem in prose, get a working CVXPY sketch, and iterate from there. That's genuinely useful even if you still need to validate the output carefully.

Debugging solver failures is faster. Infeasibility and numerical issues in optimization problems have always been hard to diagnose. Having a model that can look at your problem and say "this constraint is likely causing infeasibility because X" cuts debugging time substantially.

The integration surface with existing infrastructure is unchanged. CVXPY still calls MOSEK or SCS. Solver performance characteristics are the same. If your problem is too large for current solvers, GPT-5 doesn't fix that. You still need decomposition, approximation, or a different approach.

For teams building scheduling systems, ML infrastructure, or resource allocation layers — say, a Node.js/TypeScript backend calling out to a Python optimization service — the practical win is in prototyping speed and reducing the expertise required to reach a working formulation.

// A backend service that now has a shorter path to proper optimization
// instead of a hand-rolled heuristic
async function scheduleJobs(jobs: Job[], machines: Machine[]): Promise<Assignment[]> {
  // Previously: greedy heuristic because writing the LP felt like too much
  // Now: call a Python optimization service with a properly formulated problem
  // generated and validated with AI assistance
  const formulation = await optimizationService.solve({
    type: 'linear_program',
    objective: 'minimize_makespan',
    jobs,
    machines,
  });
  return formulation.assignments;
}

Where to Be Careful

A few concrete cautions before building this into critical infrastructure.

Always verify the problem class. If the model says your problem is convex, check it. A non-convex problem handed to a convex solver will either fail noisily or return a locally optimal point far from the global optimum. In a scheduler or resource allocator, that has real consequences.

Numerical conditioning still requires human attention. LLMs generate well-scaled constraint matrices for textbook problems. Your production problem has characteristics the model hasn't seen. Check condition numbers. Know your solver's tolerance settings.

Don't skip domain expert review. The formulation step is where domain knowledge matters most — not just mathematical correctness, but whether the optimization objective actually captures what you care about. GPT-5 can give you a mathematically valid LP that optimizes the wrong thing because it misunderstood a business constraint.

The Actual Opportunity

The real engineering opportunity here isn't "replace your solver with GPT-5." It's closer to: a class of infrastructure problems previously gated behind specialized knowledge is now more accessible to generalist engineers.

That has compounding effects. Teams that previously used greedy heuristics because the optimization setup cost was too high can now prototype proper formulations. Those prototypes, even if they need expert refinement, start from a better place than a hand-rolled approximation.

For developer tooling specifically — compilers, build systems, deployment schedulers — this opens up experimentation with optimization-based approaches that teams routinely deprioritized because of implementation cost.

The 30-year gap in optimization theory hasn't closed. But the gap between optimization theory and something an engineering team can actually use got meaningfully smaller. That's a more modest claim than the headline suggested — but it's a real one, and it's worth taking seriously.

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

DimiDan — 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

DimiDan — 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

DimiDan — 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

DimiDan — 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.

DimiDan — 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.