DEV Community: Parvej Shah

The Stack I Keep Coming Back To and Why I Stop Reconsidering It

Parvej Shah — Wed, 26 Aug 2026 20:34:30 +0000

Originally published at parvejshah.com/blog/craft-of-high-velocity-software-delivery by Parvej Shah.

There's a specific state of mind that a developer can get into where evaluating new tools feels productive. You read release notes, benchmark comparisons, and Twitter threads from early adopters. You build proof-of-concepts. You track GitHub stars and Hacker News reception. This can occupy a significant fraction of your available thinking time.

The output from this activity is rarely a better product. It's usually a well-informed decision to continue using what you were already using.

I've been building full-stack web applications across projects ranging from EdTech platforms to enterprise workforce dashboards to real-time telephony systems. I've done this primarily with PostgreSQL, TypeScript, and Next.js. I keep coming back to this combination — not because I haven't evaluated alternatives, but because I've evaluated enough alternatives to understand what I'd actually be trading.

What "Boring Technology" Means in Practice

The phrase "boring technology" gets misread as a preference for old or unsophisticated tools. That's not the point. The point is familiarity depth.

When I encounter a bug in a Prisma query at 11pm during a client deployment, I know where to look. I understand how Prisma generates SQL, what its transaction semantics are, how connection pooling behaves under load. This knowledge was accumulated across dozens of projects and hours of debugging. When I encounter a problem with an ORM I've used for three weeks, my diagnostic path is much longer.

PostgreSQL covers an enormous surface area of what applications actually need. Full-text search, JSON document storage, relational joins, atomic transactions, row-level security, triggers, recursive CTEs. Every application I've built eventually needed something that Postgres had native support for.

For MathPro Academy, we use PostgreSQL for course data, enrollments, payments, and streak tracking. The streak tracking required a SQL UPSERT with CASE logic that would have been genuinely awkward to implement correctly in most NoSQL databases. PostgreSQL handled it cleanly with a single atomic statement.

TypeScript is a net-positive before you're familiar with it and an unmistakable productivity multiplier after you are. The upfront cost — writing types for your data structures, understanding generics, configuring the compiler — is real. The payoff — catching a null access error at compile time instead of at 3am in a production error log — is also real.

The strictness setting matters. Running TypeScript with strict: false gives you type annotations without most of the safety. strict: true is uncomfortable initially and significantly better in practice.

Next.js solves the API/frontend split that used to require running and coordinating two separate development servers. API routes live in the same codebase as UI components. Server-side rendering and static generation are first-class primitives rather than configurations. The App Router's Server Components model — when you understand it — eliminates entire categories of client-side data fetching patterns that were always the wrong abstraction anyway.

The Real Velocity Driver: Short Feedback Loops

The biggest predictor of delivery speed on any project isn't the language or framework — it's the feedback loop length. How long does it take to go from writing code to knowing whether it works?

In a fast feedback environment:

The development server reflects file changes in under 500ms.
Type errors appear in the editor as you type, not on the next build.
Database schema changes are applied with a single command.
Deployment to staging takes under three minutes.

In a slow feedback environment:

Build times over 30 seconds create cognitive context loss between iterations.
Manual testing steps are required to verify basic functionality.
Deployment pipelines take 15 minutes, so you batch changes instead of shipping incrementally.

The specific tools matter less than whether you've configured them to minimize feedback latency. Turbopack's fast HMR, TypeScript's language server integration with VS Code, Prisma's db push for rapid schema iteration during development — these are the practical affordances that compound into meaningful time savings across a project.

Knowing What to Leave Out

The hardest and most valuable engineering skill is deciding not to build something.

Every feature you build is code that must be maintained, bugs that can occur, edge cases that must be handled, and cognitive load for future developers (often yourself). The features that get cut are free. The features that get built carry ongoing costs.

This applies to infrastructure choices too. Distributed message queues are powerful and complex. For a project where a single Postgres instance is adequate, the complexity of Redis and BullMQ is pure overhead. Microservices offer genuine benefits at scale. For a team of one to three developers building a product for a few hundred users, they introduce deployment complexity that serves no one.

The right time to add architectural complexity is when you have clear evidence that you need it. The evidence is usually a specific bottleneck, a specific scale requirement, or a specific capability gap — not a theoretical concern about future scale.

I've seen more projects slow down from premature architectural complexity than from inadequate infrastructure. A well-designed monolith on a managed Postgres database has shipped and maintained more valuable software than any number of elaborate distributed systems built for scale problems that never materialized.

The stack I keep coming back to isn't remarkable. It's just familiar, capable, and well-understood. That turns out to be enough.

Parvej Shah is a Lead Full-Stack Web Developer & Platform Architect based in Dhaka, Bangladesh. Explore full architecture case studies and production code at parvejshah.com.

What I Actually Had to Change When Moving to React Server Components

Parvej Shah — Wed, 26 Aug 2026 20:34:24 +0000

Originally published at parvejshah.com/blog/nextjs-16-turbopack-deep-dive by Parvej Shah.

When Next.js introduced the App Router with React Server Components, the mental model shift was more significant than the API change. The API changes are well-documented. The mental model shift is harder to articulate and easier to get wrong.

This is a practical account of what changed when building this portfolio site on Next.js 16 with Turbopack — which pages ended up as Server Components, which needed to be Client Components, and what the non-obvious boundary decisions looked like.

The Instinctive Wrong Move

The instinct when you hit a component that seems "complex" is to add "use client" to the top of the file. This works — the component now runs in the browser like it always did — but it often carries a hidden cost.

When you mark a parent component as a Client Component, every component it imports transitively becomes part of the client bundle too. If you've put "use client" on a layout component that imports your navigation, your blog post renderer, and your analytics component, you've just made all of those things client-side JavaScript even if none of them need interactivity.

The correct question isn't "does this component need to be a Client Component?" It's "what is the smallest leaf component that actually needs to run in the browser?"

The Actual Split on This Portfolio

Going through each section of the portfolio site with this question produced a clear pattern:

Everything in the blog system stayed as a Server Component. Blog posts fetch their content from PostgreSQL through Prisma. Markdown gets parsed and rendered. Cover images are served from the public directory. None of this involves user interaction. None of it changes based on client-side state. All of it is better handled on the server.

// This is a Server Component — no "use client"
// It runs at build time for static pages, at request time for dynamic ones

async function BlogPost({ slug }: { slug: string }) {
  const post = await db.post.findUnique({
    where: { slug, status: "PUBLISHED" },
    include: { coverImage: true },
  });

  if (!post) notFound();

  return (
    <article>
      <PostHeader post={post} />
      <MarkdownContent content={post.content} />
    </article>
  );
}

The navigation required a hybrid approach. The navbar is mostly static HTML, but it needs to highlight the active route — which requires knowing the current pathname, a client-side concern. The solution is to keep the navbar structure as a Server Component and extract only the active-state logic into a small Client Component.

// nav-link.tsx — Client Component (needs usePathname)
"use client";

import { usePathname } from "next/navigation";

export function NavLink({ href, children }: NavLinkProps) {
  const pathname = usePathname();
  const isActive = pathname.startsWith(href);

  return (
    <a href={href} className={isActive ? "text-emerald-400" : "text-slate-400"}>
      {children}
    </a>
  );
}

Forms are Client Components. The contact form and the admin dashboard forms require useState, onChange handlers, and submission logic. These are genuinely client-side concerns. Making them Client Components is correct.

Static Generation with Database Content

The blog posts and project pages are statically generated at build time. Next.js calls generateStaticParams to enumerate all the slugs, then pre-renders each page to static HTML.

export async function generateStaticParams() {
  const posts = await db.post.findMany({
    where: { status: "PUBLISHED" },
    select: { slug: true },
  });

  return posts.map(post => ({ slug: post.slug }));
}

When a new blog post is published through the admin interface, it triggers a Vercel deployment. The new build runs generateStaticParams, discovers the new slug, generates its static HTML, and deploys. The post goes live without any runtime database queries for future visitors.

One Actual Gotcha

There's a subtle issue with unstable_cache in Next.js when combined with static generation. The cache is keyed by the arguments you pass to it, but if you change the data in the database without triggering a new deployment, the cache will serve stale data indefinitely.

For content that changes through the admin interface, the admin routes that write to the database call revalidatePath or revalidateTag after each write, which purges the relevant cache entries. Without this, editing a blog post would update the database but leave the static HTML unchanged until the next deployment.

import { revalidatePath } from "next/cache";

async function updateBlogPost(id: string, data: PostUpdateData) {
  await db.post.update({ where: { id }, data });

  // Purge the static cache for this post's page
  revalidatePath(`/blog/${data.slug}`);

  // Purge the blog index page too
  revalidatePath("/blog");
}

This is the part that takes the most deliberate thought — not the Server/Client boundary, but the cache invalidation strategy. Get it right and content updates feel instant. Get it wrong and editors wonder why their changes aren't appearing.

Parvej Shah is a Lead Full-Stack Web Developer & Platform Architect based in Dhaka, Bangladesh. Explore full architecture case studies and production code at parvejshah.com.

How We Made Academic Certificates Verifiable Without a Blockchain

Parvej Shah — Wed, 26 Aug 2026 20:33:44 +0000

Originally published at parvejshah.com/blog/cryptographic-credential-verification-institutional-web by Parvej Shah.

When the Center for Policy Research on Business and Development (CPRBD) at the University of Dhaka approached us about building their institutional web portal, one requirement stood out immediately: certificate verification.

CPRBD runs executive education programs and professional certification cohorts for mid-career government officials and business professionals. Participants receive physical certificates signed by faculty from the University of Dhaka's Department of International Business. These certificates are used as credentials when applying for government positions, international postings, and senior roles.

The problem: nothing on the physical certificate was verifiable. An employer looking at a CPRBD Executive Certification had no way to confirm it was authentic. The certificate could have been genuine, fraudulently obtained, or simply printed on a good color printer.

Why HMAC Hashes Are Enough

The core requirement for certificate verification is this: given a certificate ID printed on the physical certificate, an employer should be able to query a public endpoint and receive confirmation that a specific person completed a specific program.

Blockchain solutions add tamper-evidence and decentralization. Both are useful properties in some contexts. For institutional certificate verification — where CPRBD controls the issuing authority and the verification endpoint — neither is necessary. The trust anchor is CPRBD's public-facing website, not a distributed ledger.

A simple HMAC hash is tamper-evident: it is computationally infeasible to produce a valid verification code without knowing the secret key, which only CPRBD's server holds.

function generateCertificateVerificationCode(
  certificateNumber: string,
  recipientName: string,
  programName: string,
  secretKey: string
): string {
  const payload = [certificateNumber, recipientName, programName]
    .join(":")
    .toLowerCase()
    .trim();

  return crypto
    .createHmac("sha256", secretKey)
    .update(payload)
    .digest("hex")
    .substring(0, 16)
    .toUpperCase();
}

Each certificate is issued with a verification code generated from its unique attributes: the certificate number, the recipient's name exactly as it appears on the certificate, and the program name. The code is printed on the certificate and embedded in a QR code that links directly to the verification page.

The Verification Endpoint

When an employer scans the QR code or enters the verification code manually, the endpoint performs the inverse: retrieve the certificate record by certificate number, recompute the verification code using the stored attributes, and compare to the submitted code.

async function verifyCertificate(
  certificateNumber: string,
  submittedCode: string
): Promise<VerificationResult> {
  const certificate = await db.certificate.findUnique({
    where: { certificateNumber },
    include: { recipient: true, program: true },
  });

  if (!certificate) {
    return { valid: false, reason: "Certificate number not found" };
  }

  const expectedCode = generateCertificateVerificationCode(
    certificate.certificateNumber,
    certificate.recipient.name,
    certificate.program.name,
    process.env.CERTIFICATE_SECRET_KEY!
  );

  const valid = crypto.timingSafeEqual(
    Buffer.from(expectedCode, "utf-8"),
    Buffer.from(submittedCode.toUpperCase().trim(), "utf-8")
  );

  if (!valid) {
    return { valid: false, reason: "Verification code does not match" };
  }

  return {
    valid: true,
    recipient: certificate.recipient.name,
    program: certificate.program.name,
    completionDate: certificate.completedAt,
    grade: certificate.grade,
  };
}

The endpoint responds in under 100 milliseconds and requires no authentication from the verifying party. It's intentionally public — anyone with a certificate number and verification code can confirm its authenticity. Only CPRBD can issue valid codes.

The Administrative Side

The less visible but equally important part of the platform is the administrative interface for cohort and certificate management. Program coordinators need to define cohorts, enroll participants, track attendance and completion, and issue certificates when participants meet the requirements.

We built the admin interface with a focus on bulk operations — importing participant lists from spreadsheets, issuing certificates to an entire cohort in a single action, and generating batch QR code PDFs for physical printing. The alternative — managing 60 participants in a form-based interface one at a time — was the previous workflow, and it took days.

The research publication repository was a separate section: structured metadata with attached PDF assets, full-text search, and a clean reading interface. University of Dhaka's Department of International Business has a significant body of published research, and the previous approach was a static list in a Word document on the university website. The structured repository made research discoverable and made CPRBD's intellectual output visible to policy practitioners and government stakeholders who otherwise wouldn't find it.

Parvej Shah is a Lead Full-Stack Web Developer & Platform Architect based in Dhaka, Bangladesh. Explore full architecture case studies and production code at parvejshah.com.

Designing the Learning Progression Engine Behind Codervai CP

Parvej Shah — Wed, 26 Aug 2026 20:33:38 +0000

Originally published at parvejshah.com/blog/scaling-competitive-programming-lms-architectures by Parvej Shah.

Competitive programming requires building a specific kind of knowledge: algorithms and data structures that compose with each other. You can't understand dynamic programming without first being solid on recursion. You can't reason about graph traversal without understanding how to implement a queue. The dependency tree is real, and the order in which concepts are introduced matters.

Codervai CP is a structured competitive programming learning platform. When we were designing its learning progression engine, the core product question was: how do you prevent students from jumping to advanced problems before they've built the foundational skills, without making the platform feel restrictive or condescending?

The answer we arrived at was timed module unlocking with a cohort schedule — not ability gating, which frustrates students who feel artificially held back, but temporal pacing, which mirrors how well-designed university courses work.

Module Unlock Logic

Each course cohort operates on a defined schedule: module 1 is available from day 0, module 2 from day 7, module 3 from day 14, and so on. Students who enroll on any day within the cohort window get access to the modules that have been released as of their enrollment date, and new modules unlock on the cohort's schedule going forward.

interface CohortModule {
  moduleIndex: number;
  unlockAfterDays: number;
  title: string;
  problemIds: string[];
}

function getAvailableModules(
  cohortStartDate: Date,
  modules: CohortModule[]
): CohortModule[] {
  const elapsedDays = Math.floor(
    (Date.now() - cohortStartDate.getTime()) / (1000 * 60 * 60 * 24)
  );

  return modules.filter(
    module => elapsedDays >= module.unlockAfterDays
  );
}

The cohort start date is fixed. All students in the cohort see the same modules on the same calendar days. This creates a shared experience — students are working on the same problems simultaneously, which drives community discussion and makes group study sessions more productive.

The Streak Concurrency Problem

Daily streaks are one of the most effective engagement mechanics in learning platforms. At Codervai CP, streaks are awarded for solving at least one problem per day. A student who maintains a 30-day streak has real motivation to protect it.

The concurrency issue is predictable: a significant fraction of streak activity happens near midnight, as students rush to maintain their streak before the day resets. This creates a burst of simultaneous database writes, and the naive implementation of streak tracking breaks under concurrent load.

Consider the naive approach:

// BROKEN: race condition when two submissions arrive simultaneously
async function updateStreak(userId: string): Promise<void> {
  const streak = await db.userStreak.findUnique({ where: { userId } });
  const today = new Date().toDateString();

  if (streak?.lastActiveDate.toDateString() === today) return;

  const yesterday = new Date();
  yesterday.setDate(yesterday.getDate() - 1);
  const wasActiveYesterday =
    streak?.lastActiveDate.toDateString() === yesterday.toDateString();

  await db.userStreak.upsert({
    where: { userId },
    create: { userId, currentStreak: 1, lastActiveDate: new Date() },
    update: {
      currentStreak: wasActiveYesterday ? streak!.currentStreak + 1 : 1,
      lastActiveDate: new Date(),
    },
  });
}

If two problem submissions from the same user arrive within milliseconds of each other, both threads execute the findUnique call before either has written. Both see the streak as needing an update. Both write. The streak increments by 2 instead of 1.

The correct solution is an atomic upsert at the database level using a raw SQL INSERT ON CONFLICT DO UPDATE with CASE logic:

async function recordActivityAndUpdateStreak(userId: string): Promise<void> {
  const today = new Date().toISOString().split("T")[0];

  await prisma.$executeRaw`
    INSERT INTO "UserStreak" ("userId", "lastActiveDate", "currentStreak", "updatedAt")
    VALUES (${userId}, ${today}::date, 1, NOW())
    ON CONFLICT ("userId") DO UPDATE SET
      "currentStreak" = CASE
        WHEN "UserStreak"."lastActiveDate" = (${today}::date - INTERVAL '1 day')
          THEN "UserStreak"."currentStreak" + 1
        WHEN "UserStreak"."lastActiveDate" = ${today}::date
          THEN "UserStreak"."currentStreak"
        ELSE 1
      END,
      "lastActiveDate" = ${today}::date,
      "updatedAt" = NOW()
    WHERE "UserStreak"."lastActiveDate" < ${today}::date;
  `;
}

The entire logic — check yesterday, check today, compute new streak — is a single atomic database operation. No application code reads a value and then writes a derived value. Concurrent calls for the same user will serialize at the database lock level without corrupting the streak count.

Video Walkthrough Quality

Editorial code walkthroughs on a competitive programming platform have a specific quality challenge: the content is code on a dark background. Standard video compression is optimized for natural scenes and photographs, and it performs poorly on text — blurring the fine details in syntax that make or break code legibility.

We encode video content in HLS with multiple quality tiers, but the top-tier encoding profile is configured explicitly for code content: higher quantization parameter limits for text regions, reduced temporal compression, and target bitrate that prioritizes sharp edges over smooth gradients.

The encoding configuration is a single FFmpeg preset that content creators run locally before uploading. The infrastructure side handles HLS segmentation and CDN distribution automatically. The hard part was getting the quality parameters right, which required testing the encoding against several monitors, devices, and network conditions to find settings that were legible under all conditions.

Parvej Shah is a Lead Full-Stack Web Developer & Platform Architect based in Dhaka, Bangladesh. Explore full architecture case studies and production code at parvejshah.com.

Building Software for Places Where the Internet Doesn't Work

Parvej Shah — Wed, 26 Aug 2026 20:32:59 +0000

Originally published at parvejshah.com/blog/offline-first-pwa-emergency-volunteer-networks by Parvej Shah.

Blood donor matching is time-sensitive in a way most software problems aren't. When a patient needs a specific blood type during a critical procedure, the medical team is working with a narrow window. The volunteer coordinator needs to identify available donors, contact them, and arrange a donation quickly.

Badhan is the blood donation organization of the Amar Ekushey Hall unit at the University of Dhaka, operating a volunteer donor network for the Dhaka Medical College Hospital. The donor management platform needed to be fast, usable by volunteers with varying technical experience, and — critically — functional in hospital environments where network connectivity is unreliable.

Anyone who has been inside a large hospital building knows the problem: thick concrete walls, basement floors, and dense building infrastructure create mobile dead zones. A web application that requires network connectivity to display a list of blood donors is simply not useful in these environments.

Offline-First vs. Offline-Capable

There's an important distinction between applications that are offline-capable and applications that are offline-first.

An offline-capable application handles the absence of network connectivity gracefully — it shows a cached version of content it previously loaded, or displays a "you're offline" message without crashing. This is the baseline minimum.

An offline-first application treats local storage as the primary data source. All reads come from local storage first. Network requests are used to synchronize local data with the server, not to serve the request. The application is fully functional without a network connection, not just tolerable.

For Badhan's use case, offline-capable was insufficient. If a volunteer could only search the donor directory online, the application would fail exactly when it was needed most.

The Data Synchronization Architecture

All donor records, blood group data, and volunteer contact information are stored in the browser's IndexedDB. When the application loads with a network connection, it syncs any changes from the server to local IndexedDB. When the volunteer searches for donors, the query runs against local IndexedDB with zero network involvement.

interface LocalDonorRecord {
  id: string;
  name: string;
  bloodGroup: "A+" | "A-" | "B+" | "B-" | "AB+" | "AB-" | "O+" | "O-";
  contactNumber: string;
  lastDonationDate: Date | null;
  isEligible: boolean;   // pre-computed flag
  hallName: string;
  roomNumber: string;
  lastSyncedAt: Date;
}

async function syncDonorRecords(): Promise<void> {
  const lastSync = await getLastSyncTimestamp();

  const updates = await fetch(`/api/donors?updatedSince=${lastSync.toISOString()}`)
    .then(r => r.json());

  const db = await openLocalDB();
  const tx = db.transaction("donors", "readwrite");

  for (const donor of updates) {
    const isEligible = donor.lastDonationDate
      ? daysSince(donor.lastDonationDate) >= 90
      : true;

    await tx.store.put({ ...donor, isEligible, lastSyncedAt: new Date() });
  }

  await tx.done;
  await setLastSyncTimestamp(new Date());
}

We pre-compute the isEligible boolean flag on dataset sync. Blood donation guidelines require a minimum 90-day gap between donations. Pre-computing it means the calculation happens once at sync time, not on every search query, enabling instant filtering in the critical search flow.

Service Worker Caching Strategy

Workbox handles the service worker layer, managing pre-caching for static assets and runtime caching strategies for API responses.

import { precacheAndRoute } from "workbox-precaching";
import { registerRoute } from "workbox-routing";
import { NetworkFirst } from "workbox-strategies";
import { ExpirationPlugin } from "workbox-expiration";

precacheAndRoute(self.__WB_MANIFEST);

registerRoute(
  ({ url }) => url.pathname.startsWith("/api/donors"),
  new NetworkFirst({
    cacheName: "donor-api-cache",
    networkTimeoutSeconds: 4,
    plugins: [
      new ExpirationPlugin({
        maxEntries: 100,
        maxAgeSeconds: 24 * 60 * 60,
      }),
    ],
  })
);

The NetworkFirst strategy with a 4-second timeout means: try the network first. If the network responds within 4 seconds, use that response and update the cache. If not, serve the cached response. This gives volunteers fresh data when the network is marginal but usable, and cached data when it's completely unavailable.

The Offline-First Side Effect: Speed

The most practical aspect of the offline-first approach turned out to be speed rather than connectivity. IndexedDB queries for blood group filtering across hundreds of records return in under 10 milliseconds consistently. This is faster than any network request and faster than most server-side database queries when you account for round-trip time.

The offline-first architecture that we built for connectivity resilience also produced a noticeably snappier search experience under normal conditions.

That's usually how it works: designing for the hard constraint improves performance under the easy conditions too.

Parvej Shah is a Lead Full-Stack Web Developer & Platform Architect based in Dhaka, Bangladesh. Explore full architecture case studies and production code at parvejshah.com.

The Surprising Complexity of Injecting a UI into Someone Else's Web Page

Parvej Shah — Wed, 26 Aug 2026 20:32:53 +0000

Originally published at parvejshah.com/blog/building-manifest-v3-ai-chrome-extensions by Parvej Shah.

When we started building Leadswave — a LinkedIn brand assistant Chrome extension — the plan seemed straightforward. Detect LinkedIn post elements in the feed, attach a small AI companion button to each one, let users generate engagement responses without leaving the page. A week's work, maybe two.

Three weeks later we were still fighting style collisions, service worker lifecycle bugs, and a Manifest V3 API constraint we hadn't anticipated. This is what we learned.

Why Injecting into a Third-Party Page Is Complicated

When your content script injects HTML into LinkedIn's document, you're working inside a page you don't control, with styles you didn't write, against a DOM structure that changes in LinkedIn's deployments without your knowledge.

The first version of Leadswave simply appended a styled div to each post element and mounted a React component inside it. It worked locally. On the actual LinkedIn feed, our Tailwind utility classes either had no effect (because LinkedIn's CSS specificity was higher) or caused unintended effects in LinkedIn's own components (because our styles bled into their DOM nodes).

The fix is Shadow DOM. Every modern browser supports the ability to attach a shadow root to a host element, creating an isolated DOM subtree that is completely separate from the main document's style cascade.

function mountAssistantWidget(hostElement: HTMLElement): HTMLElement {
  const container = document.createElement("div");
  container.id = "lw-assistant-root";

  // Attach a shadow root — this creates the style isolation boundary
  const shadow = container.attachShadow({ mode: "open" });

  // Our styles live inside the shadow — they can't bleed out,
  // and LinkedIn's styles can't bleed in
  const styleSheet = document.createElement("link");
  styleSheet.rel = "stylesheet";
  styleSheet.href = chrome.runtime.getURL("content/styles.css");
  shadow.appendChild(styleSheet);

  const mountPoint = document.createElement("div");
  shadow.appendChild(mountPoint);

  hostElement.appendChild(container);
  return mountPoint;
}

Manifest V3 Service Workers: Assume Nothing Persists

Manifest V2 allowed persistent background pages — JavaScript modules that stayed alive indefinitely and could hold state in memory. Manifest V3 replaced this with service workers. Service workers can be terminated by the browser at any point when they appear idle.

This is easy to forget when developing locally, because Chrome is less aggressive about terminating service workers during active development. In production, with a real user who opens LinkedIn once, reads through their feed over 20 minutes, and then triggers the assistant widget — the service worker has almost certainly been terminated in the interim.

// Don't rely on module-level variables for persistent state
// This will be undefined after the service worker restarts:
// let cachedApiKey: string | null = null; // BAD

// Instead, always read from storage:
async function getApiKey(): Promise<string | null> {
  const result = await chrome.storage.local.get(["apiKey"]);
  return result.apiKey ?? null;
}

async function saveUserSettings(settings: UserSettings): Promise<void> {
  await chrome.storage.local.set({ userSettings: settings });
}

For the assistant response generation — which requires sending post context to an API and streaming back a response — the content script makes the API call directly rather than routing through the service worker. This avoids the service worker lifecycle problem entirely for latency-sensitive operations.

Extracting Clean Context from LinkedIn's DOM

The AI generation requires understanding the content of the LinkedIn post the user is looking at. Passing raw innerHTML is wasteful and noisy — LinkedIn embeds tracking attributes, SVG icon paths, interaction counters, and other noise that consumes tokens without contributing to useful context.

function extractPostContext(postElement: HTMLElement): PostContext {
  const authorElement = postElement.querySelector(
    ".update-components-actor__name"
  );
  const author = authorElement?.textContent?.trim() ?? "Unknown";

  const bodyElement = postElement.querySelector(
    ".update-components-text"
  );

  const bodyText = extractTextNodes(bodyElement)
    .filter(text => text.trim().length > 0)
    .join(" ")
    .replace(/s+/g, " ")
    .trim();

  return { author, bodyText, extractedAt: Date.now() };
}

function extractTextNodes(el: Element | null): string[] {
  if (!el) return [];
  const texts: string[] = [];

  el.childNodes.forEach(node => {
    if (node.nodeType === Node.TEXT_NODE) {
      texts.push(node.textContent ?? "");
    } else if (node.nodeType === Node.ELEMENT_NODE) {
      texts.push(...extractTextNodes(node as Element));
    }
  });

  return texts;
}

The extracted context is typically 200 to 400 tokens — clean, structured, and representative of what the post actually says. This keeps API costs predictable and response generation fast.

The LinkedIn DOM Changes Problem

There's no way to make a content script robustly stable against DOM changes in a host page you don't control. LinkedIn deploys frontend changes regularly, and CSS class names can shift.

We partially mitigate this with attribute-based selectors where possible — data-* attributes tend to be more stable than utility class names — and by maintaining a small compatibility shim that detects structural changes and reports them. When the extension breaks on a LinkedIn update, we want to know within hours, not days.

The real answer is humility: DOM scraping is inherently fragile, and the architecture needs to be designed with that fragility in mind rather than pretending it won't happen.

Parvej Shah is a Lead Full-Stack Web Developer & Platform Architect based in Dhaka, Bangladesh. Explore full architecture case studies and production code at parvejshah.com.

Building a Chat-Based Sales Bot That Doesn't Drop Messages During Flash Sales

Parvej Shah — Wed, 26 Aug 2026 20:31:58 +0000

Originally published at parvejshah.com/blog/conversational-commerce-webhook-architecture by Parvej Shah.

In Bangladesh and much of South and Southeast Asia, e-commerce doesn't look like what a Silicon Valley product manager pictures. Buyers don't browse product catalogs, add items to carts, and check out with saved payment methods. They send a message on Facebook or WhatsApp, ask if an item is in stock, negotiate slightly, confirm their address, and pay by mobile banking transfer. The entire purchase funnel is a conversation.

SellerVai is a platform built for exactly this reality: a 24/7 automated sales assistant that handles order inquiries, processes orders in Bengali and Banglish, and filters fake Cash-on-Delivery (COD) requests across WhatsApp Business API, Facebook Messenger, and Telegram.

The core engineering challenge wasn't the AI. It was the plumbing.

Why Webhooks Are Harder Than They Look

Every message sent to a business on WhatsApp or Facebook triggers an HTTP POST from Meta's servers to your registered webhook URL. The contract is simple: respond with 200 OK within a few seconds, or Meta assumes delivery failed and retries.

When your webhook handler needs to classify intent, query a product database, check inventory, generate a personalized response, and sometimes initiate a payment collection flow — none of which can happen in a few seconds — you have a problem. The naive solution of doing all that work synchronously inside the webhook handler means you're constantly racing against the timeout, and you lose that race regularly during any period of elevated load.

The retry behavior makes it worse. When Meta doesn't get its 200 OK, it retries the same message. Now you have the same message being processed twice, potentially resulting in the same customer getting two replies, the same order being created twice, or two inventory decrements for a single purchase.

The Ingestion Architecture

The solution is to treat the webhook endpoint as nothing more than an authenticated message receiver. Its only responsibility is to verify the signature and acknowledge delivery. All actual processing happens asynchronously.

// Webhook ingestion handler — responds in < 15ms
export async function POST(req: Request) {
  const rawBody = await req.text();
  const signature = req.headers.get("x-hub-signature-256") ?? "";

  if (!verifyMetaSignature(rawBody, signature, META_APP_SECRET)) {
    return new Response("Forbidden", { status: 403 });
  }

  const payload = JSON.parse(rawBody) as MetaWebhookPayload;

  await messageQueue.add("process-incoming", {
    channel: "whatsapp",
    rawPayload: payload,
    receivedAt: Date.now(),
  });

  return new Response("OK", { status: 200 });
}

The queue (BullMQ backed by Redis) holds the message until a worker picks it up. The webhook handler has already returned 200 OK to Meta and is completely done. The actual work — intent classification, inventory lookup, response generation — happens in worker processes with no timeout pressure.

The Deduplication Layer

Workers can't blindly process everything in the queue. If Meta retried a message three times before getting its 200 OK, there are three copies of that message in the queue.

Every message gets fingerprinted before processing. The fingerprint is derived from the channel, the sender ID, and the platform's native message ID. The fingerprint goes into Redis with a 5-minute TTL using a SET NX operation — set only if not exists. If the key already exists, that message has been processed recently and the worker skips it.

function buildMessageFingerprint(
  channel: "whatsapp" | "messenger" | "telegram",
  senderId: string,
  messageId: string
): string {
  return crypto
    .createHash("sha256")
    .update(`${channel}:${senderId}:${messageId}`)
    .digest("hex");
}

async function processMessage(event: IncomingMessageEvent): Promise<void> {
  const fingerprint = buildMessageFingerprint(
    event.channel,
    event.senderId,
    event.messageId
  );

  const acquired = await redis.set(
    `processed:${fingerprint}`,
    "1",
    "NX",
    "EX",
    300
  );

  if (!acquired) return; // Duplicate — already processed or in progress

  await runConversationTurn(event);
}

Parsing Bengali and Banglish

Customer messages in social commerce are colloquial and informal. A real message looks like:

"vai ei sneaker ta ki size 42 ache? cash on delivery hobe? dhaka te delivery koto din lagbe?"

Translation: "bro is this sneaker available in size 42? can I pay cash on delivery? how many days will delivery take to Dhaka?"

There are three distinct questions packed into one casual message, written in a mix of Bengali script words and Bengali-language words written in Roman characters.

We use a two-tier parsing approach. A fast regex and keyword engine handles structured data extraction: phone numbers, size numbers, city names, specific product codes. This runs in under 2ms. An LLM classifier handles intent categorization where casual phrasing and code-switching require genuine language understanding.

Flash Sale Traffic

The real stress test came during a promotional campaign. Traffic spiked to roughly 15 times the baseline over a two-hour window. Because the ingestion layer is stateless and the queue absorbs the burst, the webhook endpoints stayed responsive. Workers processed the queue backlog over the following 20 minutes. Every message was processed. No duplicates were sent.

The architecture didn't require any changes for this scenario because it was designed with this scenario in mind from the start. Most reliability problems in messaging systems aren't hard to solve — they just require thinking through the failure modes before you're in them.

Parvej Shah is a Lead Full-Stack Web Developer & Platform Architect based in Dhaka, Bangladesh. Explore full architecture case studies and production code at parvejshah.com.

What It Actually Takes to Build a Workforce Management Dashboard for an AI Company

Parvej Shah — Wed, 26 Aug 2026 20:31:54 +0000

Originally published at parvejshah.com/blog/engineering-precision-data-platforms-sft-rlhf by Parvej Shah.

The initial brief from GenMorphics AI Solutions sounded straightforward: build a dashboard to help their team coordinate work across a global network of domain experts. As we got into the details, it became clear that "dashboard" was underselling the complexity significantly.

GenMorphics works with specialists in software engineering, mathematics, legal reasoning, and scientific disciplines. The work requires matching highly specific tasks to people with verifiable domain depth — not just anyone who checked a box saying they know Python. Building a web platform that could reliably route the right task to the right person, track project status across dozens of concurrent assignments, and maintain strict data access boundaries between different client projects turned out to be a genuine systems architecture challenge.

The Skill Routing Problem

The first thing we designed was the skill profiling system. The naive version of this is a checkbox list of technologies and subjects. The problem with that approach is that it makes no distinction between someone who learned Python basics in a weekend course and someone who has been writing production Python services for three years.

We structured skill profiles across three dimensions: domain category, competency depth, and verification status.

Domain categories span the disciplines GenMorphics works across — software engineering broken into language-specific tracks, mathematics covering areas like calculus, linear algebra, and discrete math separately, and professional fields including legal analysis, financial modeling, and scientific writing.

Competency depth marks whether a skill is self-reported or has been verified through a qualification review. Task routing logic only assigns work that requires verified skills to people who hold verified badges in that category.

interface ExpertProfile {
  id: string;
  skills: {
    category: "Software Engineering" | "Mathematics" | "Legal" | "Scientific";
    subcategory: string;
    depth: "Introductory" | "Proficient" | "Expert";
    verified: boolean;
    verifiedAt: Date | null;
  }[];
  activeTaskCount: number;
  maxConcurrentTasks: number;
}

function isEligibleForTask(expert: ExpertProfile, task: TaskRequirement): boolean {
  return task.requiredSkills.every(req =>
    expert.skills.some(s =>
      s.subcategory === req.subcategory &&
      s.depth >= req.minimumDepth &&
      (req.requiresVerification ? s.verified : true)
    )
  );
}

Authentication Architecture

The platform serves multiple stakeholders with fundamentally different access requirements. Domain experts can see only their assigned tasks and their own performance metrics. Project managers can see all tasks within their assigned project portfolio but not tasks belonging to other clients. Administrators have full access to user management, skill verification, and cross-project reporting.

We implemented this through role-based access control (RBAC) with row-level security at the database layer. Supabase's Row Level Security policies enforce access boundaries at the data layer itself, which means even if a bug in application code produced an unauthorized query, the database would refuse to return the data.

-- Experts can only view their own task assignments
CREATE POLICY "expert_own_tasks" ON task_assignments
  FOR SELECT USING (
    expert_id = auth.uid()
  );

-- Project managers see tasks within their managed projects
CREATE POLICY "pm_project_tasks" ON task_assignments
  FOR SELECT USING (
    EXISTS (
      SELECT 1 FROM project_managers
      WHERE user_id = auth.uid()
        AND project_id = task_assignments.project_id
    )
  );

For authentication itself, we integrated OAuth 2.0 with Google Workspace, which was the identity provider GenMorphics already used internally. This eliminated password management entirely for the core team while still allowing external domain experts to authenticate through a separate flow.

The Dataset Access Problem

Some tasks involve reviewing code repositories, audio samples, or domain-specific documents that belong to specific clients. These assets cannot be freely downloadable — they should expire and become inaccessible once a task is completed or reassigned.

We addressed this with short-lived signed URLs. All work materials are stored in private cloud storage buckets with no public access. When a user opens a task, the server generates a signed URL that is valid for 300 seconds — long enough to view and work with the material, short enough that the URL is useless by the time a task session ends.

async function getTaskAssetUrl(
  taskId: string,
  assetPath: string,
  requestingUserId: string
): Promise<string> {
  const assignment = await db.taskAssignment.findFirst({
    where: { taskId, expertId: requestingUserId, status: "ACTIVE" },
  });

  if (!assignment) throw new Error("Unauthorized: task not assigned to user");

  const { data } = await supabase.storage
    .from("task-assets")
    .createSignedUrl(assetPath, 300);

  return data.signedUrl;
}

What We Learned

The most valuable insight from this project was how much the technical complexity was driven by human organizational structure rather than technical requirements. The skill routing logic, the access control layers, the asset expiry design — all of it was a direct translation of how GenMorphics actually manages their team and their client commitments.

The web platform wasn't replacing that structure; it was encoding it in a way that could scale. That distinction shaped every architectural decision we made.

Parvej Shah is a Lead Full-Stack Web Developer & Platform Architect based in Dhaka, Bangladesh. Explore full architecture case studies and production code at parvejshah.com.

Why We Stopped Using LLM Agents to Control LLM Agents (Deterministic Multi-Agent FSM)

Parvej Shah — Wed, 26 Aug 2026 20:20:06 +0000

Originally published at parvejshah.com/blog/deterministic-multi-agent-systems-production by Parvej Shah.

The standard architecture pattern for multi-agent systems right now is an orchestration agent: a central LLM that receives a goal, decides which specialized agents to invoke, passes messages between them, and decides when the task is complete.

In early 2025, we built this exact pattern for Minions.AI's automated technical content pipeline. An orchestrator LLM coordinated a research agent, a draft writer, a critic agent, and a formatting specialist.

It worked in 70% of runs. In the other 30%, it failed in creative, unpredictable ways.

How LLM Orchestrators Fail

The failure modes weren't bugs in the traditional sense. The individual prompts were well-engineered. The tool definitions were clean. The failures came from the non-deterministic nature of the control plane.

Loop oscillation. The critic agent would reject a draft for lacking specific technical details. The writer agent would add details, but slightly change the tone. The critic agent would then reject the new draft for tone issues, causing the writer to revert the details. The orchestrator would watch this tennis match loop until hitting the maximum turn limit.

Context poisoning. As agents passed conversational turns back and forth, the shared context window accumulated conversational residue — conversational filler, apologies, retry explanations. By turn 6, 40% of the token budget was spent on orchestration chatter rather than the actual task domain.

Non-deterministic convergence. The same topic with the same source signals would sometimes produce a crisp, 1,200-word technical deep dive in 4 turns, and other times produce a rambling 3,000-word overview in 14 turns costing 4x the inference budget.

The Solution: Deterministic State Machines in TypeScript

The fix was conceptually simple: remove all control flow decisions from LLMs and put them in typed code.

LLMs are exceptional at content transformation, extraction, synthesis, and evaluation against specific criteria. They are terrible at state machine transitions, termination detection, and error routing.

We redesigned the multi-agent pipeline as a formal Finite State Machine (FSM) written in TypeScript:

type PipelineState =
  | "HARVEST_SIGNALS"
  | "DRAFT_CONTENT"
  | "CRITIC_REVIEW"
  | "REVISE_DRAFT"
  | "STAGE_CMS"
  | "FAILED";

interface PipelineContext {
  topicId: string;
  signals: IndustrySignal[];
  draftMarkdown?: string;
  critique?: CritiqueResult;
  revisionCount: number;
  maxRevisions: 2; // Strict deterministic limit
}

export async function runContentPipeline(
  ctx: PipelineContext
): Promise<PipelineState> {
  let state: PipelineState = "HARVEST_SIGNALS";

  while (state !== "STAGE_CMS" && state !== "FAILED") {
    switch (state) {
      case "HARVEST_SIGNALS":
        ctx.signals = await signalHarvesterAgent(ctx.topicId);
        state = ctx.signals.length > 0 ? "DRAFT_CONTENT" : "FAILED";
        break;

      case "DRAFT_CONTENT":
        ctx.draftMarkdown = await draftingAgent(ctx.signals);
        state = "CRITIC_REVIEW";
        break;

      case "CRITIC_REVIEW":
        ctx.critique = await criticAgent(ctx.draftMarkdown!);
        if (ctx.critique.score >= 85) {
          state = "STAGE_CMS";
        } else if (ctx.revisionCount < ctx.maxRevisions) {
          ctx.revisionCount++;
          state = "REVISE_DRAFT";
        } else {
          // Hard exit: escalate to human editor rather than infinite loop
          state = "FAILED";
        }
        break;

      case "REVISE_DRAFT":
        ctx.draftMarkdown = await revisionAgent(
          ctx.draftMarkdown!,
          ctx.critique!.actionableFixes
        );
        state = "CRITIC_REVIEW";
        break;
    }
  }

  return state;
}

The Architectural Rules That Emerged

State transitions belong in TypeScript. An LLM never decides what state comes next. The code inspects structured JSON output from the agent, evaluates explicit boolean conditions, and transitions state deterministically.
Hard iteration bounds. No loop runs without an explicit counter. If a draft fails critic review twice, the pipeline does not try a third time. It flags the job for human inspection and exits cleanly.
Isolated, stateless context per agent. Agents do not share a conversational transcript. The drafting agent receives only the raw signals. The critic agent receives only the generated draft and a strict rubric. Context poisoning is physically impossible.

The Outcome

The deterministic FSM pipeline has processed hundreds of scheduled content runs for Minions.AI with a 99.2% automated completion rate and zero loop oscillations. Inference cost variance dropped from ±120% to ±8%.

Parvej Shah is a Lead Full-Stack Web Developer & Platform Architect based in Dhaka, Bangladesh. Explore full architecture case studies and production code at parvejshah.com.

Rendering Math Formulas Without Making Students Wait (Server-Side KaTeX in RSC)

Parvej Shah — Wed, 26 Aug 2026 20:17:07 +0000

Originally published at parvejshah.com/blog/rendering-katex-formulas-nextjs-server-components by Parvej Shah.

MathPro Academy teaches JSC, SSC, and HSC mathematics to secondary and higher secondary students across Bangladesh. The platform's value proposition is clear and narrow: make complex mathematics accessible and understandable.

When the instructor works through a quadratic formula or a trigonometric identity, the rendering of that formula matters. A math notation that appears as a blurry, partially-loaded visual element — or worse, as raw LaTeX strings like \frac{-b \pm \sqrt{b^2-4ac}}{2a} before the renderer kicks in — undermines the credibility of the content and distracts from the explanation.

This is a rendering problem. And it's a problem that most EdTech platforms solve badly.

How Most Sites Render Math (and Why It's Slow)

The standard approach is to ship a math rendering library — KaTeX or MathJax — as a JavaScript bundle to the browser. The browser downloads the HTML, renders the raw LaTeX strings as placeholder text, downloads and parses the math library, then processes every formula on the page.

The result is a visible layout shift. Students see the raw formula text, then watch it suddenly transform into rendered notation. This causes Cumulative Layout Shift (CLS), which affects Core Web Vitals scores and SEO performance.

For MathPro Academy's student base, most of whom access the platform on mid-range Android devices over 4G connections, the bundle size matters too. KaTeX ships at roughly 180KB compressed. This is overhead that every student pays for every page load.

Approach	Client JS Bundle	CLS Score	First Paint
Client-side KaTeX	~180KB	0.28 (noticeable snap)	~1.8s
Client-side MathJax	~340KB	0.35 (severe snap)	~2.4s
Server-side KaTeX (RSC)	0KB	0.00	~0.5s

The server-side approach ships formulas as pre-rendered HTML with embedded geometry. The browser has nothing to compute and nothing to reflow.

Implementation with React Server Components

React Server Components execute on the server at request time or at build time for static pages. A Server Component can call katex.renderToString() directly — a synchronous, CPU-local operation — and the output is HTML that ships to the browser pre-rendered.

// This component never runs in the browser.
// There is no "use client" directive.
import katex from "katex";

interface MathFormulaProps {
  equation: string;
  block?: boolean;
}

export function MathFormula({ equation, block = false }: MathFormulaProps) {
  const html = katex.renderToString(equation, {
    displayMode: block,
    throwOnError: false,
    // Outputs both visual HTML and accessible MathML in the same element
    output: "htmlAndMathml",
    strict: false,
  });

  return (
    <span
      className={block ? "my-6 block overflow-x-auto py-2 text-center" : "inline-block align-middle"}
      dangerouslySetInnerHTML={{ __html: html }}
    />
  );
}

The output: "htmlAndMathml" option causes KaTeX to emit both the visual HTML representation and an embedded MathML element which screen readers and accessibility tools can interpret. This handles accessibility without any additional work.

Integrating with Markdown Content

Course content at MathPro Academy is authored in Markdown with inline LaTeX. The content pipeline processes Markdown through remark, with a custom plugin that intercepts LaTeX-delimited spans and replaces them with pre-rendered KaTeX HTML during the build step.

import { visit } from "unist-util-visit";
import katex from "katex";
import type { Plugin } from "unified";

export const remarkKatex: Plugin = () => (tree) => {
  visit(tree, "inlineCode", (node: any) => {
    if (node.value.startsWith("math:")) {
      const latex = node.value.slice(5);
      node.type = "html";
      node.value = katex.renderToString(latex, {
        displayMode: false,
        throwOnError: false,
        output: "htmlAndMathml",
      });
    }
  });
};

The formula HTML is embedded directly in the static page output. There is no JavaScript involved in rendering it, no hydration step, and no layout shift.

One Trade-off Worth Noting

Server-side rendering requires that katex runs as a Node.js dependency rather than a browser dependency. This means it's part of the server bundle — which is the whole point — but it does mean the server takes a small CPU hit rendering formulas for each unique page at build time.

For a statically generated course platform like MathPro Academy, this cost is paid once at build time, not once per request. A one-time CPU cost at build, permanent zero-cost rendering for every student visit afterward. The tradeoff is extremely favorable.

Parvej Shah is a Lead Full-Stack Web Developer & Platform Architect based in Dhaka, Bangladesh. Explore full architecture case studies and production code at parvejshah.com.

Payment Webhook Mistakes You Only Make Once (bKash & Nagad Idempotency)

Parvej Shah — Wed, 26 Aug 2026 20:14:23 +0000

Originally published at parvejshah.com/blog/defensive-webhook-engineering-payment-gateways by Parvej Shah.

There's a class of bug that only appears in production, under real network conditions, with real money. You can't reproduce it in development. You can't catch it in a staging environment with predictable network responses. The first time you encounter it, it's already caused a problem — either a student received course access they didn't pay for, or a student paid and didn't receive access.

These are the bugs that live inside payment webhook handlers.

For MathPro Academy, students purchase course enrollments through bKash and Nagad — Bangladesh's two dominant mobile financial services. Both platforms use webhook-based payment confirmation: after a successful transaction, their servers POST a confirmation payload to your registered endpoint. Your job is to receive that POST, verify it's legitimate, fulfill the order, and respond with a success status.

The failure modes are more numerous and more subtle than they appear.

The Network Doesn't Behave Itself

The fundamental assumption that breaks naive webhook handlers is that the POST will be delivered exactly once. It won't be.

If your server takes too long to respond, bKash or Nagad marks the delivery as failed and retries. If your server has a deployment in progress when the POST arrives, it might receive a 503. The payment gateway retries. Now the same payment confirmation has been delivered twice.

If your handler's first act is to write the enrollment to the database without checking whether it was already written — you've enrolled the student twice. The student has two active enrollments for the same course, your finance reconciliation is off by one transaction, and your per-course analytics are measuring a ghost.

The Three Properties Every Payment Handler Needs

1. Signature verification. Before touching the database or any application logic, verify that the incoming request actually came from the payment gateway. Both bKash and Nagad include an HMAC signature header that can be validated against your shared secret key.

function verifyPaymentSignature(
  rawBody: string,
  signatureHeader: string,
  secretKey: string
): boolean {
  const expectedHash = crypto
    .createHmac("sha256", secretKey)
    .update(rawBody)
    .digest("hex");

  // Timing-safe comparison prevents side-channel timing attacks
  // where an attacker can infer characters of your secret by measuring
  // how long the comparison takes
  return crypto.timingSafeEqual(
    Buffer.from(expectedHash, "utf-8"),
    Buffer.from(signatureHeader, "utf-8")
  );
}

The timing-safe comparison is worth calling out explicitly. A naive string comparison short-circuits at the first mismatched character — slightly faster for strings that differ early. An attacker with precise timing measurements can use this to infer the hash value one character at a time. crypto.timingSafeEqual always takes the same amount of time regardless of where the strings diverge.

2. Idempotency. Every transaction has a unique transaction ID assigned by the payment gateway. Use it as a natural idempotency key. Before processing any fulfillment, check whether that transaction ID has already been processed.

async function fulfillCourseOrder(
  transactionId: string,
  orderId: string
): Promise<{ status: "SUCCESS" | "ALREADY_PROCESSED" }> {
  return await prisma.$transaction(async (tx) => {
    const order = await tx.order.findFirst({
      where: { id: orderId },
    });

    if (!order) throw new Error(`Order ${orderId} not found`);

    if (order.status === "COMPLETED") {
      return { status: "ALREADY_PROCESSED" };
    }

    await tx.order.update({
      where: { id: orderId },
      data: {
        status: "COMPLETED",
        transactionId,
        completedAt: new Date(),
      },
    });

    await tx.enrollment.create({
      data: {
        userId: order.userId,
        courseId: order.courseId,
        enrolledAt: new Date(),
      },
    });

    return { status: "SUCCESS" };
  });
}

3. Atomicity. The order status update and the enrollment creation need to succeed or fail together. If the order update succeeds but the enrollment creation fails — database connectivity, constraint violation, application crash — you now have a paid order with no course access. The student is frustrated, your support queue gets a ticket, and you have to handle a manual correction.

Prisma's $transaction wraps both operations in a single database transaction. If anything in the callback throws, the entire transaction rolls back.

Idempotency Under Concurrent Retries

There's a subtle race condition worth thinking through. Imagine the payment gateway delivers the webhook twice in very quick succession — close enough that both requests arrive before either has fully processed. Both requests pass signature verification. Both check the order status and find it as PENDING. Both proceed to the fulfillment logic.

The $transaction call handles this. When accessed inside an interactive transaction with relational updates, the database enforces serializability or row-level locks. The second concurrent request waits until the first transaction commits. By the time the second transaction proceeds, the order status has already been set to COMPLETED, and the early return fires.

Responding to the Payment Gateway

Return a success status (200 OK) only after successful processing. If your handler returns success before confirming the enrollment, and then your enrollment write fails, the payment gateway considers its job done. There's no retry. The student paid and got nothing.

Return a server error code (500) if your handler can't process the request due to transient database or infrastructure failures. This signals the gateway to retry. Your idempotency logic ensures the retry is safe.

Parvej Shah is a Lead Full-Stack Web Developer & Platform Architect based in Dhaka, Bangladesh. Explore full architecture case studies and production code at parvejshah.com.

How We Got Voice AI Response Times Under 1.8 Seconds on Real Phone Calls

Parvej Shah — Wed, 26 Aug 2026 20:13:15 +0000

Originally published at parvejshah.com/blog/architecting-sub-18s-voice-ai-pipelines by Parvej Shah.

There's a specific type of frustration that's hard to explain unless you've experienced it. You call a business. An automated voice picks up. You ask your question. And then — silence. Not a brief pause. A real silence. Long enough that you start wondering if the call dropped, long enough that you pull the phone away from your ear to check the signal bars.

That silence is what we were trying to eliminate when building the telephony dispatcher for Minions.AI, a voice-based service dispatch platform for trade contractors.

In human conversation, the natural gap between one person finishing a sentence and the other beginning a response is around 200 to 300 milliseconds. Anything beyond 600ms starts to feel awkward. At 2,500ms — which was where the original prototype sat — callers would repeat themselves, raise their voice, or hang up. The call experience was technically functional and practically unusable.

The Sequential Pipeline Problem

The first design was a completely natural one: record audio, run transcription, generate a response, synthesize speech, play it back. Each stage waited for the previous one to finish. The latency budget looked like this:

Stage	Time
Voice Activity Detection (end-of-turn)	800ms
Speech-to-Text transcription	400ms
LLM generation (full response)	1,200ms
Text-to-Speech synthesis	500ms
Total	~2,900ms

That math is catastrophic for a phone call. And it gets worse in real conditions: cellular networks introduce jitter, LLM response times have variance, TTS output buffering adds overhead.

The solution wasn't to make each stage faster in isolation. It was to stop treating them as stages at all.

Replacing Stages with Streams

The rewrite changed the mental model from a sequential pipeline to an overlapping set of event-driven streams. Nothing waits for anything it doesn't strictly have to.

Neural VAD instead of silence timers. The original design waited for 800ms of audio silence before assuming the caller had finished speaking. We replaced this with a WebRTC-compatible neural Voice Activity Detection model running on 20ms audio frames. It detects speech completion at the prosodic level — reading the natural falling intonation of a completed sentence — rather than just measuring decibels.

interface VADConfig {
  frameSizeMs: 20;
  positiveSpeechThreshold: 0.65;
  negativeSpeechThreshold: 0.35;
  minSilenceDurationMs: 280;    // down from 800ms
  prefixPaddingFrames: 3;
}

function handleIncomingAudioFrame(frame: Buffer, vad: NeuralVAD) {
  const isSpeech = vad.process(frame);

  // Immediate barge-in handling
  if (isSpeech && currentAgentState === "SPEAKING") {
    audioOutputBuffer.clear();
    llmAbortController.abort();
    transitionToState("LISTENING");
  }
}

This dropped end-of-turn detection from 800ms to 280ms without causing false cutoffs when callers paused mid-thought.

Overlapping LLM token generation with TTS synthesis. We stopped waiting for the full LLM completion before initiating text-to-speech. As the LLM streams tokens, a boundary detector splits on sentence clauses (periods, commas, clause breaks) and dispatches the first clause to the TTS engine immediately.

async function streamToTTS(
  tokenStream: AsyncIterable<string>,
  ttsEngine: StreamingTTSClient,
  audioSink: AudioStreamSink
) {
  let buffer = "";
  const sentenceEndPattern = /[.!?,;:]\s+/;

  for await (const token of tokenStream) {
    buffer += token;
    const match = buffer.match(sentenceEndPattern);

    if (match && match.index !== undefined) {
      const clause = buffer.slice(0, match.index + 1).trim();
      buffer = buffer.slice(match.index + match[0].length);

      if (clause.length > 0) {
        // Synthesize and stream the first clause immediately
        const audioChunk = await ttsEngine.synthesizeClause(clause);
        await audioSink.enqueue(audioChunk);
      }
    }
  }

  // Flush any remaining text in buffer
  if (buffer.trim().length > 0) {
    const finalAudio = await ttsEngine.synthesizeClause(buffer.trim());
    await audioSink.enqueue(finalAudio);
  }
}

The first audio chunk starts synthesizing while the LLM is still generating the second half of the response. The caller hears the first word of the answer within ~600ms of the LLM receiving the prompt, rather than waiting 1,200ms for the full sentence to generate.

Speculative Tool Pre-fetching

The largest latency spike occurred whenever the agent needed to call an external tool — checking technician availability in the CRM or looking up an address in the dispatch database. Standard tool-calling waits for the LLM to output a tool_call token sequence, executes the function, appends the result to the context, and prompts the LLM again. That roundtrip routinely added 1,100ms.

We implemented speculative pre-fetching: while the user is still speaking and the interim transcription suggests a booking intent (e.g., "Do you have anyone available on Thursday..."), a background worker queries the technician availability API with predicted date parameters before the utterance completes.

// Interim transcript listener for speculative pre-fetch
sttStream.on("interim_transcript", (partialText: string) => {
  const intentPrediction = fastIntentClassifier(partialText);

  if (intentPrediction.type === "CHECK_AVAILABILITY" && intentPrediction.confidence > 0.85) {
    // Pre-warm the cache before the caller finishes speaking
    technicianScheduleCache.prefetch({
      date: intentPrediction.extractedDate ?? getNextBusinessDay(),
      serviceType: intentPrediction.serviceType,
    });
  }
});

By the time the LLM formally issues the tool call, the database result is already warm in Redis cache. Tool execution time dropped from 380ms to 4ms.

The Result: Sub-1.8s in Real Conditions

Here is the latency budget before and after the architecture change:

Stage	Before	After	Delta
Voice Activity Detection (end-of-turn)	800ms	280ms	-520ms
Speech-to-Text	400ms	190ms (streaming)	-210ms
LLM Time-to-First-Token	1,200ms (full completion)	310ms (first token)	-890ms
TTS First Audio Chunk	500ms (full audio)	220ms (first clause)	-280ms
Network Jitter Buffer	0ms	180ms (added for stability)	+180ms
Total Response Latency	~2,900ms	~1,180ms – 1,450ms	~55% faster

Under real cellular phone call conditions (varying 4G/5G latency, background noise, slight packet loss), the median round-trip time consistently stays under 1.8 seconds.

At 1.4 to 1.8 seconds, the interaction stops feeling like a command-and-response terminal and starts feeling like a conversation. Callers don't talk over the agent, they don't repeat themselves, and appointment conversion rates increased by over 30% compared to the sequential prototype.

Parvej Shah is a Lead Full-Stack Web Developer & Platform Architect based in Dhaka, Bangladesh. Explore full architecture case studies and production code at parvejshah.com.