David Aniebo - freeCodeCamp.org

How to Design APIs for AI Agents

David Aniebo — Thu, 28 May 2026 22:12:00 +0000

APIs are designed for human developers. People read documentation, infer the intent behind an endpoint, and know how to handle edge cases when something unexpected happens.

AI agents don't have that context and understanding.

AI agent understand APIs through schemas, examples, randomized data and live responses. When a behavior or method is ambiguous and inconsistent, the model doesn't pause to “think” – it fills in the blanks (randomizing).

In production, those guesses could become blocks, retry storms, duplicated side effects, or broken workflows.

This is why APIs that are perfectly fine for humans frequently fail under AI agent use. The problem is rarely “the agent isn’t smart enough.” More often, the API was never designed for an agent/machine consumer that must plan, call tools, and recover from failure without a human in the loop.

In this guide, you’ll learn how to design APIs that agents can use reliably. We’ll anchor the discussion in three practical ideas:

Deterministic behavior: same inputs and state should yield predictable outcomes and shapes.
Strong schemas: contracts that are complete, descriptive, and testable.
Guardrails at the API boundary: authorization, validation, and safe defaults that prevent unsafe autonomy.

The aim of this article is not to build “AI-powered” APIs, but rather to build APIs that are clear, strict, and dependable, even when the caller is not an agent but a fellow developers leveraging various tools.

Prerequisites
Why “Good Enough for Devs” Is Not Good Enough for Agents
Principle 1: Deterministic Behavior
Principle 2: Strong Schemas
Principle 3: Guardrails at the API Boundary
Patterns That Bridge APIs and Agent Runtimes
A Practical Before and After Example
Checklist: Is Your API Agent-Ready?
Conclusion

Prerequisites

Before reading this guide, it helps to have:

A basic understanding of HTTP APIs and REST concepts
Familiarity with JSON and API request/response patterns
An understanding of common API concepts like authentication, pagination, and retries

Why “Good Enough for Devs” Is Not Good Enough for Agents

Human developers bring implied and contextual knowledge: they read through Slack threads, read blog posts, and recognize that “this 404 usually means you forgot the workspace ID.”

Agents mostly get whatever is in the spec, the examples, and the last response body.

That gap shows up in predictable ways:

Ambiguous semantics: wrong endpoint or wrong parameter combination.
Undocumented branches: the model invents fields or misreads optional behavior.
Inconsistent error bodies: retries that shouldn't happen, or no retry when one is safe.
Non-idempotent “do things” endpoints: duplicate charges, duplicate tickets, duplicate emails.

Industry commentary and practitioner guides converge on the same point: agents are becoming a major class of API consumer, and machine legibility matters as much as developer experience.

See for example discussions of OpenAPI as the source of truth for agents, emerging tool protocols, and traffic patterns that differ from human clients in the resources listed at the end of this article.

Principle 1: Deterministic Behavior

Determinism for agents doesn't mean “always return the same JSON forever.” It means: given the same request and the same server-side state, your API behaves in a way the agent can model and when state changes, you make that explicit.

Prefer Explicit State Over Hidden Magic

Agents struggle with “sometimes the server does X depending on internal flags.” Where humans infer intent from product copy, agents infer from patterns. If those patterns drift, autonomy breaks.

Practical habits:

Model lifecycle explicitly (draft → submitted → approved) instead of overloading a single status field with undocumented combinations.
Return what changed after mutations (updated resource, relevant IDs, next allowed actions).
Avoid silent coercion (auto-correcting bad enums, silently dropping unknown fields) unless you document and signal it.

Make Writes Safe: Idempotency and Intent Keys

For any endpoint that bills, sends messages, provisions infrastructure, or otherwise does something irreversible, assume double-submission will happen.

Support idempotency keys (header or body) for create-like operations.
Use clear HTTP semantics: POST creates, PUT replaces where appropriate, PATCH for partial updates and document what repeats mean.
Where duplicates are possible, offer a lookup-by-client-reference path so agents can reconcile.

Pagination and Sorting: One Pattern, Everywhere

Agents loop. If every resource paginates differently, the model will mix strategies.

To combat this, pick one pagination style (cursor vs offset) per API surface and stick to it.

Also, always return stable sort order or require sort explicitly. You should also include next links or cursors in a consistent envelope.

Timeouts, Partial Success, and Async Work

Agents hate “maybe it worked.” Long-running work should be explicitly async:

202 Accepted + job ID + polling or webhooks.
Clear terminal states: succeeded, failed, canceled, with structured error details on failure.

Principle 2: Strong Schemas

If determinism is about behavior, schemas are about communication. For agents, your OpenAPI (or equivalent) isn't paperwork, it's part of the runtime interface.

Treat OpenAPI as a Contract, Not a Souvenir

A specification that lags production is worse than no spec: it trains the agent to be confidently wrong. Teams increasingly treat OpenAPI as the authoritative contract and validate requests/responses against it in CI and at the edge.

Here's the minimum bar for agent-friendly OpenAPI:

Every operation has a summary and a description that explain when to use it, not only what it returns.
Every request body property has description and realistic example values.
All responses are documented including 4xx/5xx with stable JSON shapes.

Describe Intent in Natural Language, Precisely

Agents aren't offended by verbosity. They're confused by vague verbs.

Instead of:

“Gets orders.”

Prefer:

“Lists orders for the authenticated merchant. Supports filtering by status and a time window on created_at. Returns at most limit items; use cursor for the next page.”

This aligns with what multiple guides call context-aware or self-describing APIs: the schema carries semantic intent, not just types.

Examples Are Part of the Contract

You should provide a happy path example per endpoint, at least one validation error example (400) with your standard error object, and examples for optional fields when they change behavior.

Examples reduce “shape hallucination” where the model guesses field names or nesting.

JSON Schema Strictness Helps Tool-Calling Stacks

If your agent uses function calling / structured outputs, tighten schemas:

Prefer enum for small closed sets.
Mark fields required honestly.
Use format (uuid, date-time) where real.
Avoid additionalProperties: true on security-sensitive payloads if you need strict validation.

Name Things Consistently

userId in one endpoint and user_id in another is a human annoyance and an agent trap. Pick a convention and enforce it.

Principle 3: Guardrails at the API Boundary

Autonomy amplifies mistakes. Guardrails turn “oops” into blocked requests instead of incidents.

Authorization Should Be Narrow and Explicit

Agents should receive credentials scoped to least privilege. For example, use short-lived tokens, with refresh documented clearly. Use scopes that map to real actions (orders:read vs orders:write). And avoid flows that assume a human can solve (CAPTCHAs) or click (email links mid-run) or isolate those as human-in-the-loop tools.

Validate Hard, Fail Loud and Structured

Reject bad input at the edge with stable error_code values (machine-actionable), human-readable message (for logs and UI), optional field or JSON Pointer to the problem, and optional doc_url linking to documentation.

This matches guidance from several practitioner articles: opaque 500s and generic errors are where autonomous clients spiral.

RFC 7807 Problem Details (application/problem+json) is a good, widely understood pattern for HTTP APIs, a structured envelope agents can parse consistently.

Separate “Read the World” from “Change the World”

For high-impact actions (refunds, deletes, transfers), consider using a two-step pattern: first create an intent, then confirm execution.

Or you can dry-run query parameters / dedicated endpoints that validate without committing.

Also keep in mind that rate limits and quotas tuned for bursty agent behavior and autonomous loops can dwarf human traffic.

Observability is a Product Feature

Log correlation IDs, surface them in responses where safe, and monitor for retry amplification. An agent that misreads a 409 as “retry forever” becomes a denial-of-wallet attack on your own systems.

Patterns That Bridge APIs and Agent Runtimes

Workflow Documentation: Sequences, Not Just Endpoints

Agents excel when they can follow a recipe. Document common sequences (“create customer → add payment method → charge”) and consider standards meant for multi-step API flows (such as Arazzo) when your product’s complexity justifies it.

Hypermedia and “Next Steps”

Including links to plausible next actions (for example, pagination next, or related resources) reduces improvisation. This is the same spirit as HATEOAS: the response whispers what you can do next, instead of forcing the model to guess URLs.

Tool-Oriented Surfaces (For Example, MCP)

Protocols like the Model Context Protocol (MCP) are gaining traction as a way to expose curated capabilities (“tools”) with schemas agents can bind to directly.

A common pragmatic pattern is not to dump every micro-endpoint as a tool, but to expose coarse-grained tools aligned to user outcomes while keeping your underlying REST API strict and clean.

MCP isn't a substitute for good API design. It's a delivery and discovery layer. Slapping a thin wrapper on a messy API still leaves you with a messy system – it just fails faster in public.

Metadata for Discovery (`llms.txt` and Friends)

Some teams publish /llms.txt or similar lightweight discovery files for documentation sites. Treat these as optional signposts, not replacements for OpenAPI.

Ecosystem adoption is still evolving, but the underlying idea is sound: make the canonical machine-readable description easy to find.

A Practical Before/After

Weak Pattern (Agent-hostile)

POST /do-stuff

Response 200 OK:

{ "ok": true }

Problems: no idempotency, no structured error, no entity ID, no way to poll, the agent must guess whether “ok” means “created” or “ignored duplicate.”

Stronger Pattern (Agent-friendly)

POST /v1/invoices
Idempotency-Key: 7b3c-...

Response 201 Created:

{
  "invoice": {
    "id": "inv_9Qz",
    "status": "draft",
    "total": { "amount": "120.00", "currency": "USD" }
  },
  "links": {
    "finalize": "/v1/invoices/inv_9Qz/finalize"
  }
}

Conflict response 409 Conflict with Problem Details:

{
  "type": "https://api.example.com/problems/duplicate-idempotency-key",
  "title": "Duplicate idempotency key",
  "status": 409,
  "detail": "A different request body was sent with the same Idempotency-Key.",
  "error_code": "IDEMPOTENCY_KEY_REUSE_BODY_MISMATCH"
}

This tells the agent what happened and whether retrying is appropriate.

Checklist: Is Your API Agent-Ready?

Contract: Published OpenAPI 3.x, validated against real traffic, with rich descriptions and examples.
Determinism: Documented state machines, consistent pagination, explicit async for long jobs.
Safe writes: Idempotency for side effects, reconciliation endpoints where needed.
Errors: Stable codes, structured bodies, documented remediation paths.
Security: Least-privilege tokens, no “mystery” side doors agents can accidentally hit.
Operations: Rate limits, bulk endpoints where appropriate, correlation IDs, dashboards for anomalous agent traffic.

Conclusion

Designing for AI agents is, in most respects, disciplined API design — pushed to the level where machines can rely on your contract without tribal knowledge.

If you remember only three things:

Be predictable: in shapes, states, and side effects.
Be explicit: in schemas, examples, and errors.
Be protective: validate early, scope narrowly, and make dangerous actions hard to trigger by accident.

A Developer’s Guide to Lazy Loading in React and Next.js

David Aniebo — Tue, 14 Apr 2026 20:31:59 +0000

Large JavaScript bundles can slow down your application. When too much code loads at once, users wait longer for the first paint and pages feel less responsive. Search engines may also rank slower sites lower in results.

Lazy loading helps solve this problem by splitting your code into smaller chunks and loading them only when they are needed

This guide walks you through lazy loading in React and Next.js. By the end, you'll know when to use React.lazy, next/dynamic, and Suspense, and you'll have working examples you can copy and adapt to your own projects.

What is Lazy Loading?
Prerequisites
How to Use React.lazy for Code Splitting
How to Use Suspense with React.lazy
How to Handle Errors with Error Boundaries
How to Use next/dynamic in Next.js
React.lazy vs next/dynamic: When to Use Each
Real-World Examples
Conclusion

What is Lazy Loading?

Lazy loading is a performance technique that defers loading code until it's needed. Instead of loading your entire app at once, you split it into smaller chunks. The browser only downloads a chunk when the user navigates to that route or interacts with that feature.

Benefits include:

Faster initial load: Smaller first bundle means quicker time to interactive
Better Core Web Vitals: Improves Largest Contentful Paint and Total Blocking Time
Lower bandwidth: Users only download what they use

In React, you achieve this with dynamic imports and React.lazy() or Next.js’s next/dynamic.

Prerequisites

Before you follow along, you should have:

Basic familiarity with React (components, hooks, state)
Node.js installed (version 18 or later recommended)
A React app (Create React App or Vite) or a Next.js app (for the Next.js examples)

For the React examples, you can use Create React App or Vite. For the Next.js examples, use the App Router (Next.js 13 or later).

How to Use `React.lazy` for Code Splitting

React.lazy() lets you define a component as a dynamic import. React will load that component only when it's first rendered.

React.lazy() expects a function that returns a dynamic import(). The imported module must use a default export.

Here's a basic example:

import { lazy } from 'react';

const HeavyChart = lazy(() => import('./HeavyChart'));
const AdminDashboard = lazy(() => import('./AdminDashboard'));

function App() {
  return (
    
      My App
      
      
    
  );
}

If you use named exports, you can map them to a default export:

const ComponentWithNamedExport = lazy(() =>
  import('./MyComponent').then((module) => ({
    default: module.NamedComponent,
  }))
);

You can also name chunks for easier debugging in the browser:

const HeavyChart = lazy(() =>
  import(/* webpackChunkName: "heavy-chart" */ './HeavyChart')
);

React.lazy() alone isn't enough. You must wrap lazy components in Suspense so React knows what to show while they load.

How to Use `Suspense` with `React.lazy`

Suspense is a React component that shows a fallback UI while its children are loading. It works with React.lazy() to handle the loading state of dynamically imported components.

Wrap your lazy components in Suspense and provide a fallback prop:

import { lazy, Suspense } from 'react';

const HeavyChart = lazy(() => import('./HeavyChart'));
const AdminDashboard = lazy(() => import('./AdminDashboard'));

function App() {
  return (
    
      My App
      Loading chart...}>
        
      
      Loading dashboard...}>
        
      
    
  );
}

You can use a single Suspense boundary for multiple lazy components:

Loading...}>

A more polished fallback improves perceived performance:

function LoadingSpinner() {
  return (
    
      
      Loading...
    
  );
}

}>

How to Handle Errors with Error Boundaries

React.lazy() and Suspense don't handle loading errors (for example, network failures or missing chunks). For that, you need an Error Boundary.

Error Boundaries are class components that use componentDidCatch or static getDerivedStateFromError to catch errors in their child tree and render a fallback UI.

Here is a simple Error Boundary:

import { Component } from 'react';

class ErrorBoundary extends Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    console.error('Error caught by boundary:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback || Something went wrong.;
    }
    return this.props.children;
  }
}

Wrap your Suspense boundary with an Error Boundary:

import { lazy, Suspense } from 'react';
import ErrorBoundary from './ErrorBoundary';

const HeavyChart = lazy(() => import('./HeavyChart'));

function App() {
  return (
    Failed to load chart. Please try again.}>
      Loading chart...}>
        
      
    
  );
}

If the chunk fails to load, the Error Boundary catches it and shows your fallback instead of a blank screen or unhandled error.

How to Use `next/dynamic` in Next.js

Next.js provides next/dynamic, which wraps React.lazy() and Suspense and adds options tailored for Next.js (including Server-Side Rendering).

Basic usage:

'use client';

import dynamic from 'next/dynamic';

const ComponentA = dynamic(() => import('../components/A'));
const ComponentB = dynamic(() => import('../components/B'));

export default function Page() {
  return (
    
      
      
    
  );
}

Custom Loading UI

Use the loading option to show a placeholder while the component loads:

const HeavyChart = dynamic(() => import('../components/HeavyChart'), {
  loading: () => Loading chart...,
});

Disable Server-Side Rendering

For components that must run only on the client (for example, those using window or browser-only APIs), set ssr: false:

const ClientOnlyMap = dynamic(() => import('../components/Map'), {
  ssr: false,
  loading: () => Loading map...,
});

Note: ssr: false works only for Client Components. Use it inside a 'use client' file.

Load on Demand

You can load a component only when a condition is met:

'use client';

import { useState } from 'react';
import dynamic from 'next/dynamic';

const Modal = dynamic(() => import('../components/Modal'), {
  loading: () => Opening modal...,
});

export default function Page() {
  const [showModal, setShowModal] = useState(false);

  return (
    
      
      {showModal &&  setShowModal(false)} />}
    
  );
}

Named Exports

For named exports, return the component from the dynamic import:

const Hello = dynamic(() =>
  import('../components/hello').then((mod) => mod.Hello)
);

Using Suspense with next/dynamic

In React 18+, you can use suspense: true to rely on a parent Suspense boundary instead of the loading option:

const HeavyChart = dynamic(() => import('../components/HeavyChart'), {
  suspense: true,
});

// In your component:
Loading...}>

Important: When using suspense: true, you can't use ssr: false or the loading option. Use the Suspense fallback instead.

`React.lazy` vs `next/dynamic`: When to Use Each

Feature	React.lazy + Suspense	next/dynamic
Framework	Any React app (Create React App, Vite, etc.)	Next.js only
Server-Side Rendering	Not supported	Supported by default
Disable SSR	N/A	`ssr: false` option
Loading UI	`Suspense` fallback prop	Built-in `loading` option
Error handling	Requires Error Boundary	Requires Error Boundary
Named exports	Manual `.then()` mapping	Same `.then()` pattern
Suspense mode	Always uses Suspense	Optional via `suspense: true`

When to Use `React.lazy`

You're building a pure React app (no Next.js)
You use Create React App, Vite, or a custom Webpack setup
You don't need Server-Side Rendering
You want a simple, framework-agnostic approach

When to `Use next/dynamic`

You're building a Next.js app
You need SSR for some components and want to disable it for others
You want built-in loading placeholders without manually adding Suspense
You want Next.js-specific optimizations and defaults

Real-World Examples

Example 1: Route-Based Code Splitting in React

Split your app by route so each page loads only when the user navigates to it:

// App.jsx
import { lazy, Suspense } from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import ErrorBoundary from './ErrorBoundary';

const Home = lazy(() => import('./pages/Home'));
const Dashboard = lazy(() => import('./pages/Dashboard'));
const Settings = lazy(() => import('./pages/Settings'));

function App() {
  return (
    
      Failed to load page.}>
        Loading page...}>
          
            } />
            } />
            } />
          
        
      
    
  );
}

Example 2: Lazy Loading a Heavy Chart Library in Next.js

Defer loading a chart library until the user opens the analytics section:

// app/analytics/page.jsx
'use client';

import { useState } from 'react';
import dynamic from 'next/dynamic';

const Chart = dynamic(() => import('../components/Chart'), {
  ssr: false,
  loading: () => (
    
      
      
      
    
  ),
});

export default function AnalyticsPage() {
  const [showChart, setShowChart] = useState(false);

  return (
    
      Analytics
      
      {showChart && }
    
  );
}

Load a modal component only when the user clicks to open it:

// React (with React.lazy)
import { lazy, Suspense, useState } from 'react';

const Modal = lazy(() => import('./Modal'));

function ProductPage() {
  const [showModal, setShowModal] = useState(false);

  return (
    
      
      {showModal && (
        
           setShowModal(false)} />
        
      )}
    
  );
}

// Next.js (with next/dynamic)
'use client';

import { useState } from 'react';
import dynamic from 'next/dynamic';

const Modal = dynamic(() => import('./Modal'), {
  loading: () => null,
});

export default function ProductPage() {
  const [showModal, setShowModal] = useState(false);

  return (
    
      
      {showModal &&  setShowModal(false)} />}
    
  );
}

Example 4: Lazy Loading External Libraries

Load a library only when the user needs it (for example, when they start typing in a search box):

'use client';

import { useState } from 'react';

const names = ['Alice', 'Bob', 'Charlie', 'Diana'];

export default function SearchPage() {
  const [results, setResults] = useState([]);
  const [query, setQuery] = useState('');

  const handleSearch = async (value) => {
    setQuery(value);
    if (!value) {
      setResults([]);
      return;
    }
    // Load fuse.js only when user searches
    const Fuse = (await import('fuse.js')).default;
    const fuse = new Fuse(names);
    setResults(fuse.search(value));
  };

  return (
    
       handleSearch(e.target.value)}
      />
      
        {results.map((result) => (
          {result.item}
        ))}
      
    
  );
}

Conclusion

Lazy loading improves performance by splitting your bundle and loading code only when needed. Here's what you learned:

React.lazy() – Use in plain React apps for code splitting. It requires a default export and works with dynamic import().
Suspense – Wrap lazy components in Suspense and provide a fallback for the loading state.
Error Boundaries – Use them to catch chunk load failures and show a friendly error UI.
next/dynamic – Use in Next.js for the same benefits plus SSR control and built-in loading options.

Choose React.lazy for React-only projects and next/dynamic for Next.js. Combine them with Suspense and Error Boundaries for a solid lazy-loading setup.

Start by identifying your heaviest components (charts, modals, admin panels) and lazy load them. Measure your bundle size and Core Web Vitals before and after to see the impact.

How to Share Components Between Server and Client in NextJS

David Aniebo — Fri, 27 Mar 2026 20:41:32 +0000

Next.js App Router splits your app into Server Components and Client Components. Server Components run on the server and keep secrets safe. Client Components run in the browser and handle interactivity. The challenge is sharing data and UI between them without breaking the rules of each environment.

This guide shows you how to share components and data between Server and Client Components in Next.js. You'll learn composition patterns, prop passing rules, and when to use each approach.

What are Server and Client Components?
Prerequisites
How to Pass Data from Server to Client via Props
How to Pass Server Components as Children to Client Components
What Props Are Allowed Between Server and Client
How to Share Data with Context and React.cache
How to Use Third-Party Components in Both Environments
How to Prevent Environment Poisoning with server-only and client-only
Real-World Examples
Conclusion

What are Server and Client Components?

In the Next.js App Router, every component is a Server Component by default. Server Components run only on the server. They can fetch data from databases, use API keys, and keep sensitive logic out of the browser. They don't send JavaScript to the client, which reduces bundle size.

Client Components run on both the server (for the initial HTML) and the client (for interactivity). You mark them with the "use client" directive at the top of the file. They can use useState, useEffect, event handlers, and browser APIs like localStorage and window.

The key rule: Server Components can import and render Client Components, but Client Components can't import Server Components directly. They can only receive them as props (such as children).

Prerequisites

Before you follow along, you should have:

Basic familiarity with React (components, props, hooks)
A Next.js project using the App Router (Next.js 13 or later)
Node.js installed (version 18 or later recommended)

If you don't have a Next.js project yet, create one with:

npx create-next-app@latest my-app

How to Pass Data from Server to Client via Props

The simplest way to share data between Server and Client Components is to pass it as props. The Server Component fetches the data, and the Client Component receives it and handles interactivity.

Here is a basic example. A page (Server Component) fetches a post and passes the like count to a LikeButton (Client Component):

// app/post/[id]/page.jsx (Server Component)
import LikeButton from '@/app/ui/like-button';
import { getPost } from '@/lib/data';

export default async function PostPage({ params }) {
  const { id } = await params;
  const post = await getPost(id);

  return (
    
      {post.title}
      {post.content}
      
    
  );
}

// app/ui/like-button.jsx (Client Component)
'use client';

import { useState } from 'react';

export default function LikeButton({ likes, postId }) {
  const [count, setCount] = useState(likes);

  const handleLike = () => {
    setCount((c) => c + 1);
    // Call API or Server Action to persist
  };

  return (
    
  );
}

The Server Component fetches data on the server. The Client Component receives plain values (likes, postId) and manages state and events. This pattern keeps data fetching on the server and interactivity on the client.

How to Pass Server Components as Children to Client Components

You can pass a Server Component as the children prop (or any prop) to a Client Component. The Server Component still renders on the server. The Client Component receives the rendered output, not the component code.

This is useful when you want a Client Component to wrap or control the layout of server-rendered content. For example, a modal that shows server-fetched data:

// app/ui/modal.jsx (Client Component)
'use client';

import { useState } from 'react';

export default function Modal({ children }) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      
      {isOpen && (
        
          {children}
        
      )}
    
  );
}

// app/cart/page.jsx (Server Component)
import Modal from '@/app/ui/modal';
import Cart from '@/app/ui/cart';

export default function CartPage() {
  return (
    
      
    
  );
}

// app/ui/cart.jsx (Server Component - no 'use client')
import { getCart } from '@/lib/cart';

export default async function Cart() {
  const items = await getCart();

  return (
    
      {items.map((item) => (
        {item.name}
      ))}
    
  );
}

Cart is a Server Component that fetches cart data. It's passed as children to Modal, which is a Client Component. The server renders Cart first. The RSC Payload includes the rendered result. The client receives that output and displays it inside the modal. The cart data never runs on the client.

You can use the same pattern with named props (slots):

// app/ui/tabs.jsx (Client Component)
'use client';

import { useState } from 'react';

export default function Tabs({ tabs, children }) {
  const [activeIndex, setActiveIndex] = useState(0);

  return (
    
      
        {tabs.map((tab, i) => (
          
        ))}
      
      {children[activeIndex]}
    
  );
}

// app/dashboard/page.jsx (Server Component)
import Tabs from '@/app/ui/tabs';
import Overview from '@/app/ui/overview';
import Analytics from '@/app/ui/analytics';

export default function DashboardPage() {
  const tabs = [
    { id: 'overview', label: 'Overview' },
    { id: 'analytics', label: 'Analytics' },
  ];

  return (
    
      
      
    
  );
}

Overview and Analytics can be Server Components that fetch their own data. They render on the server, and the client receives the pre-rendered output.

What Props Are Allowed Between Server and Client

Props passed from Server Components to Client Components must be serializable. React serializes them into the RSC Payload so they can be sent to the client.

Allowed Types

Strings, numbers, booleans
null and undefined
Plain objects (no functions, no class instances)
Arrays of serializable values
JSX (Server Components as children or other props)
Server Actions (functions with "use server")

Not Allowed

Functions (except Server Actions)
Date objects
Class instances
Symbols
Map, Set, WeakMap, WeakSet
Objects with custom prototypes
Buffers, ArrayBuffer, typed arrays

If you need to pass a Date, convert it to a string or number first:

If you use MongoDB, convert ObjectId to a string:

Passing Server Actions as props

Server Actions are async functions marked with "use server". You can pass them as props to Client Components. They are serialized by reference, not by value.

// app/actions/post.js
'use server';

export async function likePost(postId) {
  // Update database
  revalidatePath(`/post/${postId}`);
}

// app/post/[id]/page.jsx (Server Component)
import LikeButton from '@/app/ui/like-button';
import { likePost } from '@/app/actions/post';

export default async function PostPage({ params }) {
  const post = await getPost((await params).id);

  return ;
}

// app/ui/like-button.jsx (Client Component)
'use client';

export default function LikeButton({ likes, postId, onLike }) {
  const handleClick = () => {
    onLike(postId);
  };

  return ;
}

You can also bind arguments:

React Context doesn't work in Server Components. To share data between Server and Client Components, you can combine a Client Component context provider with React.cache for server-side memoization.

Create a cached fetch function:

// lib/user.js
import { cache } from 'react';

export const getUser = cache(async () => {
  const res = await fetch('https://api.example.com/user');
  return res.json();
});

Create a provider that accepts a promise and stores it in context:

// app/providers/user-provider.jsx
'use client';

import { createContext } from 'react';

export const UserContext = createContext(null);

export default function UserProvider({ children, userPromise }) {
  return (
    
      {children}
    
  );
}

In your root layout, pass the promise without awaiting it:

// app/layout.jsx
import UserProvider from '@/app/providers/user-provider';
import { getUser } from '@/lib/user';

export default function RootLayout({ children }) {
  const userPromise = getUser();

  return (
    
      
        {children}
      
    
  );
}

Client Components use use() to unwrap the promise:

// app/ui/profile.jsx
'use client';

import { use, useContext } from 'react';
import { UserContext } from '@/app/providers/user-provider';

export default function Profile() {
  const userPromise = useContext(UserContext);
  if (!userPromise) {
    throw new Error('Profile must be used within UserProvider');
  }
  const user = use(userPromise);

  return Welcome, {user.name};
}

Wrap the component in Suspense for loading states:

// app/dashboard/page.jsx
import { Suspense } from 'react';
import Profile from '@/app/ui/profile';

export default function DashboardPage() {
  return (
    Loading profile...}>
      
    
  );
}

Server Components can call getUser() directly. Because it's wrapped in React.cache, multiple calls in the same request return the same result:

// app/settings/page.jsx
import { getUser } from '@/lib/user';

export default async function SettingsPage() {
  const user = await getUser();
  return Settings for {user.name};
}

React.cache is scoped per request. Each request has its own memoization – there's no sharing across requests.

How to Use Third-Party Components in Both Environments

Some third-party components use useState, useEffect, or browser APIs but don't have "use client" in their source. If you use them in a Server Component, you'll get an error.

Wrap them in your own Client Component:

// app/ui/carousel-wrapper.jsx
'use client';

import { Carousel } from 'acme-carousel';

export default Carousel;

Now you can use it in a Server Component:

// app/gallery/page.jsx
import Carousel from '@/app/ui/carousel-wrapper';

export default function GalleryPage() {
  return (
    
      Gallery
      
    
  );
}

If the third-party component is already used inside a Client Component, you don't need a wrapper. The parent's "use client" boundary is enough:

'use client';

import { Carousel } from 'acme-carousel';

export default function Gallery() {
  return ;
}

How to Prevent Environment Poisoning with server-only and client-only

It's easy to accidentally import server-only code (database clients, API keys) into a Client Component. To catch this at build time, use the server-only package.

Install it:

npm install server-only

Add it at the top of files that must never run on the client:

// lib/data.js
import 'server-only';

export async function getSecretData() {
  const res = await fetch('https://api.example.com/data', {
    headers: {
      authorization: process.env.API_KEY,
    },
  });
  return res.json();
}

If you import getSecretData (or any symbol from this file) into a Client Component, the build will fail with a clear error.

For client-only code (for example, code that uses window), use client-only:

npm install client-only

// lib/analytics.js
import 'client-only';

export function trackEvent(name) {
  if (typeof window !== 'undefined') {
    window.analytics?.track(name);
  }
}

Importing this into a Server Component will cause a build error.

Real-World Examples

Example 1: Layout with Shared Server and Client Pieces

Keep the layout as a Server Component. Only the interactive parts are Client Components:

// app/layout.jsx (Server Component)
import Logo from '@/app/ui/logo';
import Search from '@/app/ui/search';

export default function Layout({ children }) {
  return (
    
      
        
          
          
        
        {children}
      
    
  );
}

// app/ui/logo.jsx (Server Component - no directive)
export default function Logo() {
  return ;
}

// app/ui/search.jsx (Client Component)
'use client';

import { useState } from 'react';

export default function Search() {
  const [query, setQuery] = useState('');

  return (
     setQuery(e.target.value)}
    />
  );
}

Logo stays on the server. Search is interactive and runs on the client. The layout composes both.

Example 2: Product Page with Server Data and Client Add-to-Cart

// app/product/[id]/page.jsx (Server Component)
import { getProduct } from '@/lib/products';
import AddToCartButton from '@/app/ui/add-to-cart-button';

export default async function ProductPage({ params }) {
  const { id } = await params;
  const product = await getProduct(id);

  return (
    
      {product.name}
      {product.description}
      ${product.price}
      
    
  );
}

// app/ui/add-to-cart-button.jsx (Client Component)
'use client';

import { useState } from 'react';

export default function AddToCartButton({ productId, price }) {
  const [added, setAdded] = useState(false);

  const handleClick = () => {
    // Call Server Action or API
    setAdded(true);
  };

  return (
    
  );
}

Example 3: Theme Provider Wrapping Server Content

// app/providers/theme-provider.jsx (Client Component)
'use client';

import { createContext, useContext, useState } from 'react';

const ThemeContext = createContext('light');

export function useTheme() {
  return useContext(ThemeContext);
}

export default function ThemeProvider({ children }) {
  const [theme, setTheme] = useState('light');

  return (
    
      {children}
    
  );
}

// app/layout.jsx (Server Component)
import ThemeProvider from '@/app/providers/theme-provider';

export default function RootLayout({ children }) {
  return (
    
      
        {children}
      
    
  );
}

ThemeProvider is a Client Component. It wraps children, which can be Server Components. Render providers as deep as possible in the tree so Next.js can optimize static Server Components.

Example 4: Shared Utility Without Directives

Pure utilities (no hooks, no browser APIs) can be shared. They run in the environment of the component that imports them:

// lib/format.js (shared - no directive)
export function formatPrice(amount) {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
  }).format(amount);
}

// Server Component
import { formatPrice } from '@/lib/format';

export default async function ProductPage() {
  const product = await getProduct();
  return {formatPrice(product.price)};
}

// Client Component
'use client';

import { formatPrice } from '@/lib/format';

export default function PriceDisplay({ amount }) {
  return {formatPrice(amount)};
}

formatPrice is a pure function. It works in both Server and Client Components.

Conclusion

Sharing components and data between Server and Client Components in Next.js comes down to a few patterns:

Pass data as props – Server Components fetch data and pass serializable values to Client Components.
Pass Server Components as children – Client Components can wrap server-rendered content via children or slot props.
Use serializable props only – Stick to primitives, plain objects, arrays, and Server Actions. Convert Date and ObjectId to strings.
Share data with Context + React.cache – Use a Client Component provider that receives a promise and React.cache for server-side deduplication.
Wrap third-party components – Add "use client" wrappers for libraries that use client-only features.
Use server-only and client-only – Prevent accidental imports across the server/client boundary.

Keep Server Components at the top of the tree and push Client Components down to leaf nodes. This reduces JavaScript sent to the browser while keeping interactivity where you need it.

How to Build Real-Time Update Systems with MQTT and Express.js

David Aniebo — Tue, 10 Mar 2026 16:05:25 +0000

Real-time updates are everywhere – like live sports scores, stock tickers, chat applications, and IoT dashboards. If you want to build systems that push data to users the moment it changes, you need the right tools.

Message Queuing Telemetry Transport (MQTT) is a lightweight messaging protocol that excels at this. Combined with a broker like Mosquitto and a web framework like Express, you can build a production-ready real-time system in a single afternoon.

In this tutorial, you'll build a complete real-time football (soccer) sports update system from scratch. You'll create an admin interface for uploading scores and match details, a viewer interface for watching live updates, and a backend that uses MQTT to broadcast changes instantly to every connected client.

By the end of this guide, you'll understand how to integrate MQTT with Express, set up the Mosquitto broker, and deliver real-time data to web browsers using Server-Sent Events. You will have a working system that you can extend for production use.

What You Will Learn
Prerequisites
Understanding the Architecture
What is MQTT and Why Use It?
- MQTT Topic Design
- Why Server-Sent Events Instead of WebSockets?
Project Setup
How to Set Up the MQTT Broker
How to Build the Express Server
How to Implement the Match Routes
How to Bridge MQTT to the Browser with Server-Sent Events
How to Build the Admin Upload Interface
- Admin HTML Structure and Styles
- Admin JavaScript Logic
How to Build the Live Viewer Interface
- Viewer JavaScript Logic
How to Build the Home Page
How to Run and Test the System
How to Extend the System for Production
API Reference
Troubleshooting
Conclusion

What You Will Learn

During this tutorial, you'll learn how to:

Connect an Express server to an MQTT broker using the MQTT.js library
Publish and subscribe to MQTT topics for real-time messaging
Use Server-Sent Events to push MQTT messages to web browsers
Build a REST application programming interface (API) for match and score management
Create a simple admin interface for uploading match data
Create a viewer interface that updates in real time without page refreshes

Prerequisites

Before you start, you should have:

Node.js version 18 or later installed on your machine
Basic familiarity with JavaScript, Express, and HTML
A terminal or command line for running commands
Docker installed (optional, for running Mosquitto in a container)

If you don't have Node.js installed, you can download it from the official Node.js website.

Understanding the Architecture

The system has three main parts:

Admin interface – A web page where you create matches, update scores, and add events such as goals and cards.
Express server – Receives HyperText Transfer Protocol (HTTP) requests from the admin, publishes data to MQTT, subscribes to MQTT topics, and streams updates to viewers via Server-Sent Events.
Viewer interface – A web page that connects to the server and displays live scores and events as they arrive.

How the flow works
When you submit a score update in the admin panel, the Express server publishes a message to the MQTT broker. The server also subscribes to those same topics. When a message arrives, the server forwards it to all connected viewers through Server-Sent Events. The viewers update their display without refreshing the page.

What is MQTT and Why Use It?

MQTT stands for Message Queuing Telemetry Transport. It's a lightweight, publish-subscribe messaging protocol designed for low bandwidth and unreliable networks. It's widely used in Internet of Things (IoT) applications, but it works well for any real-time system where you need to broadcast updates to many subscribers.

Here are some reasons to use MQTT for a sports update system:

Low overhead: Messages are small and efficient, which helps when you have many clients.
Built-in Quality of Service (QoS): You can choose how many times a message is delivered (at most once, at least once, or exactly once).
Topic-based routing: You organize messages by topic (for example, sports/football/match/123) so subscribers receive only what they need.
Broker-based: A central broker (Mosquitto) handles all message distribution, so your application logic stays simple.

Mosquitto is a popular, open-source MQTT broker that's easy to install and configure.

MQTT Topic Design

MQTT uses a hierarchical topic structure. For this project, the topics are:

sports/football/match/{id}: One topic per match. When you publish the full match object here, any subscriber receives the complete state. This makes it easy to add new match fields later without changing the topic structure.
sports/football/scores: A single topic for score-related notifications. Messages include a type field (match_created or score_update) so subscribers can handle them differently.
sports/football/events: A topic for match events such as goals and cards. Subscribers receive { type: 'match_event', matchId, event }.

The # wildcard in a subscription means "match this level and all levels below." So sports/football/# subscribes to every topic under sports/football, including sports/football/match/abc123 and sports/football/scores. The + wildcard matches exactly one level. For example, sports/+/match/# would match any sport, not just football.

Why Server-Sent Events Instead of WebSockets?

You might wonder why this tutorial uses Server-Sent Events (SSE) instead of WebSockets. Both can push data to the browser. The main difference:

Server-Sent Events: One-way (server to client). Built on HTTP. Automatic reconnection in the browser. Simpler to implement. No extra libraries.
WebSockets: Two-way. Requires a different protocol. More flexible but more complex.

For a sports score viewer, you only need server-to-client updates. The viewer never sends messages back over the same channel. Server-Sent Events is a better fit. If you later need the client to send commands (for example, to filter by league), you can add a separate HTTP API or switch to WebSockets.

Project Setup

Start by creating a new folder for your project and initialize it with npm. The mkdir command creates the directory, cd moves into it, and npm init -y creates a package.json file with default values without prompting you for input.

mkdir mqtt-football-scores
cd mqtt-football-scores
npm init -y

Install the required dependencies. Each package serves a specific role in the application. Run this command in the project root directory.

npm install express cors mqtt uuid

express: Web framework for the HTTP server and API. It provides routing, middleware, and static file serving.
cors: Enables Cross-Origin Resource Sharing so your frontend can call the API from a different origin (for example, if you serve the HTML from a different port or domain).
mqtt: MQTT client for Node.js. It handles connection, publish, subscribe, reconnection, and Quality of Service (QoS) flows.
uuid: Generates unique identifiers (Universally Unique Identifiers) for matches and events. Each ID is practically unique across all systems.

Next, create the following folder structure. The server folder holds the Node.js backend code. The public folder holds the HTML, CSS, and client-side JavaScript that the browser loads. The routes subfolder keeps the match-related route handlers separate from the main server file.

mqtt-football-scores/
├── server/
│   ├── index.js
│   ├── sse.js
│   └── routes/
│       └── matches.js
├── public/
│   ├── index.html
│   ├── admin.html
│   └── viewer.html
├── mosquitto.conf
├── docker-compose.yml
└── package.json

Add "type": "module" to your package.json so you can use JavaScript modules (import and export). The type field tells Node.js to treat .js files as ES modules, which allows you to use import and export syntax instead of CommonJS require and module.exports.

{
  "name": "mqtt-football-scores",
  "version": "1.0.0",
  "type": "module",
  "main": "server/index.js"
}

How to Set Up the MQTT Broker

You need an MQTT broker running before the server can connect. You have three options.

Option 1: Docker (Recommended)

Create a docker-compose.yml file. This file defines a single service named mosquitto that runs the Eclipse Mosquitto 2 image. The ports directive maps port 1883 on your host to port 1883 in the container so your Express server can connect. The volumes directive mounts your local mosquitto.conf into the container so the broker uses your configuration. The restart: unless-stopped option ensures the container restarts automatically if it crashes or if you reboot your machine.

version: "3.8"

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mqtt-football-mosquitto
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf
    restart: unless-stopped

Create a mosquitto.conf file. The listener 1883 directive tells Mosquitto to listen on port 1883 for MQTT connections. The protocol mqtt specifies the standard MQTT protocol (as opposed to WebSocket). The allow_anonymous true setting permits connections without a username and password, which is fine for local development but should be disabled in production. The log_dest stdout and log_type all directives send all log output to the console so you can debug connection issues.

listener 1883
protocol mqtt
allow_anonymous true
log_dest stdout
log_type all

Start the broker:

docker-compose up -d

Option 2: Local Install

On macOS with Homebrew:

brew install mosquitto
mosquitto -c mosquitto.conf

On Ubuntu or Debian:

sudo apt install mosquitto mosquitto-clients
sudo systemctl start mosquitto

Option 3: Public Test Broker

You can use the public test broker at test.mosquitto.org without installing anything. Set the environment variable when you start the server:

MQTT_BROKER=mqtt://test.mosquitto.org npm start

Note: The public broker is shared and not suitable for production. Use it only for development and testing.

How to Build the Express Server

In this step, you'll create the main server that powers the real-time application. The Express server handles HTTP requests, serves static files like HTML and JavaScript, and acts as the bridge between the browser and the MQTT broker. It also provides endpoints that allow data to be sent and received in real time. Essentially, this server is the backbone of the application, enabling communication between all components.

Begin by creating the main server file at server/index.js:

import express from 'express';
import cors from 'cors';
import mqtt from 'mqtt';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
import { v4 as uuidv4 } from 'uuid';

import { matchRoutes } from './routes/matches.js';
import { setupSSE, addSSEClient } from './sse.js';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const MQTT_BROKER = process.env.MQTT_BROKER || 'mqtt://localhost:1883';
const PORT = process.env.PORT || 3000;

const app = express();
app.use(cors());
app.use(express.json());
app.use(express.static(join(__dirname, '../public')));

let mqttClient = null;

function connectMQTT() {
  mqttClient = mqtt.connect(MQTT_BROKER, {
    clientId: `football-scores-${uuidv4().slice(0, 8)}`,
    reconnectPeriod: 3000,
    connectTimeout: 10000,
  });

  mqttClient.on('connect', () => {
    console.log('Connected to MQTT broker at', MQTT_BROKER);
    mqttClient.subscribe('sports/football/#', { qos: 1 }, (err) => {
      if (err) console.error('Subscribe error:', err);
    });
  });

  mqttClient.on('error', (err) => {
    console.error('MQTT error:', err.message);
  });

  mqttClient.on('close', () => {
    console.log('MQTT connection closed');
  });

  mqttClient.on('reconnect', () => {
    console.log('MQTT reconnecting...');
  });

  return mqttClient;
}

const mqttClientInstance = connectMQTT();
const { publishMatch, publishScoreUpdate, publishEvent, getMatches } = matchRoutes(mqttClientInstance);
setupSSE(mqttClientInstance);

app.get('/api/events', (req, res) => addSSEClient(res));
app.post('/api/matches', publishMatch);
app.patch('/api/matches/:id/score', publishScoreUpdate);
app.post('/api/matches/:id/events', publishEvent);
app.get('/api/matches', getMatches);

app.listen(PORT, () => {
  console.log(`Football Scores Server running at http://localhost:${PORT}`);
  console.log(`Admin (upload):  http://localhost:${PORT}/admin.html`);
  console.log(`Viewer:          http://localhost:${PORT}/viewer.html`);
});

Here is what each part does:

Imports: The fileURLToPath and dirname utilities replicate the __dirname variable that CommonJS provides, since ES modules don't have it. You need __dirname to build the path to the public folder.
Environment variables: MQTT_BROKER defaults to mqtt://localhost:1883 so the server connects to a local Mosquitto instance. You can override it for Docker or a remote broker. PORT defaults to 3000.
Middleware: cors() allows requests from any origin, which is useful during development. express.json() parses JSON request bodies. express.static() serves files from public so /admin.html and /viewer.html are available.
connectMQTT: Creates an MQTT client with a unique client ID (required by the broker), a 3-second reconnect interval, and a 10-second connection timeout. On connect, it subscribes to sports/football/# with QoS 1. The # wildcard means "all topics under sports/football."
matchRoutes: Returns the route handlers that create matches, update scores, and add events. Each handler publishes to MQTT and responds with JSON.
setupSSE: Registers a listener on the MQTT client's message event. When a message arrives, it forwards the payload to all connected Server-Sent Events clients.
addSSEClient: Called when a viewer opens /api/events. It sets the response headers for Server-Sent Events, flushes the headers so the connection stays open, and adds the response object to a set of active clients.
Routes: The GET /api/events route establishes the Server-Sent Events stream. The POST, PATCH, and GET routes for matches delegate to the handlers from matchRoutes.

The server serves static files from the public folder, so your HTML pages are available at the root.

How to Implement the Match Routes

In this step, you'll create the route handlers that manage matches, scores, and events. These routes allow the server to receive requests from the admin interface, update match data, and publish real-time updates to MQTT. They also store match information in memory so it can be retrieved and updated during the session.

Begin by creating the file at server/routes/matches.js:

import { v4 as uuidv4 } from 'uuid';

const TOPIC_MATCH = 'sports/football/match';
const TOPIC_SCORES = 'sports/football/scores';
const TOPIC_EVENTS = 'sports/football/events';

const matches = new Map();

function publish(client, topic, payload, qos = 1) {
  if (!client?.connected) {
    console.warn('MQTT not connected, message not published');
    return false;
  }
  client.publish(topic, JSON.stringify(payload), { qos, retain: false });
  return true;
}

export function matchRoutes(mqttClient) {
  return {
    publishMatch: (req, res) => {
      const { homeTeam, awayTeam, league, venue, kickoff } = req.body;
      if (!homeTeam || !awayTeam) {
        return res.status(400).json({ error: 'homeTeam and awayTeam are required' });
      }

      const match = {
        id: uuidv4(),
        homeTeam,
        awayTeam,
        homeScore: 0,
        awayScore: 0,
        league: league || 'Premier League',
        venue: venue || 'TBD',
        kickoff: kickoff || new Date().toISOString(),
        status: 'scheduled',
        minute: 0,
        events: [],
        createdAt: new Date().toISOString(),
      };

      matches.set(match.id, match);

      const topic = `\({TOPIC_MATCH}/\){match.id}`;
      publish(mqttClient, topic, match);
      publish(mqttClient, TOPIC_SCORES, { type: 'match_created', match });

      res.status(201).json(match);
    },

    publishScoreUpdate: (req, res) => {
      const { id } = req.params;
      const { homeScore, awayScore, minute, status } = req.body;

      const match = matches.get(id);
      if (!match) {
        return res.status(404).json({ error: 'Match not found' });
      }

      if (homeScore !== undefined) match.homeScore = homeScore;
      if (awayScore !== undefined) match.awayScore = awayScore;
      if (minute !== undefined) match.minute = minute;
      if (status !== undefined) match.status = status;

      const topic = `\({TOPIC_MATCH}/\){id}`;
      publish(mqttClient, topic, match);
      publish(mqttClient, TOPIC_SCORES, {
        type: 'score_update',
        matchId: id,
        homeScore: match.homeScore,
        awayScore: match.awayScore,
        minute: match.minute,
        status: match.status,
      });

      res.json(match);
    },

    publishEvent: (req, res) => {
      const { id } = req.params;
      const { type, team, player, minute, description } = req.body;

      const match = matches.get(id);
      if (!match) {
        return res.status(404).json({ error: 'Match not found' });
      }

      const event = {
        id: uuidv4().slice(0, 8),
        type: type || 'goal',
        team,
        player: player || 'Unknown',
        minute: minute ?? match.minute,
        description: description || `\({type}: \){player}`,
        timestamp: new Date().toISOString(),
      };

      match.events.push(event);
      if (type === 'goal') {
        if (team === match.homeTeam) match.homeScore++;
        else if (team === match.awayTeam) match.awayScore++;
      }

      const topic = `\({TOPIC_MATCH}/\){id}`;
      publish(mqttClient, topic, match);
      publish(mqttClient, TOPIC_EVENTS, { type: 'match_event', matchId: id, event });

      res.status(201).json({ match, event });
    },

    getMatches: (req, res) => {
      const list = Array.from(matches.values()).sort(
        (a, b) => new Date(b.createdAt) - new Date(a.createdAt)
      );
      res.json(list);
    },
  };
}

The routes use an in-memory Map to store matches. In production, you would replace this with a database such as PostgreSQL or MongoDB.

Explanation of the key logic:

publish: A helper that checks if the MQTT client is connected before publishing. If the broker is down, it logs a warning instead of throwing. The retain: false option means the broker doesn't store the last message for new subscribers.
publishMatch: Validates that homeTeam and awayTeam are present. Creates a match object with default values for league, venue, kickoff, status, and events. Stores it in the Map, publishes to the match-specific topic and the scores topic, and returns the match with status 201 (Created).
publishScoreUpdate: Looks up the match by ID. If not found, returns 404. Updates only the fields that are provided (using !== undefined so you can set a score to 0). Publishes the full match and a score_update notification.
publishEvent: Creates an event object with a short unique ID. Pushes it to the match's events array. If the event type is goal, increments the home or away score based on the team. Publishes the updated match and an event notification.
getMatches: Converts the Map to an array, sorts by createdAt descending (newest first), and returns the list as JSON.

MQTT topics used:

sports/football/match/{id}: Full match state. Used when a match is created or updated.
sports/football/scores: Score change notifications. Used for match creation and score updates.
sports/football/events: Match events such as goals and cards.

The publish function sends JavaScript Object Notation (JSON) payloads with QoS 1 (at least once delivery). MQTT defines three QoS levels: 0 (at most once), 1 (at least once), and 2 (exactly once). Level 1 ensures the broker will retry until the subscriber acknowledges the message, which reduces the chance of losing score updates if the connection drops briefly.

How to Bridge MQTT to the Browser with Server-Sent Events

In this step, you'll create the Server-Sent Events (SSE) module that bridges MQTT messages to the browser. MQTT works over TCP and browsers cannot connect to it directly, so we use SSE as a lightweight HTTP-based streaming channel. SSE keeps an open connection and allows the server to push updates to connected browsers in real time. This is what enables viewers to see match updates instantly without refreshing.

Now create the file at server/sse.js:

const clients = new Set();

export function setupSSE(mqttClient) {
  if (!mqttClient) return;

  mqttClient.on('message', (topic, message) => {
    try {
      const payload = JSON.parse(message.toString());
      const data = JSON.stringify({ topic, ...payload });
      clients.forEach((res) => {
        try {
          res.write(`data: ${data}\n\n`);
        } catch (e) {
          clients.delete(res);
        }
      });
    } catch (e) {
      console.error('SSE parse error:', e.message);
    }
  });
}

export function addSSEClient(res) {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  res.setHeader('X-Accel-Buffering', 'no');
  res.flushHeaders();

  clients.add(res);

  res.on('close', () => {
    clients.delete(res);
  });
}

Explanation of each part:

clients Set: A Set holds all active Server-Sent Events response objects. Using a Set makes it easy to add and remove clients without duplicates.
setupSSE: Attaches a message listener to the MQTT client. When any message arrives on a subscribed topic, the callback runs. It parses the message payload (which is JSON), merges the topic into the payload with { topic, ...payload }, and sends the result to every client. The Server-Sent Events format requires each message to be data: {content}\n\n (two newlines). The forEach loop catches write errors (for example, if a client disconnected) and removes the client from the set.
addSSEClient: Sets the Content-Type header to text/event-stream so the browser treats the response as an event stream. The Cache-Control: no-cache and Connection: keep-alive headers prevent the browser or proxy from caching or closing the connection. The X-Accel-Buffering: no header disables buffering in Nginx, which can delay or block Server-Sent Events. The flushHeaders call sends the headers immediately so the connection is established. The close event handler removes the client when the client disconnects (closes the tab or navigates away).

Server-Sent Events is one-way (server to client). For this use case, that is enough because viewers only need to receive updates, not send messages back over the same channel.

How to Build the Admin Upload Interface

The admin interface is a single HTML page where match creators can create new matches, update scores, and add events such as goals or cards. It uses standard HTML forms so data can be submitted to the server, and JavaScript will later handle form submissions and dynamic updates. All the markup, styles, and script live in public/admin.html, which the Express server serves as a static page.

Admin HTML Structure and Styles

The document starts with the standard HTML5 boilerplate. The charset and viewport meta tags ensure proper character encoding and responsive layout on mobile devices. The page loads the Outfit font from Google Fonts for a clean, modern look.

The Cascading Style Sheets (CSS) uses custom properties (variables) in the :root block so you can change the color scheme in one place. The --bg variable holds the dark background color, --surface for card backgrounds, --accent for the green accent color, and --text-muted for secondary text. The .grid class creates a two-column layout for form fields that collapses to one column on screens under 600 pixels wide. The .toast class positions the notification at the bottom-right and uses transform and opacity for a slide-in animation when the .show class is added.

Now create the file at public/admin.html:




  
  
  Admin - Football Scores Upload
  
  
  
  


  
    
      ⚽ Football Scores
      Admin
      → Open Viewer
    

    
      Create New Match
      
        
          
            Home Team
            
          
          
            Away Team
            
          
          
            League
            
          
          
            Venue
            
          
          
            Kickoff (ISO)
            
          
        
        
          
        
      
    

    
      Update Score
      
        
          
            Select Match
            
          
          
            Home Score
            
          
          
            Away Score
            
          
          
            Minute
            
          
          
            Status
            
          
        
        
          
        
      
    

    
      Add Match Event (Goal, Card, etc.)
      
        
          
            Select Match
            
          
          
            Event Type
            
          
          
            Team
            
          
          
            Player
            
          
          
            Minute
            
          
          
            Description
            
          
        
        
          
        
      
    

    
      Active Matches

The three forms use id attributes (createMatch, updateScore, addEvent) so the JavaScript can attach submit handlers. The match dropdowns (scoreMatchId and eventMatchId) are populated dynamically when the page loads. The matchList div is the container for the list of active matches. The toast element sits outside the main container so it can be fixed to the viewport.

Admin JavaScript Logic

The script block handles all interaction between the admin page and the server. It defines helper functions for showing notifications, fetching matches, updating the UI, and submitting data. When the page loads or after any action (create, update, or event submission), the UI refreshes so the latest match data is always visible.

Explanation of each part:

showToast: updates the toast text and adds the show class to trigger the CSS animation. The isError parameter switches the toast to a red background for error messages. The setTimeout removes the show class after 3 seconds so the toast slides back out.
fetchMatches: calls the GET /api/matches endpoint and returns the parsed JSON so the UI can display the latest data.
populateSelects: builds option elements from the matches array and injects them into both dropdowns, so the same match list appears in the Update Score and Add Event forms.
renderMatchList: either shows a placeholder when there are no matches or renders each match as a card with team names, scores, league, status, and an Update button.
quickScore: pre-fills the Update Score form when you click the Update button on a match card, so you can adjust the score without re-selecting the match.
loadMatches: fetches matches, populates the dropdowns, and renders the list. It runs on page load and after every successful create, update, or event submission.
onsubmit: calls e.preventDefault() to stop the default form submission, builds a request body from the form values, sends a fetch request to the appropriate endpoint, and on success shows a toast and calls loadMatches to refresh the UI.

How to Build the Live Viewer Interface

The viewer interface displays real-time match updates and connects to the Server-Sent Events endpoint so it can receive data the moment the server pushes it.

Unlike the admin page, the viewer is read-only: it shows live scores, match events, and status updates without requiring user input. The page uses a dark theme and a connection indicator so users can see whether the real-time stream is active.

Now create the file at public/viewer.html:




  
  
  Live Football Scores
  
  
  
  


  
    
      ⚽ Live Football Scores
      
        
        Connecting...
      
    

    

    
      Live Feed

Explanation of each part:

header: displays the page title and a connection indicator so users know whether the real-time stream is active.
status dot: a small circle that pulses while disconnected and turns green with a glow when the SSE connection is established.
matches container: the div with id="matches" is where match cards will be rendered dynamically by JavaScript as data arrives.
feed section: shows a chronological list of live updates so users can see recent events at a glance.
CSS theme: uses dark colors and custom properties so the look can be adjusted in one place. The live badge and border styles highlight matches that are in progress.
Server-Sent Events integration: JavaScript (added in the next step) will connect to /api/events and update this page whenever new data arrives.

The header shows the title and a connection status indicator. The matches div is the container for match cards, populated by JavaScript. The feed div displays the live feed of recent updates.

Viewer JavaScript Logic

The script powers the live viewer interface by maintaining an in-memory collection of matches and a feed of recent updates. It connects to the Server-Sent Events endpoint so data flows from the server to the browser in real time. When messages arrive, the page updates automatically to show the latest scores, events, and match details.

Explanation of each part:

The matches Map: stores match objects keyed by ID so updates can be applied efficiently without searching arrays.
The feed array: keeps a small history of recent events (limited to MAX_FEED) so the live feed remains lightweight.
setStatus: toggles the connected class on the status dot and updates the status text to “Live” or “Reconnecting…” so users know connection status.
renderMatches: converts the Map to a sorted array (newest first). If there are no matches, it displays an empty state. Otherwise it renders cards showing league, venue, teams, scores, status badge, minute, and events.
getEventIcon: returns an emoji for each event type so events are visually identifiable (goal, card, substitution, and so on).
renderFeed: displays the live feed items or a placeholder message when no updates exist.
addFeedItem: appends a timestamped message to the feed, keeps only the latest items, and re-renders the feed.
handleMessage: processes incoming data. It updates the matches Map for full match objects, score updates, and match events. For score updates and goals it adjusts scores and adds feed items so the viewer reflects real-time changes.
handleSSEMessage: parses the Server-Sent Events payload and forwards it to handleMessage. If the message contains a match topic and full match data, it stores it in the Map.
connectSSE: creates an EventSource connection to /api/events. On open it marks the connection as live. On error it closes and retries after three seconds so transient network issues do not break the stream.
loadInitial: fetches existing matches on page load so the viewer displays data even before real-time updates arrive.

How to Build the Home Page

The home page (public/index.html) is a simple landing page that links to the viewer and admin interfaces. It uses a centered card layout with two buttons. The primary button (green) goes to the viewer, and the secondary button (outlined) goes to the admin. The page uses the same dark theme and Outfit font for consistency. There is no JavaScript – it's purely static HTML and CSS.




  
  
  Football Scores - MQTT Real-Time
  
  
  
  


  
    ⚽ Football Scores
    Real-time updates via MQTT & Mosquitto
    
      View Live Scores
      Admin - Upload Scores

The Express server serves index.html when you visit the root URL (http://localhost:3000/) because the express.static middleware serves files from the public folder, and Express automatically serves index.html when the request path is /.

How to Run and Test the System

Start the MQTT broker (Docker or local install).

Then start the Express server:

npm start

Next, open http://localhost:3000/admin.html in the admin panel. Create a new match (for example, Manchester United vs Liverpool).

Open http://localhost:3000/viewer.html in another tab or window. Then update the score or add an event in the admin panel. The viewer should update within a second without refreshing.

How to Extend the System for Production

The current implementation uses in-memory storage. For production, you should:

Add a database: Store matches in PostgreSQL, MongoDB, or another database. Load matches on startup and persist every create, update, and event.
Add authentication: Protect the admin routes with JSON Web Tokens (JWT) or session-based auth so only authorized users can upload scores.
Add validation: Validate request bodies with a library such as Joi or Zod to prevent invalid data.
Enable TLS: Use HTTPS for the Express server and secure WebSockets or MQTTS for the broker in production.
Scale horizontally: If you run multiple server instances, each will have its own MQTT connection and SSE clients. The MQTT broker will deliver messages to all subscribers, so each instance will receive updates and forward them to its connected viewers.

API Reference

For quick reference, here are the endpoints your server exposes:

Method	Endpoint	Description
GET	`/api/matches`	Returns all matches as a JSON array
POST	`/api/matches`	Creates a new match. Body: `{ homeTeam, awayTeam, league?, venue?, kickoff? }`
PATCH	`/api/matches/:id/score`	Updates a match score. Body: `{ homeScore?, awayScore?, minute?, status? }`
POST	`/api/matches/:id/events`	Adds an event. Body: `{ type?, team, player?, minute?, description? }`
GET	`/api/events`	Server-Sent Events stream for real-time updates

The status field can be scheduled, live, halftime, or finished. The type field for events can be goal, yellow_card, red_card, substitution, or penalty.

Troubleshooting

You might come across various issues as you build this. Here are some common ones:

The server cannot connect to the MQTT broker. Check that Mosquitto is running. If you use Docker, run docker ps to verify the container is up. If you use the public broker, ensure you have internet connectivity and that your firewall allows outbound connections on port 1883.

The viewer does not update when you change scores. Open the browser developer tools and check the Network tab. The /api/events request should show a pending state (it stays open). If it fails or closes, check the server logs for errors. Ensure you are not behind a proxy that buffers or closes long-lived connections.

Matches disappear when you restart the server. The current implementation stores matches in memory. Restarting the server clears the data. Add a database as described in the production section to persist matches across restarts.

Conclusion

In this tutorial, you built a real-time football sports update system using MQTT, Mosquitto, and Express. You've learned how to:

Connect an Express server to an MQTT broker
Publish match and score updates to MQTT topics
Subscribe to topics and forward messages to browsers via Server-Sent Events
Build an admin interface for creating matches and updating scores
Build a viewer interface that displays live updates without page refreshes

The same pattern applies to other real-time systems: IoT dashboards, live notifications, collaborative editing, and more. MQTT gives you a reliable, scalable messaging layer, and Server-Sent Events gives you a simple way to push updates to web clients.

The code in this tutorial gives you a solid foundation. Try adding features such as match filtering by league, historical event logs, or push notifications to make the system your own.

How to Build a Production-Ready Feature Flag System with Next.js and Supabase

David Aniebo — Thu, 05 Feb 2026 22:40:14 +0000

Feature flags are powerful tools that let you control which features are visible to users without deploying new code. They enable gradual rollouts, A/B testing, and instant feature toggles, which are all essential for modern software development.

In this article, we’ll build a real, production-ready feature flag system, not just a simple boolean toggle.

Specifically, we’ll implement:

A global on/off flag to enable or disable features instantly
User-specific flags to grant access to individual users (for beta testing or internal users)
Percentage-based rollouts to gradually expose features to a subset of users
A React-powered admin dashboard to manage flags without redeploying
Client-side and server-side enforcement, so features are gated consistently everywhere

By the end, we’ll finish by wiring a real Todo feature behind a feature flag, showing how entire pages and components can be safely toggled on and off in production.

What Are Feature Flags?
Prerequisites
Project Setup
Database Schema Design
Setting Up Supabase
Building the Core Feature Flag Logic
Setting Up React Query
Creating the React Hook
Building the Admin Dashboard
Implementing a Real-World Example
Server-Side Usage
Why React Query?
Conclusion

Prerequisites

Before you begin, make sure you have:

Node.js 18 or higher installed
A basic understanding of React and Next.js
Familiarity with TypeScript
A Supabase account (free tier works perfectly)
A code editor like VS Code
Basic understanding of React Query (TanStack Query) for server state management

What Are Feature Flags?

Feature flags (also called feature toggles) are configuration mechanisms that let you enable or disable features in your application without changing code. Think of them as light switches for your features.

Here are some common use cases:

Gradual rollouts: Release a feature to 10% of users first, then gradually increase
User-specific access: Enable features for beta testers or VIP users
Emergency kill switches: Instantly disable a feature if something goes wrong
A/B testing: Test different versions of features with different user groups

Project Setup

Start by creating a new Next.js project with TypeScript:

npx create-next-app@latest supabase-feature-flag --typescript --tailwind --app
cd supabase-feature-flag

Next, install the required dependencies:

npm install @supabase/ssr @supabase/supabase-js @tanstack/react-query

The @supabase/ssr package provides server-side rendering support for Supabase, which is essential for Next.js App Router. @tanstack/react-query provides powerful server state management with automatic caching, invalidation, and real-time updates, which is perfect for feature flags that need to reflect changes immediately without page refreshes.

Database Schema Design

Before writing any code, you need to design your database schema. A feature flag needs several properties:

A unique key to identify the flag
A name and description for human readability
An enabled/disabled state
Support for user-specific access
Support for percentage-based rollouts

Here's the SQL migration that creates the feature_flags table:

-- Create feature_flags table
CREATE TABLE IF NOT EXISTS feature_flags (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  key TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  description TEXT,
  enabled BOOLEAN DEFAULT false NOT NULL,
  enabled_for_users JSONB DEFAULT '[]'::jsonb,
  enabled_for_percent INTEGER DEFAULT 0 CHECK (enabled_for_percent >= 0 AND enabled_for_percent <= 100),
  metadata JSONB DEFAULT '{}'::jsonb,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
);

Let's break down each field:

id: A unique identifier for each flag
key: A unique string identifier (like "new-dashboard" or "beta-feature")
name: A human-readable name
description: Optional description of what the flag controls
enabled: Global on/off switch
enabled_for_users: JSON array of user IDs who have access
enabled_for_percent: Percentage of users who should see the feature (0-100)
metadata: Flexible JSON field for additional configuration
created_at and updated_at: Timestamps for tracking

The migration also includes indexes for performance:

-- Create indexes for fast lookups
CREATE INDEX IF NOT EXISTS idx_feature_flags_key ON feature_flags(key);
CREATE INDEX IF NOT EXISTS idx_feature_flags_enabled ON feature_flags(enabled);

Indexes on key and enabled ensure fast queries when checking flag status.

Setting Up Supabase

Step 1: Create a Supabase Project

To start, go to supabase.com and sign up or log in. Then click on "New Project". Fill in your project details and wait for it to initialize.

Step 2: Run the Migration

In your Supabase dashboard, navigate to the SQL Editor:

Then click "New Query". Copy and paste the complete migration SQL (including the indexes and RLS policies shown below) and click "Run".

Here's the complete migration with Row Level Security (RLS) policies:

-- Create feature_flags table
CREATE TABLE IF NOT EXISTS feature_flags (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  key TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  description TEXT,
  enabled BOOLEAN DEFAULT false NOT NULL,
  enabled_for_users JSONB DEFAULT '[]'::jsonb,
  enabled_for_percent INTEGER DEFAULT 0 CHECK (enabled_for_percent >= 0 AND enabled_for_percent <= 100),
  metadata JSONB DEFAULT '{}'::jsonb,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
);

-- Create indexes
CREATE INDEX IF NOT EXISTS idx_feature_flags_key ON feature_flags(key);
CREATE INDEX IF NOT EXISTS idx_feature_flags_enabled ON feature_flags(enabled);

-- Auto-update updated_at timestamp
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = NOW();
  RETURN NEW;
END;
$$ language 'plpgsql';

CREATE TRIGGER update_feature_flags_updated_at
  BEFORE UPDATE ON feature_flags
  FOR EACH ROW
  EXECUTE FUNCTION update_updated_at_column();

-- Enable Row Level Security
ALTER TABLE feature_flags ENABLE ROW LEVEL SECURITY;

-- Policy: Allow public read access
CREATE POLICY "Allow public read access"
  ON feature_flags
  FOR SELECT
  USING (true);

-- Policy: Allow public write access (for admin operations)
CREATE POLICY "Allow public write access"
  ON feature_flags
  FOR ALL
  USING (true)
  WITH CHECK (true);

The RLS policies allow:

Public read access: Anyone can check if a feature flag is enabled
Public write access: Allows the admin dashboard to create/update flags (in production, you'd restrict this further)

Step 3: Get Your API Credentials

Go to Settings and then API in your Supabase project. Copy your Project URL and Publishable Key. THen create a .env.local file in your project root:

NEXT_PUBLIC_SUPABASE_URL=your_project_url
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=your_publishable_key

Building the Core Feature Flag Logic

Now let's build the core logic for checking feature flags. You'll create separate utilities for client-side and server-side usage.

TypeScript Types

First, define the types you'll use throughout the application:

// types/feature-flag.ts
export interface FeatureFlag {
  id: string;
  key: string;
  name: string;
  description: string | null;
  enabled: boolean;
  enabled_for_users: string[];
  enabled_for_percent: number;
  metadata: Record<string, any>;
  created_at: string;
  updated_at: string;
}

export interface FeatureFlagCheckResult {
  enabled: boolean;
  reason?: string;
}

The FeatureFlag interface matches your database schema. The FeatureFlagCheckResult includes a reason field that explains why a flag is enabled or disabled, which is useful for debugging.

Supabase Client Setup

Create the Supabase client for client-side usage:

// lib/supabase/client.ts
import { createBrowserClient } from "@supabase/ssr";

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY;

export const createClient = () =>
  createBrowserClient(supabaseUrl!, supabaseKey!);

The createBrowserClient function from @supabase/ssr creates a client optimized for browser usage.

For server-side usage:

// lib/supabase/server.ts
import { createServerClient, type CookieOptions } from "@supabase/ssr";
import { cookies } from "next/headers";

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY;

export const createClient = (cookieStore: ReturnType<typeof cookies>) => {
  return createServerClient(
    supabaseUrl!,
    supabaseKey!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll()
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            )
          } catch {
            // The `setAll` method was called from a Server Component.
            // This can be ignored if you have middleware refreshing
            // user sessions.
          }
        },
      },
    },
  );
};

This server client handles cookies properly for Next.js server components and API routes.

Client-Side Feature Flag Logic

Create the client-side utility for checking feature flags:

// lib/feature-flags/client.ts
import { createClient } from '@/lib/supabase/client';
import { FeatureFlag, FeatureFlagCheckResult } from '@/types/feature-flag';

// Simple cache with 5 second TTL (React Query handles primary caching)
// This cache is just for reducing redundant calls within a very short window
const cache = new Map<string, { data: FeatureFlag | null; expires: number }>();
const CACHE_TTL = 5000; // 5 seconds - short enough to not interfere with React Query invalidation

function getCached(key: string): FeatureFlag | null | undefined {
  const cached = cache.get(key);
  if (cached && cached.expires > Date.now()) {
    return cached.data;
  }
  return undefined;
}

function setCached(key: string, data: FeatureFlag | null): void {
  cache.set(key, { data, expires: Date.now() + CACHE_TTL });
}

The cache reduces database queries by storing flag data in memory for 5 seconds. This is a secondary cache layer – React Query handles the primary caching and automatic invalidation, ensuring changes reflect immediately across all components.

The getFeatureFlag function fetches a flag from the database:

export async function getFeatureFlag(key: string): Promise<FeatureFlag | null> {
  const cached = getCached(key);
  if (cached !== undefined) return cached;

  const supabase = createClient();
  const { data, error } = await supabase
    .from('feature_flags')
    .select('*')
    .eq('key', key)
    .single();

  if (error) {
    if (error.code === 'PGRST116') {
      setCached(key, null);
      return null;
    }
    console.error('Error fetching feature flag:', error);
    return null;
  }

  setCached(key, data);
  return data;
}

The function first checks the cache. If the flag isn't cached, it queries Supabase. The error code PGRST116 means "not found." In that case, you cache null to avoid repeated queries for non-existent flags.

The core logic is in isFeatureEnabled:

export async function isFeatureEnabled(
  key: string,
  userId?: string
): Promise<FeatureFlagCheckResult> {
  const flag = await getFeatureFlag(key);

  if (!flag) {
    return { enabled: false, reason: 'Flag not found' };
  }

  if (!flag.enabled) {
    return { enabled: false, reason: 'Flag is globally disabled' };
  }

  // Check user-specific access
  if (userId && flag.enabled_for_users.length > 0) {
    if (flag.enabled_for_users.includes(userId)) {
      return { enabled: true, reason: 'User has explicit access' };
    }
    return { enabled: false, reason: 'User not in allowed list' };
  }

  // Check percentage rollout
  if (flag.enabled_for_percent > 0) {
    const hash = simpleHash(userId || key);
    const percentage = hash % 100;
    const enabled = percentage < flag.enabled_for_percent;

    return {
      enabled,
      reason: enabled
        ? `User falls within ${flag.enabled_for_percent}% rollout`
        : `User falls outside ${flag.enabled_for_percent}% rollout`,
    };
  }

  return { enabled: true, reason: 'Flag is globally enabled' };
}

The function follows this logic:

Flag doesn't exist: Return disabled
Flag is globally disabled: Return disabled
User-specific list exists: Check if the user is in the list
Percentage rollout is set: Use a hash function to assign users to buckets deterministically
Otherwise: Flag is globally enabled

The hash function ensures consistent assignment, so that the same user always gets the same result:

function simpleHash(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    const char = str.charCodeAt(i);
    hash = (hash << 5) - hash + char;
    hash = hash & hash;
  }
  return Math.abs(hash);
}

This creates a deterministic hash, so simpleHash("user-123") always returns the same number, ensuring consistent feature flag decisions.

Server-Side Feature Flag Logic

The server-side version is similar but uses the server Supabase client:

// lib/feature-flags/server.ts
import { createClient } from '@/lib/supabase/server';
import { cookies } from 'next/headers';
import { FeatureFlag, FeatureFlagCheckResult } from '@/types/feature-flag';

export async function getFeatureFlag(key: string): Promise<FeatureFlag | null> {
  const cookieStore = await cookies();
  const supabase = createClient(cookieStore);

  const { data, error } = await supabase
    .from('feature_flags')
    .select('*')
    .eq('key', key)
    .single();

  if (error) {
    if (error.code === 'PGRST116') return null;
    console.error('Error fetching feature flag:', error);
    return null;
  }

  return data;
}

export async function isFeatureEnabled(
  key: string,
  userId?: string
): Promise<FeatureFlagCheckResult> {
  const flag = await getFeatureFlag(key);

  if (!flag) {
    return { enabled: false, reason: 'Flag not found' };
  }

  if (!flag.enabled) {
    return { enabled: false, reason: 'Flag is globally disabled' };
  }

  // Check user-specific access
  if (userId && flag.enabled_for_users.length > 0) {
    if (flag.enabled_for_users.includes(userId)) {
      return { enabled: true, reason: 'User has explicit access' };
    }
    return { enabled: false, reason: 'User not in allowed list' };
  }

  // Check percentage rollout
  if (flag.enabled_for_percent > 0) {
    const hash = simpleHash(userId || key);
    const percentage = hash % 100;
    const enabled = percentage < flag.enabled_for_percent;

    return {
      enabled,
      reason: enabled
        ? `User falls within ${flag.enabled_for_percent}% rollout`
        : `User falls outside ${flag.enabled_for_percent}% rollout`,
    };
  }

  return { enabled: true, reason: 'Flag is globally enabled' };
}

function simpleHash(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    const char = str.charCodeAt(i);
    hash = (hash << 5) - hash + char;
    hash = hash & hash;
  }
  return Math.abs(hash);
}

The logic is identical to the client version, but it uses the server Supabase client that handles cookies correctly.

Setting Up React Query

We’ll rely heavily on React Query throughout this tutorial because feature flags are server-driven values that can change at runtime while users are actively using the application.

React Query provides robust server-state management through caching, background refetching, and cache invalidation. This allows feature flag changes to propagate automatically across the app without forcing page refreshes or manual state synchronization.

Create the Query Provider

First, create the providers/QueryProvider.tsx file to configure and initialize React Query for the entire application:

'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useState } from 'react';

export function QueryProvider({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            // With SSR, we usually want to set some default staleTime
            // above 0 to avoid refetching immediately on the client
            staleTime: 20 * 1000,
            refetchOnWindowFocus: true,
            refetchOnReconnect: true,
          },
        },
      })
  );

  return (
    {children}
  );
}

What’s happening in this code:

This file runs on the client because React Query relies on React hooks, which only execute in the browser.
A single QueryClient instance is created and stored in state so it persists across renders and isn’t recreated.
The QueryClient defines how server data is cached, when it becomes stale, and when it should be refetched.

This is important because components no longer need to handle fetch logic, loading states, or caching manually. Also, server data is shared and reused across components instead of being refetched repeatedly. And feature flag updates propagate automatically, keeping the app consistent without manual refreshes.

Add Provider to Root Layout

Next, update the app/layout.tsx file to wrap the application with the React Query provider.

import type { Metadata } from 'next'
import './globals.css'
import { QueryProvider } from '@/providers/QueryProvider'

export const metadata: Metadata = {
  title: 'Feature Flag System',
  description: 'Production-ready feature flag system with Next.js and Supabase',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    "en">
      
        {children}
      
    
  )
}

We wrap the entire application with QueryProvider, so React Query can manage server data globally across the app.

What `QueryProvider` actually does

QueryProvider creates and shares a single Query Client that is responsible for:

Caching data fetched from the server
Tracking loading and error states
Automatically refetching data when needed
Synchronizing data between components

By wrapping the app, every component inside it can use React Query hooks without any extra setup.

Creating the React Hook

Create the hooks/useFeatureFlag.ts file to check whether a feature flag is enabled for a user, using React Query to cache and share the data across components:

'use client';

import { useQuery } from '@tanstack/react-query';
import { isFeatureEnabled } from '@/lib/feature-flags/client';
import { FeatureFlagCheckResult } from '@/types/feature-flag';

export function useFeatureFlag(key: string, userId?: string) {
  const {
    data: result = { enabled: false, reason: 'Loading...' },
    isLoading: loading,
    error,
  } = useQuery({
    queryKey: ['featureFlag', key, userId],
    queryFn: () => isFeatureEnabled(key, userId),
    staleTime: 30 * 1000,
    refetchOnWindowFocus: true,
  });

  return { ...result, loading, error };
}

What’s happening in the code:

'use client'; ensures this file runs in the browser because React Query hooks can only run on the client.
useQuery fetches the feature flag status from the server and caches the result.
queryKey: ['featureFlag', key, userId] uniquely identifies this query so React Query can cache it separately for each feature and user.
queryFn: () => isFeatureEnabled(key, userId) is the function that actually checks if the feature is enabled.
staleTime: 30 * 1000 keeps the cached data fresh for 30 seconds before refetching.
refetchOnWindowFocus: true automatically refetches the data when the user switches back to the tab.
return { ...result, loading, error } makes it easy for components to access the flag status, loading state, and any errors.

Admin Hooks for Managing Flags

We’re going to create a set of React Query hooks to manage feature flags from the admin dashboard. These hooks allow you to fetch, create, update, and delete feature flags while automatically keeping your UI in sync.

Step 1: Create the hooks file

Start by creating a new file at hooks/useFeatureFlags.ts file. This is where we’ll implement all the hooks for the admin to manage feature flags.

After creating the hooks/useFeatureFlags.ts file, import React Query hooks and the FeatureFlag type so we can fetch, update, create, and delete feature flags with type safety and caching.

'use client';

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { FeatureFlag } from '@/types/feature-flag';

In this code:

useQuery fetches and caches server data automatically.
useMutation sends updates, creates, or deletes data on the server.
useQueryClient gives access to the query cache so we can invalidate or update queries after mutations.
FeatureFlag is the TypeScript type definition for feature flags, ensuring our hooks use correct data structures.

Step 2: Add a hook to fetch all feature flags

Next, in the same hooks/useFeatureFlags.ts file, add a hook to fetch all feature flags for the admin page. This hook will allow components to retrieve the list of flags and automatically cache the data using React Query.

export function useFeatureFlags() {
  return useQuery({
    queryKey: ['featureFlags'],
    queryFn: async () => {
      const response = await fetch('/api/feature-flags');
      const { data } = await response.json();
      return data || [];
    },
    staleTime: 30 * 1000,
  });
}

What’s happening in the code:

useQuery fetches all feature flags from the server and caches them automatically.
queryKey: ['featureFlags'] uniquely identifies this query so React Query can manage caching and refetching.
queryFn is an async function that calls the /api/feature-flags endpoint and returns the data.
staleTime: 30 * 1000 keeps the cached data fresh for 30 seconds before refetching.

This matters because admin components always display the latest flags without manual refresh. Also, cached data reduces unnecessary network requests. Finally, any component using this hook will automatically update when the flags change.

Step 3: Add a hook to update a feature flag

Next, in the same hooks/useFeatureFlags.ts file, add a hook to update an existing feature flag. This hook will allow the admin to modify a flag and ensure all components using it get the updated value automatically.

export function useUpdateFeatureFlag() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async ({
      key,
      updates,
    }: {
      key: string;
      updates: Partial;
    }) => {
      const response = await fetch(`/api/feature-flags/${key}`, {
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updates),
      });

      if (!response.ok) {
        throw new Error('Failed to update feature flag');
      }

      const { data } = await response.json();
      return data;
    },
    onSuccess: (data, variables) => {
      // Invalidate and refetch feature flags list
      queryClient.invalidateQueries({ queryKey: ['featureFlags'] });
      // Invalidate the specific feature flag check
      queryClient.invalidateQueries({
        queryKey: ['featureFlag', variables.key],
      });
      // Invalidate all feature flag checks (in case userId was involved)
      queryClient.invalidateQueries({ queryKey: ['featureFlag'] });
    },
  });
}

What’s happening in the code:

useMutation creates a function to update a feature flag on the server.
mutationFn is an async function that sends a PATCH request to /api/feature-flags/${key} with the updated data.
onSuccess runs after a successful update to invalidate cached queries so the latest data is available everywhere:
- ['featureFlags'] updates the full list of flags.
- ['featureFlag', variables.key] updates the specific flag that was changed.
- ['featureFlag'] updates any other cached flag checks (for example, per user checks).

Step 4: Add a hook to delete a feature flag

Next, add the useDeleteFeatureFlag hook to delete a feature flag. This hook allows the admin to remove a flag from the system and ensures the UI updates automatically everywhere the flag was used.

export function useDeleteFeatureFlag() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (key: string) => {
      const response = await fetch(`/api/feature-flags/${key}`, {
        method: 'DELETE',
      });

      if (!response.ok) {
        throw new Error('Failed to delete feature flag');
      }
    },
    onSuccess: (_, key) => {
      // Invalidate and refetch feature flags list
      queryClient.invalidateQueries({ queryKey: ['featureFlags'] });
      // Invalidate the specific feature flag check
      queryClient.invalidateQueries({ queryKey: ['featureFlag', key] });
    },
  });
}

What’s happening in the code:

useMutation creates a function to delete a feature flag from the server.
mutationFn is an async function that sends a DELETE request to /api/feature-flags/${key}.
onSuccess runs after the flag is successfully deleted to invalidate the cache so the UI updates:
- ['featureFlags'] refetches the full list of flags.
- ['featureFlag', key] removes the deleted flag from any cached queries.

Step 5: Add a hook to create a new feature flag

Finally, add the useCreateFeatureFlag hook to create a new feature flag. This allows the admin to add new flags and ensures the dashboard updates automatically when a new flag is created.

export function useCreateFeatureFlag() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (flag: {
      key: string;
      name: string;
      description?: string;
      enabled?: boolean;
      enabled_for_users?: string[];
      enabled_for_percent?: number;
      metadata?: Record<string, any>;
    }) => {
      const response = await fetch('/api/feature-flags', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(flag),
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.error || 'Failed to create feature flag');
      }

      const { data } = await response.json();
      return data;
    },
    onSuccess: () => {
      // Invalidate and refetch feature flags list
      queryClient.invalidateQueries({ queryKey: ['featureFlags'] });
    },
  });
}

What’s happening in the code:

useMutation creates a function to send a new feature flag to the server.
mutationFn is an async function that posts the flag data to /api/feature-flags.
onSuccess runs after a successful creation to invalidate the cached list of flags, so the admin dashboard shows the new flag immediately.

Feature Flag Gate Component

Now we’ll create a wrapper component to conditionally render UI based on feature flags. This helps you show or hide parts of your app depending on whether a flag is enabled for a user.

Create the components/FeatureFlagGate.tsx file and add the following code:

'use client';

import { ReactNode } from 'react';
import { useFeatureFlag } from '@/hooks/useFeatureFlag';

interface FeatureFlagGateProps {
  flagKey: string;
  userId?: string;
  children: ReactNode;
  fallback?: ReactNode;
  showLoading?: ReactNode;
}

export function FeatureFlagGate({
  flagKey,
  userId,
  children,
  fallback = null,
  showLoading = null,
}: FeatureFlagGateProps) {
  const { enabled, loading } = useFeatureFlag(flagKey, userId);

  if (loading && showLoading !== null) {
    return <>{showLoading};
  }

  if (!enabled) {
    return <>{fallback};
  }

  return <>{children};
}

What’s happening in the code:

useFeatureFlag(flagKey, userId) checks whether the feature is enabled for a specific user and tracks loading state.
loading && showLoading !== null: if the data is still loading, render the optional showLoading UI.
!enabled: if the feature is disabled, render the optional fallback UI.
children renders the actual content only if the flag is enabled and not loading.

This makes it easy to conditionally render features without scattering logic throughout your components. It also supports custom loading and fallback UI for better user experience. And it works with React Query caching automatically, so flag changes propagate immediately.

Building the Admin Dashboard

Admins need a way to manage feature flags in your app. To do this, we’ll create API routes that support CRUD operations (Create, Read, Update, Delete). These routes will interact with Supabase to store and modify flag data.

Step 1: Create the main feature flags API route

Start by creating the app/api/feature-flags/route.ts file. This file will handle fetching all feature flags (GET) and creating new ones (POST).

import { NextRequest, NextResponse } from 'next/server';
import { createClient } from '@/lib/supabase/server';
import { cookies } from 'next/headers';

export async function GET(request: NextRequest) {
  try {
    const cookieStore = await cookies();
    const supabase = createClient(cookieStore);
    const { data, error } = await supabase
      .from('feature_flags')
      .select('*')
      .order('created_at', { ascending: false });

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ data });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

export async function POST(request: NextRequest) {
  try {
    const cookieStore = await cookies();
    const supabase = createClient(cookieStore);
    const body = await request.json();

    if (!body.key || !body.name) {
      return NextResponse.json(
        { error: 'key and name are required' },
        { status: 400 }
      );
    }

    const { data, error } = await supabase
      .from('feature_flags')
      .insert({
        key: body.key,
        name: body.name,
        description: body.description || null,
        enabled: body.enabled || false,
        enabled_for_users: body.enabled_for_users || [],
        enabled_for_percent: body.enabled_for_percent || 0,
        metadata: body.metadata || {},
      })
      .select()
      .single();

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ data }, { status: 201 });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

What’s happening in this file:

GET fetches all feature flags from Supabase, ordered by creation date.
POST creates a new feature flag in Supabase. It checks that key and name exist, and sets defaults for optional fields.
createClient(cookieStore) authenticates requests with Supabase using cookies from the client.
NextResponse.json() sends JSON responses with data or error messages.

Step 2: Create the dynamic route for individual flags

Next, Create the file app/api/feature-flags/[key]/route.ts. This route handles updating (PATCH) and deleting (DELETE) individual flags based on their key.

import { NextRequest, NextResponse } from 'next/server';
import { createClient } from '@/lib/supabase/server';
import { cookies } from 'next/headers';

export async function PATCH(
  request: NextRequest,
  { params }: { params: { key: string } }
) {
  try {
    const cookieStore = await cookies();
    const supabase = createClient(cookieStore);
    const body = await request.json();

    const { data, error } = await supabase
      .from('feature_flags')
      .update({
        ...(body.name !== undefined && { name: body.name }),
        ...(body.description !== undefined && { description: body.description }),
        ...(body.enabled !== undefined && { enabled: body.enabled }),
        ...(body.enabled_for_users !== undefined && {
          enabled_for_users: body.enabled_for_users,
        }),
        ...(body.enabled_for_percent !== undefined && {
          enabled_for_percent: body.enabled_for_percent,
        }),
      })
      .eq('key', params.key)
      .select()
      .single();

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ data });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

export async function DELETE(
  request: NextRequest,
  { params }: { params: { key: string } }
) {
  try {
    const cookieStore = await cookies();
    const supabase = createClient(cookieStore);

    const { error } = await supabase
      .from('feature_flags')
      .delete()
      .eq('key', params.key);

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ success: true });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

What’s happening in this file:

PATCH updates a feature flag with only the fields provided in the request body.
- Uses the spread operator (...) to include only fields that exist.
DELETE removes the feature flag identified by key.
eq('key', params.key) ensures the operation targets the correct flag.

Step 3: Create the Admin Dashboard UI

Now, create the file app/admin/page.tsx. This is the main admin dashboard where you can view, create, and manage feature flags.

With React Query, the admin dashboard becomes much cleaner and automatically updates when flags change:

'use client';

import { useState } from 'react';
import { FeatureFlagList } from '@/components/admin/FeatureFlagList';
import { CreateFeatureFlagModal } from '@/components/admin/CreateFeatureFlagModal';
import { useFeatureFlags } from '@/hooks/useFeatureFlags';

export default function AdminPage() {
  const [showCreateModal, setShowCreateModal] = useState(false);
  const { data: flags = [], isLoading: loading } = useFeatureFlags();

  return (
    'min-h-screen bg-gray-50 py-8'>
      'max-w-7xl mx-auto px-4 sm:px-6 lg:px-8'>
        'mb-8 flex justify-between items-center'>
          
            'text-3xl font-bold text-gray-900'>
              Feature Flags Admin
            
            'mt-2 text-sm text-gray-600'>
              Manage your feature flags and rollouts
            
          
          
        

        {loading ? (
          'text-center py-12'>
            'inline-block animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600'>
            'mt-4 text-gray-600'>Loading feature flags...
          
        ) : (
          
        )}

        {showCreateModal && (
          () => setShowCreateModal(false)}
            onSuccess={() => {
              setShowCreateModal(false);
            }}
          />
        )}
      
    
  );
}

What’s happening in this file:

'use client'; marks this page as a client component so hooks like useState and React Query can run.
useState manages whether the “Create Feature Flag” modal is open or closed.
useFeatureFlags() fetches all feature flags from the API and keeps the list in sync automatically.
const { data: flags = [], isLoading: loading } :
- flags contains the feature flag list
- loading tracks whether the data is still being fetched
loading ? ... : :
- Shows a loading spinner while flags are being fetched
- Renders the feature flag table once data is available
FeatureFlagList displays all feature flags and their current states.

Using Feature Flags Mutations in Components

Earlier, we created mutation hooks for creating, updating, and deleting feature flags. Now let’s see how those hooks are actually used inside UI components to trigger updates and keep the interface in sync.

Here's how to use the mutation hooks in your components:

'use client'

import { useState } from 'react'
import { FeatureFlag } from '@/types/feature-flag'
import { EditFeatureFlagModal } from './EditFeatureFlagModal'
import {
  useUpdateFeatureFlag,
  useDeleteFeatureFlag,
} from '@/hooks/useFeatureFlags'

interface FeatureFlagCardProps {
  flag: FeatureFlag
}

export function FeatureFlagCard({ flag }: FeatureFlagCardProps) {
  const [isEditing, setIsEditing] = useState(false)
  const updateFlag = useUpdateFeatureFlag()
  const deleteFlag = useDeleteFeatureFlag()

  const handleToggle = async () => {
    try {
      await updateFlag.mutateAsync({
        key: flag.key,
        updates: { enabled: !flag.enabled },
      })
    } catch (error) {
      console.error('Error toggling flag:', error)
      alert('Failed to toggle feature flag')
    }
  }

  const handleDelete = async () => {
    if (!confirm(`Are you sure you want to delete "${flag.name}"?`)) {
      return
    }

    try {
      await deleteFlag.mutateAsync(flag.key)
    } catch (error) {
      console.error('Error deleting flag:', error)
      alert('Failed to delete feature flag')
    }
  }

  return (
    <>
      "bg-white rounded-lg shadow p-6">
        "flex items-start justify-between">
          "flex-1">
            "flex items-center gap-3">
              "text-lg font-semibold text-gray-900">
                {flag.name}
              
              `px-2 py-1 text-xs font-medium rounded-full ${
                  flag.enabled
                    ? 'bg-green-100 text-green-800'
                    : 'bg-gray-100 text-gray-800'
                }`}
              >
                {flag.enabled ? 'Enabled' : 'Disabled'}
              
            
            "mt-1 text-sm text-gray-600 font-mono">{flag.key}
            {flag.description && (
              "mt-2 text-sm text-gray-500">{flag.description}
            )}

            "mt-4 flex flex-wrap gap-4 text-sm text-gray-600">
              {flag.enabled_for_users.length > 0 && (
                
                  "font-medium">Users:{' '}
                  {flag.enabled_for_users.length} user(s)
                
              )}
              {flag.enabled_for_percent > 0 && (
                
                  "font-medium">Rollout:{' '}
                  {flag.enabled_for_percent}%
                
              )}
            
          

          "flex items-center gap-2 ml-4">
            
            
            
          
        
      

      {isEditing && (
        () => setIsEditing(false)}
          onSuccess={() => {
            setIsEditing(false)
          }}
        />
      )}
    
  )
}

The component above works without any manual refetching or state synchronization logic. The moment a mutation succeeds, React Query automatically updates or invalidates the relevant cached data. That behavior is what enables the smooth, real-time updates you see in the UI.

Because all feature flag data is managed by React Query:

When a flag is toggled, React Query automatically invalidates the relevant queries
Any component using that flag immediately receives the updated value
The admin dashboard stays in sync with the rest of the application without extra code
Loading and error states are handled consistently across all mutations.

Implementing a Real-World Example

To make all of this concrete, let’s walk through a real-world example.

In this section, we’ll build a simple Todo feature that is entirely controlled by a feature flag. When the flag is disabled, users see a message explaining that the feature isn’t available. When it’s enabled, the full Todo interface appears instantly without redeploying or refreshing the page.

This demonstrates how feature flags can safely gate entire pages or features in a live application.

Below is what the experience looks like as the feature flag is toggled on and off from the admin dashboard:

Step 1: Create the Todo Page File

Create a new file app/todos/page.tsx. This page shows how to use a feature flag to conditionally render a full component. Let's build a todo app that's controlled by a feature flag. This demonstrates real-world usage.

At the top of the file, import the hooks we need and define the Todo interface.

'use client';

import { useState, useEffect } from 'react';
import { FeatureFlagGate } from '@/components/FeatureFlagGate';

interface Todo {
  id: string;
  text: string;
  completed: boolean;
}

Step 2: Initialize state in the component

Create the component and define state for todos and the input:

export default function TodosPage() {
  const [todos, setTodos] = useState([]);
  const [inputValue, setInputValue] = useState('');

Here’s what’s going on:

todos stores all todo items.
inputValue tracks what the user types in the input field.

Step 3: Load and save todos from localStorage

  useEffect(() => {
    const saved = localStorage.getItem('todos');
    if (saved) setTodos(JSON.parse(saved));
  }, []);

  useEffect(() => {
    localStorage.setItem('todos', JSON.stringify(todos));
  }, [todos]);

In this code, the first useEffect loads saved todos from the browser’s localStorage when the component mounts. The second useEffect saves todos whenever the list changes. This ensures your todos persist across page reloads.

Step 4: Add helper functions

  const addTodo = () => {
    if (inputValue.trim()) {
      setTodos([...todos, { 
        id: Date.now().toString(), 
        text: inputValue.trim(), 
        completed: false 
      }]);
      setInputValue('');
    }
  };

  const toggleTodo = (id: string) => {
    setTodos(todos.map(todo => 
      todo.id === id ? { ...todo, completed: !todo.completed } : todo
    ));
  };

  const deleteTodo = (id: string) => {
    setTodos(todos.filter(todo => todo.id !== id));
  };

In this code,

addTodo adds a new todo item with a unique id and resets the input.
toggleTodo marks a todo as completed or incomplete.
deleteTodo removes a todo from the list.

Step 5: Render the Todo App inside the FeatureFlagGate

  return (
    <div className="max-w-2xl mx-auto p-8">
      <h1 className="text-4xl font-bold mb-6">Todo Apph1>

      <FeatureFlagGate
        flagKey="test"
        fallback={
          <div className="bg-yellow-50 border-2 border-yellow-200 rounded-lg p-6">
            <h3 className="font-semibold mb-2">Feature Not Availableh3>
            <p>Enable the "test" feature flag in the admin dashboard.p>
          div>
        }
      >

What’s going on here:

We wrap the Todo app in FeatureFlagGate.
flagKey="test" only shows the Todo app if this feature flag is enabled.
fallback displays a message when the feature is disabled.

Step 6: Add the input field and Add button

        <div className="mb-6">
          <div className="flex gap-2">
            <input
              type="text"
              value={inputValue}
              onChange={(e) => setInputValue(e.target.value)}
              onKeyPress={(e) => e.key === 'Enter' && addTodo()}
              placeholder="What needs to be done?"
              className="flex-1 px-4 py-3 border rounded-lg"
            />
            <button
              onClick={addTodo}
              className="px-6 py-3 bg-purple-600 text-white rounded-lg"
            >
              Add
            button>
          div>
        div>

In this code,

Input field captures new todo text.
Pressing Enter or clicking Add triggers addTodo.
It’s styled with Tailwind CSS for spacing and rounded borders.

Step 8: Display the list of todos


        <div className="space-y-2">
          {todos.map((todo) => (
            <div
              key={todo.id}
              className="flex items-center gap-3 p-4 bg-gray-50 rounded-lg"
            >
              <button
                onClick={() => toggleTodo(todo.id)}
                className={`w-6 h-6 rounded-full border-2 ${
                  todo.completed
                    ? 'bg-green-500 border-green-500'
                    : 'border-gray-300'
                }`}
              >
                {todo.completed && '✓'}
              button>
              <span className={todo.completed ? 'line-through' : ''}>
                {todo.text}
              span>
              <button
                onClick={() => deleteTodo(todo.id)}
                className="text-red-500"
              >
                Delete
              button>
            div>
          ))}
        div>
      FeatureFlagGate>
    div>
  );
}

This code,

Loops over todos to display each item.
Shows a toggle button to mark as complete, a delete button, and the todo text.
Completed todos get a line-through style.
All interaction happens inside the FeatureFlagGate, so users only see this when the flag is enabled.
The entire todo app is wrapped in FeatureFlagGate. When the "test" flag is disabled, users see a message instead of the app. When enabled, they see the full todo interface.

Todo App Overview

This Todo app demonstrates how feature flags work in a live application. It shows how admins can enable or disable the "test" feature flag dynamically from the dashboard.

FeatureFlagGate ensures the interface updates immediately when the flag changes, and entire components or pages can be toggled on or off safely using feature flags.

Server-Side Usage

Feature flags shouldn’t only live on the client. In many cases, you’ll want to enforce them on the server as well, especially for APIs, background jobs, or sensitive business logic.

In this example, we’ll protect an API route by checking a feature flag on the server before returning any data.

First, create the API route file app/api/some-feature/route.ts. This demonstrates how to check a feature flag on the server before returning data.

import { isFeatureEnabled } from '@/lib/feature-flags/server';
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const userId = request.headers.get('user-id') || undefined;
  const result = await isFeatureEnabled('new-feature', userId);

  if (!result.enabled) {
    return NextResponse.json(
      { error: 'Feature not available' },
      { status: 403 }
    );
  }

  // Feature is enabled, proceed with logic
  return NextResponse.json({ data: 'Feature content' });
}

What’s happening in this file:

File creation: app/api/some-feature/route.ts defines a new API route.
isFeatureEnabled: Checks whether the 'new-feature' flag is active for the user.
Conditional response: Returns a 403 error if the feature is disabled. Otherwise, proceeds normally.
Server-side gating: Lets you protect entire endpoints, so users only access functionality when the feature is enabled.

Why React Query?

Feature flags introduce a unique challenge because they must remain consistent across the entire UI even as they change dynamically. Without a dedicated server-state solution, you’d need to manually refetch data, coordinate updates between components, and handle edge cases where parts of the UI fall out of sync.

React Query treats feature flags as shared server state. Once fetched, flags are cached and reused across components. When an admin updates a flag, the cache is invalidated and refetched in the background, triggering immediate UI updates everywhere the flag is used. This makes React Query a natural fit for feature flags, where correctness, consistency, and real-time updates are critical.

Real-World Impact

Before React Query:

// Had to manually refetch after every update
const handleToggle = async () => {
  await fetch(`/api/feature-flags/${key}`, { method: 'PATCH', ... });
  fetchFlags(); // Manual refetch
  // Other components still show old data until page refresh
};

After React Query:

// Automatic cache invalidation - everything updates instantly
const updateFlag = useUpdateFeatureFlag();
await updateFlag.mutateAsync({ key, updates });
// All components using this flag automatically update!

Conclusion

You’ve now built a complete, production-ready feature flag system using Next.js and Supabase. The system supports global toggles, user-specific access, and percentage-based rollouts, all backed by a flexible database schema.

Feature flags can be checked on both the client and the server, ensuring consistent behavior across UI components and API routes. With React Query handling caching and invalidation, changes made in the admin dashboard propagate instantly throughout the application without deploying or refreshing the page.

Feature flags are a foundational tool for modern development. They let you deploy code safely, test new ideas with real users, and react quickly when something goes wrong. With this setup in place, you can confidently extend the system with audit logs, analytics, scheduled rollouts, or deeper CI/CD integrations as your product grows.

How to Build a Payroll System with Express and Monnify Using Background Jobs

David Aniebo — Wed, 14 Jan 2026 21:41:50 +0000

Processing payroll payments is an important operation for any business. When you need to pay employees simultaneously, you can't afford to have your server hang, get blocking errors, or timeout while waiting for each payment to complete.

Building a payroll system is an excellent way to practice real-world backend development skills. Unlike simple CRUD applications, payroll systems require you to think about:

Asynchronous processing: When you need to pay hundreds of employees, processing payments synchronously can cause your server to timeout. Background jobs with Bull and Redis allow you to handle long-running operations without blocking your API.
Payment gateway integration: Working with payment APIs like Monnify teaches you how to handle external service integrations, authentication flows, webhook verification, and error handling in production systems.
Data consistency: Payroll systems need to maintain accurate records. You'll learn about transaction reconciliation, idempotency, and how to handle partial failures gracefully.
Production-ready patterns: This tutorial covers patterns you'll use in real applications: job queues, webhook handlers, database migrations, and proper error handling.

Whether you're building a fintech application, an HR system, or just want to understand how payment processing works, the concepts in this tutorial will serve you well. The combination of Express, TypeScript, background jobs, and payment APIs represents a common stack in modern backend development.

In this tutorial, you’ll learn how to build a production-grade payroll engine using Express.js, TypeScript, and Monnify's payment API. You'll implement background job processing with Bull and Redis to handle bulk disbursements efficiently.

By the end, you will have a fully functional payroll system that can:

Manage employee records with bank account details
Create and process payroll batches
Process bulk payments using Monnify's disbursement API
Handle payment status updates via webhooks
Reconcile transactions to ensure data consistency

Prerequisites
Project Architecture Overview
Setting Up the Project
Configuring Docker for PostgreSQL and Redis
Setting Up the Database
Creating Database Models
PayrollItemModel
Building the Monnify Client
Implementing Background Job Processing
Creating the API Controllers
Setting Up Webhook Handlers
Wiring Up Routes
Testing the System
Setting Up Webhooks for Production
Conclusion
- Key Takeaways
- References:

Prerequisites

Before you begin, make sure you have the following:

Node.js (v18 or higher)
Docker and Docker Compose installed
A Monnify merchant account with API credentials
Basic knowledge of TypeScript and Express.js
Familiarity with REST APIs

You'll also need to obtain these credentials from your Monnify dashboard:

API Key
Secret Key
Contract Code
Webhook Secret (for verifying webhook signatures)

Project Architecture Overview

Here's how the payroll system works:

Key components:

Express API: A minimal and flexible Node.js web framework that handles HTTP requests for managing employees and payrolls. Express provides routing, middleware support, and makes it easy to build RESTful APIs.
Bull Queue: A Redis-based queue library for Node.js that processes payroll jobs asynchronously in the background. Bull handles job retries, scheduling, and provides a reliable way to process long-running tasks without blocking your main application thread.
Redis: An in-memory data structure store that serves as the backend for Bull queues. Redis stores job data, manages job states (pending, active, completed, failed), and enables distributed job processing across multiple workers.
PostgreSQL: A relational database that persists employee records, payrolls, and payment items. PostgreSQL's ACID compliance ensures data integrity, and its support for complex queries makes it ideal for financial applications.
Monnify API: A payment gateway service that handles actual money transfers to employee bank accounts. Monnify provides bulk disbursement capabilities, allowing you to process multiple payments in a single API call, which is essential for payroll systems.
Webhooks: HTTP callbacks that receive real-time payment status updates from Monnify. When a payment completes or fails, Monnify sends a webhook to your server, allowing you to update your database immediately without polling.

Setting Up the Project

In this section, we'll initialize a new Node.js project with TypeScript and install all the necessary dependencies. We'll configure TypeScript for type safety and set up the project structure that will support our payroll system.

First, create a new directory and initialize your project:

mkdir monnify-payroll-system
cd monnify-payroll-system
npm init -y

Next, install the required dependencies:

npm install express cors helmet dotenv axios bull ioredis pg swagger-jsdoc swagger-ui-express express-validator

Then install the development dependencies:

npm install -D typescript ts-node-dev @types/node @types/express @types/cors @types/pg @types/bull

Create a tsconfig.json file:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*", "scripts/**/*"],
  "exclude": ["node_modules", "dist"]
}

And update your package.json scripts:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "ts-node-dev --respawn --transpile-only src/index.ts",
    "migrate": "ts-node scripts/run-migrations.ts"
  }
}

Now, create a .env file for your environment variables. All the Monnify env details can be gotten in this route:

# Server
PORT=3008
NODE_ENV=development

# Database
DB_HOST=localhost
DB_PORT=5433
DB_NAME=payroll_db
DB_USER=payroll_user
DB_PASSWORD=payroll_password

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# Monnify
MONNIFY_API_KEY=your_api_key
MONNIFY_SECRET_KEY=your_secret_key
MONNIFY_BASE_URL=https://sandbox.monnify.com
MONNIFY_CONTRACT_CODE=your_contract_code
MONNIFY_WEBHOOK_SECRET=your_webhook_secret

Configuring Docker for PostgreSQL and Redis

Before we can start building our application, we need to set up the infrastructure services: PostgreSQL for data persistence and Redis for job queue management. Using Docker Compose makes it easy to run these services locally with a single command. This approach ensures consistency across development environments and simplifies deployment.

Create a docker-compose.yml file to set up PostgreSQL and Redis:

services:
  postgres:
    image: postgres:15-alpine
    container_name: monnify-payroll-db
    environment:
      POSTGRES_USER: payroll_user
      POSTGRES_PASSWORD: payroll_password
      POSTGRES_DB: payroll_db
    ports:
      - '5433:5432'
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U payroll_user']
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: monnify-payroll-redis
    ports:
      - '6379:6379'
    volumes:
      - redis_data:/data
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:
  redis_data:

Start the services:

docker-compose up -d

And verify that both services are running:

docker-compose ps

Setting Up the Database

Now we'll configure the database connection and create the necessary tables. We'll use a connection pool for efficient database access and create migration files to set up our schema. This approach ensures our database structure is version-controlled and can be easily reproduced.

Create the src/config/database.ts file to configure the PostgreSQL connection:

import { Pool, PoolConfig } from 'pg';
import dotenv from 'dotenv';

dotenv.config();

const dbName = (process.env.DB_NAME || 'payroll_db').trim();
if (!dbName) {
  throw new Error('Database name (DB_NAME) must be set and cannot be empty');
}

const config: PoolConfig = {
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT || '5433'),
  database: dbName,
  user: process.env.DB_USER || 'payroll_user',
  password: process.env.DB_PASSWORD || 'payroll_password',
  max: 20,
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000,
};

export const pool = new Pool(config);

pool.on('error', (err: Error) => {
  console.error('Unexpected error on idle client', err);
  process.exit(-1);
});

export const query = async (text: string, params?: any[]) => {
  const start = Date.now();
  try {
    const res = await pool.query(text, params);
    return res;
  } catch (error) {
    console.error('Database query error', error);
    throw error;
  }
};

Now create the migration files. First, create a migrations folder:

mkdir migrations

Then create migrations/001_create_employees_table.sql:

-- Create employees table
CREATE TABLE IF NOT EXISTS employees (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL UNIQUE,
  employee_id VARCHAR(100) NOT NULL UNIQUE,
  salary DECIMAL(15, 2) NOT NULL,
  account_number VARCHAR(50) NOT NULL,
  bank_code VARCHAR(20) NOT NULL,
  bank_name VARCHAR(255),
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Create indexes for faster lookups
CREATE INDEX IF NOT EXISTS idx_employees_employee_id ON employees(employee_id);
CREATE INDEX IF NOT EXISTS idx_employees_is_active ON employees(is_active);

Now, create migrations/002_create_payrolls_table.sql:

-- Create payrolls table
CREATE TABLE IF NOT EXISTS payrolls (
  id SERIAL PRIMARY KEY,
  payroll_period VARCHAR(100) NOT NULL,
  total_amount DECIMAL(15, 2) NOT NULL,
  total_employees INTEGER NOT NULL,
  status VARCHAR(50) NOT NULL DEFAULT 'pending',
  processed_count INTEGER DEFAULT 0,
  failed_count INTEGER DEFAULT 0,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  processed_at TIMESTAMP
);

-- Create indexes for faster queries
CREATE INDEX IF NOT EXISTS idx_payrolls_status ON payrolls(status);
CREATE INDEX IF NOT EXISTS idx_payrolls_period ON payrolls(payroll_period);

And next, create migrations/003_create_payroll_items_table.sql:

-- Create payroll_items table
CREATE TABLE IF NOT EXISTS payroll_items (
  id SERIAL PRIMARY KEY,
  payroll_id INTEGER NOT NULL REFERENCES payrolls(id) ON DELETE CASCADE,
  employee_id INTEGER NOT NULL REFERENCES employees(id) ON DELETE CASCADE,
  amount DECIMAL(15, 2) NOT NULL,
  status VARCHAR(50) NOT NULL DEFAULT 'pending',
  transaction_reference VARCHAR(255),
  error_message TEXT,
  processed_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Create indexes for faster queries
CREATE INDEX IF NOT EXISTS idx_payroll_items_payroll_id ON payroll_items(payroll_id);
CREATE INDEX IF NOT EXISTS idx_payroll_items_employee_id ON payroll_items(employee_id);
CREATE INDEX IF NOT EXISTS idx_payroll_items_status ON payroll_items(status);
CREATE INDEX IF NOT EXISTS idx_payroll_items_transaction_ref ON payroll_items(transaction_reference);

Then create a migration runner script at scripts/run-migrations.ts:

import fs from 'fs';
import path from 'path';
import { pool } from '../src/config/database';

async function runMigrations() {
  const migrationsDir = path.join(__dirname, '../migrations');
  const files = fs.readdirSync(migrationsDir).sort();

  for (const file of files) {
    if (file.endsWith('.sql')) {
      console.log(`Running migration: ${file}`);
      const sql = fs.readFileSync(path.join(migrationsDir, file), 'utf-8');
      await pool.query(sql);
      console.log(`Completed: ${file}`);
    }
  }

  console.log('All migrations completed');
  await pool.end();
}

runMigrations().catch((err) => {
  console.error('Migration failed:', err);
  process.exit(1);
});

Run the migrations:

npm run migrate

Creating Database Models

In this section, we'll create the data access layer for our payroll system. Models encapsulate all database operations, providing a clean interface for the rest of the application. We'll build two main models: one for managing employees and another for handling payrolls and payroll items.

For each model, I’ll first explain its purpose and key methods, then show you the complete code implementation. This approach helps you understand what each model does before you implement it.

Employee Model

The EmployeeModel serves as the data-access layer for employee records. It handles creating, reading, updating, and soft-deleting employees. The model includes automatic employee ID generation (format: EMP001, EMP002, and so on) and ensures that each employee has the banking details required for payroll disbursement.

Start by creating a new file at src/models/employee.ts where we’ll implement all employee-related database logic.

After creating the file, import a shared database query helper to execute parameterized SQL safely.

import { query } from '../config/database';

This keeps raw SQL isolated from controllers and ensures protection against SQL injection.

Employee Data Structure (`Employee` Interface)

Next, we’ll define the employee interface.

The Employee interface represents a row in the employees database table and captures both operational and audit fields. It includes identifying fields (`id`, employee_id), personal fields (`name`, email), payroll fields (`salary`), banking details (`account_number`, bank_code, bank_name), operational state (`is_active`), and timestamps (`created_at`, updated_at). The is_active flag is used to support soft deletion and employee deactivation without permanently removing historical payroll relationships.

export interface Employee {
  id: number;
  name: string;
  email: string;
  employee_id: string;
  salary: number;
  account_number: string;
  bank_code: string;
  bank_name: string;
  is_active: boolean;
  created_at: Date;
  updated_at: Date;
}

Now, we’ll define the CreateEmployeeInput interface which represent the expected payload for creating an employee. It includes required fields such as name, email, salary, and bank details.

export interface CreateEmployeeInput {
  name: string;
  email: string;
  employee_id?: string;
  salary: number;
  account_number: string;
  bank_code: string;
  bank_name: string;
}

The employee_id field is optional, allowing the system to auto-generate a unique identifier if one is not provided. This flexibility supports both automated workflows and manual HR data imports.

Employee Model Class

Next, we’ll define the EmployeeModel class.

export class EmployeeModel {
  // Class methods will go here
}

This class encapsulates all database operations related to employee records. It centralizes logic for creating, retrieving, updating, and deleting employees, as well as generating unique sequential employee IDs.

Auto-Generating Employee IDs (`generateEmployeeId`)

We start by creating the generateEmployeeId method inside the EmployeeModel class.

  private static async generateEmployeeId(): Promise<string> {
    // Get the highest existing employee_id number that matches EMP### pattern
    const result = await query(
      `SELECT employee_id FROM employees
       WHERE employee_id LIKE 'EMP%'
       AND LENGTH(employee_id) >= 4
       AND SUBSTRING(employee_id FROM 4) ~ '^[0-9]+$'
       ORDER BY CAST(SUBSTRING(employee_id FROM 4) AS INTEGER) DESC
       LIMIT 1`
    );

    if (result.rows.length === 0) {
      return 'EMP001';
    }

    const lastId = result.rows[0].employee_id;
    const numberPart = lastId.substring(3);
    const lastNumber = parseInt(numberPart, 10);

    if (isNaN(lastNumber)) {
      return 'EMP001';
    }

    const nextNumber = lastNumber + 1;
    // Format as EMP001, EMP002, etc. (3 digits minimum)
    return `EMP${nextNumber.toString().padStart(3, '0')}`;
  }

The private generateEmployeeId method generates a unique employee identifier in a readable sequential format such as EMP001, EMP002, and so on. It queries the database for the highest existing employee ID that matches the expected pattern (EMP prefix followed by numeric digits), orders by the numeric suffix in descending order, and increments the latest number to produce the next ID.

If no matching record exists, it starts from EMP001. The method also protects against malformed data by returning EMP001 if parsing fails.

Finally, it ensures formatting consistency by padding the number portion to at least three digits using padStart(3, '0'), which keeps IDs aligned and easy to sort visually.

Creating an Employee (`create`)

Next, we’ll define the create method, which inserts a new employee record into the database. If the caller does not supply an employee_id, the method generates one automatically using generateEmployeeId.

  static async create(data: CreateEmployeeInput): Promise {
    // Auto-generate employee_id if not provided
    let employeeId = data.employee_id;
    if (!employeeId) {
      employeeId = await this.generateEmployeeId();
    }

    // Check if employee_id already exists (if manually provided)
    if (data.employee_id) {
      const existing = await this.findByEmployeeId(data.employee_id);
      if (existing) {
        throw new Error('Employee ID already exists');
      }
    }

    const result = await query(
      `INSERT INTO employees (name, email, employee_id, salary, account_number, bank_code, bank_name)
       VALUES ($1, $2, $3, $4, $5, $6, $7)
       RETURNING *`,
      [
        data.name,
        data.email,
        employeeId,
        data.salary,
        data.account_number,
        data.bank_code,
        data.bank_name,
      ]
    );
    return result.rows[0];
  }

Here’s what’s happening in the code:

If an employee_id is manually provided, it validates uniqueness by checking if that ID already exists among active employees, preventing collisions and ensuring each employee has a distinct identifier. After validations, the employee is inserted into the employees table and the new record is returned. This method ensures every employee created has complete banking details required for payroll disbursement.

Retrieving All Active Employees (`findAll`)

The findAll method fetches all active employees from the database.

static async findAll(): Promise {
  const result = await query(
    'SELECT * FROM employees WHERE is_active = true ORDER BY created_at DESC'
  );
  return result.rows;
}

The findAll method returns all active employees (is_active = true) ordered by most recent creation date. This behavior supports common UI patterns such as HR dashboards and payroll selection screens, where only active employees should be visible by default.

Retrieving an Employee by Database ID (`findById`)

The findById method retrieves a single employee by the internal numeric primary key (id).

static async findById(id: number): Promisenull> {
  const result = await query('SELECT * FROM employees WHERE id = $1', [id]);
  return result.rows[0] || null;
}

If the employee does not exist, it returns null. This is typically used for internal operations such as payroll processing, updates, or admin detail views.

Retrieving an Employee by Employee Identifier (`findByEmployeeId`)

The findByEmployeeId method retrieves an active employee using the business-friendly employee_id (for example, EMP014).

static async findByEmployeeId(employeeId: string): Promisenull> {
    const result = await query(
      'SELECT * FROM employees WHERE employee_id = $1 AND is_active = true',
      [employeeId]
    );
    return result.rows[0] || null;
}

The method filters by is_active = true to prevent selecting deactivated employees during operations like payroll runs or HR searches.

Updating an Employee (`update`)

The update method supports partial updates by dynamically building the SQL SET clause based on the fields present in the update payload. It iterates through the provided properties, includes only those with defined values, and constructs a parameterized query to prevent SQL injection and preserve correctness.

static async update(
    id: number,
    data: Partial
  ): Promise {
    const fields: string[] = [];
    const values: any[] = [];
    let paramCount = 1;

    // Build dynamic update query based on provided fields
    Object.entries(data).forEach(([key, value]) => {
      if (value !== undefined) {
        fields.push(`${key} = $${paramCount}`);
        values.push(value);
        paramCount++;
      }
    });

    if (fields.length === 0) {
      throw new Error('No fields to update');
    }

    // Always update the updated_at timestamp
    fields.push(`updated_at = $${paramCount}`);
    values.push(new Date());
    values.push(id);

    const result = await query(
      `UPDATE employees SET ${fields.join(', ')} WHERE id = $${
        paramCount + 1
      } RETURNING *`,
      values
    );
    return result.rows[0];
  }

Here’s what’s happening in the code:

If no fields are provided, it throws an error to avoid performing a meaningless update. It also explicitly updates the updated_at timestamp to ensure accurate audit tracking. Finally, it returns the updated database record, making it easy for controllers to respond with the latest employee state.

Soft-Deleting an Employee (`delete`)

Finally, instead of permanently removing the employee record, the delete method performs a soft delete by setting is_active = false and updating the updated_at timestamp.

This approach preserves historical payroll references and audit trails while excluding inactive employees from standard queries like findAll. It’s especially important in payroll systems where historical payment records must remain valid and traceable even after an employee leaves the organization.

static async delete(id: number): Promise<void> {
  await query(
    'UPDATE employees SET is_active = false, updated_at = NOW() WHERE id = $1',
    [id]
  );
}

Key features of the employee model:

Auto-generates sequential employee IDs if not provided
Validates employee ID uniqueness
Supports soft deletion to preserve historical payroll records
Provides methods for finding employees by database ID or employee identifier

Payroll Model

The PayrollModel manages payroll batches and individual payroll items. A payroll represents a single payment cycle (for example, "December 2024"), while payroll items represent individual employee payments within that cycle. This separation allows us to track the status of each payment independently.

Key features:

Creates payroll batches with automatic calculation of totals
Supports filtering employees for selective payroll runs
Tracks status at both batch and item levels
Provides methods for reconciliation and status updates

Let's implement the Payroll Model.

We’ll begin by creating a new file at src/models/payroll.ts, where we’ll implement the payroll models that encapsulate payroll batch creation, employee payment tracking, and payroll status management.

First, import a shared database query helper to execute parameterized SQL safely.

import { query } from '../config/database';

This keeps raw SQL isolated from controllers and ensures protection against SQL injection.

Payroll Status Lifecycle

Next, we’ll define the PayrollStatus enum.

export enum PayrollStatus {
 PENDING = 'pending',
 PROCESSING = 'processing',
 COMPLETED = 'completed',
 FAILED = 'failed',
 PARTIALLY_COMPLETED = 'partially_completed',
}

The PayrollStatus enum defines all possible states for both payroll batches and individual payroll items:

PENDING – Created but not yet processed
PROCESSING – Currently being processed by background workers
COMPLETED – Successfully processed
FAILED – Processing failed
PARTIALLY_COMPLETED – Some items succeeded while others failed

Payroll Entity

With the payroll status lifecycle defined, we can now define the payroll entity.

The Payroll interface represents a single payroll run, such as a monthly salary payout. It stores aggregate and audit information including the payroll period, total salary amount, total number of employees, processing status, counts of successful and failed payments, and timestamps for creation, updates, and completion.

Add the following interface to src/models/payroll.ts:

export interface Payroll {
 id: number;
 payroll_period: string;
 total_amount: number;
 total_employees: number;
 status: PayrollStatus;
 processed_count: number;
 failed_count: number;
 created_at: Date;
 updated_at: Date;
 processed_at?: Date;
}

This entity acts as the parent record for all employee payments within a payroll cycle and is used to track overall payroll progress and outcomes.

Payroll Item Entity

Next, we’ll define the payroll item entity, which represents an individual employee payment within a payroll.

The PayrollItem tracks the employee being paid, the payment amount, its processing status, any transaction reference returned by the payment provider, error messages in case of failure, and relevant timestamps.

Add the following interface just below the Payroll interface:

export interface PayrollItem {
  id: number;
  payroll_id: number;
  employee_id: number;
  amount: number;
  status: PayrollStatus;
  transaction_reference?: string;
  error_message?: string;
  processed_at?: Date;
  created_at: Date;
  updated_at: Date;
}

This structure allows individual employee payments to be retried, audited, or reconciled independently without affecting the rest of the payroll batch.

Creating a Payroll (`PayrollModel.create`)

Now that we’ve defined the Payroll and PayrollItem entities, we can move on to creating a payroll batch.

To keep our business logic organized, we’ll introduce a PayrollModel class. This class will be responsible for creating payroll records, calculating aggregates, and generating individual payroll items for each employee.

Before writing the model itself, let’s define the input required to create a payroll.

Add the following interface below the PayrollItem interface:

export interface CreatePayrollInput {
  payroll_period: string;
  employee_ids?: number[];
}

payroll_period identifies the payroll run (for example, 2025-01)
employee_ids is optional and allows us to run payroll for a subset of employees, enabling selective payouts or retries

Next, create the PayrollModel class. This class will encapsulate all payroll-related database operations.

export class PayrollModel {
// Payroll model class methods will go here
}

We’ll start by implementing the create method, which is responsible for creating a new payroll batch.

The method performs the following steps:

Optionally filters employees if specific employee IDs are provided
Calculates aggregate payroll statistics from the employees table
Creates a payroll record with a PENDING status
Creates a payroll item for each eligible employee

Here’s the implementation:

  static async create(data: CreatePayrollInput): Promise {
    let employeeFilter = '';
    let queryParams: any[] = [];

    // Build filter for selective employee payrolls
    if (data.employee_ids && data.employee_ids.length > 0) {
      employeeFilter = `AND id = ANY($1::int[])`;
      queryParams = [data.employee_ids];
    }

    // Calculate aggregate statistics from employees table
    const employeeStats = await query(
      `SELECT COUNT(*) as count, COALESCE(SUM(salary), 0) as total
       FROM employees
       WHERE is_active = true ${employeeFilter}`,
      queryParams
    );

    const totalEmployees = parseInt(employeeStats.rows[0].count);
    const totalAmount = parseFloat(employeeStats.rows[0].total);

    // Create the payroll record
    const result = await query(
      `INSERT INTO payrolls (payroll_period, total_amount, total_employees, status)
       VALUES ($1, $2, $3, $4)
       RETURNING *`,
      [data.payroll_period, totalAmount, totalEmployees, PayrollStatus.PENDING]
    );

    const payroll = result.rows[0];

    // Create payroll items for each employee
    // Each item starts with PENDING status and will be processed asynchronously
    const employees = await query(
      `SELECT id, salary FROM employees WHERE is_active = true ${employeeFilter}`,
      queryParams
    );

    for (const employee of employees.rows) {
      await query(
        `INSERT INTO payroll_items (payroll_id, employee_id, amount, status)
         VALUES ($1, $2, $3, $4)`,
        [payroll.id, employee.id, employee.salary, PayrollStatus.PENDING]
      );
    }

    return payroll;
  }

The payroll creation process begins by determining which employees should be included. If specific employee IDs are provided, only those employees are selected – otherwise, all active employees are included. This allows the system to support both full payroll runs and selective payouts.

Next, the system calculates aggregate payroll statistics directly from the employees table by counting eligible employees and summing their salaries. These values are stored in a new payroll record created with a PENDING status.

Finally, a payroll item is generated for each eligible employee, with each item also initialized in a PENDING state. This design separates payroll setup from payment execution, allowing employee payments to be processed asynchronously and in parallel in later stages of the system.

Fetching Payroll Records

After creating payrolls, we often need to retrieve them for administrative dashboards, reporting, and audit trails.

The PayrollModel provides two simple methods:

findById – Retrieves a single payroll by its unique identifier
findAll – Retrieves all payroll records, ordered by creation date (newest first)

These methods should be added below the create method in the PayrollModel class:

static async findById(id: number): Promisenull> {
  const result = await query('SELECT * FROM payrolls WHERE id = $1', [id]);
  return result.rows[0] || null;
}

static async findAll(): Promise {
  const result = await query(
    'SELECT * FROM payrolls ORDER BY created_at DESC'
  );
  return result.rows;
}

The findById method retrieves a single payroll by its identifier, while findAll returns all payroll records ordered by creation date.

Updating Payroll Status (`PayrollModel.updateStatus`)

Once payroll processing begins, we need a way to track the overall status of a payroll batch. The updateStatus method updates the payroll record with:

The current status (PENDING, PROCESSING, COMPLETED, and so on)
Optional counts of processed and failed payments
A processed_at timestamp automatically set for terminal states (COMPLETED or PARTIALLY_COMPLETED)

Add the following method below the fetch methods in your PayrollModel class:


  static async updateStatus(
    id: number,
    status: PayrollStatus,
    processedCount?: number,
    failedCount?: number
  ): Promise {
    const updates: string[] = ['status = $2', 'updated_at = NOW()'];
    const values: any[] = [id, status];

    // Dynamically add processed_count if provided
    if (processedCount !== undefined) {
      updates.push(`processed_count = $${values.length + 1}`);
      values.push(processedCount);
    }

    // Dynamically add failed_count if provided
    if (failedCount !== undefined) {
      updates.push(`failed_count = $${values.length + 1}`);
      values.push(failedCount);
    }

    // Set processed_at timestamp for terminal states
    if (
      status === PayrollStatus.COMPLETED ||
      status === PayrollStatus.PARTIALLY_COMPLETED
    ) {
      updates.push(`processed_at = NOW()`);
    }

    const result = await query(
      `UPDATE payrolls SET ${updates.join(', ')} WHERE id = $1 RETURNING *`,
      values
    );
    return result.rows[0];
  }
}

As payroll processing progresses, this method updates the overall payroll status along with optional counts of processed and failed payments. When a payroll reaches a terminal state such as COMPLETED or PARTIALLY_COMPLETED, the system automatically records a completion timestamp. This ensures accurate tracking of payroll execution and supports reconciliation workflows.

PayrollItemModel

After handling payroll batches with PayrollModel, we need a way to manage individual employee payments. This is where the PayrollItemModel comes in. It encapsulates database operations related to payroll items, including fetching, and updating records with employee details.

Start by adding a new class below PayrollModel:

export class PayrollItemModel {
  // Methods will go here
}

Fetching Payroll Items (`PayrollItemModel.findByPayrollId`)

Often, we want to get all payroll items for a specific payroll batch. For example, to display them on a dashboard or process them in a background worker.

This findByPayrollId method does that exactly. It retrieves all payroll items associated with a specific payroll and enriches them with employee details such as name, bank account number, and bank information through a database join.

static async findByPayrollId(payrollId: number): Promise {
  const result = await query(
    `SELECT
       pi.id, pi.payroll_id, pi.employee_id, pi.amount, pi.status,
       pi.transaction_reference, pi.error_message, pi.processed_at,
       pi.created_at, pi.updated_at,
       e.name as employee_name, e.employee_id as employee_identifier,
       e.account_number, e.bank_code, e.bank_name
     FROM payroll_items pi
     JOIN employees e ON pi.employee_id = e.id
     WHERE pi.payroll_id = $1
     ORDER BY pi.created_at`,
      [payrollId]
    );
    // Normalize numeric fields from PostgreSQL (which returns them as strings)
    return result.rows.map((row) => ({
      ...row,
      employee_id: parseInt(row.employee_id, 10),
      id: parseInt(row.id, 10),
      payroll_id: parseInt(row.payroll_id, 10),
      amount: parseFloat(row.amount),
    }));
  }

Here’s what’s happening in the code:

We use a JOIN with the employees table so each payroll item includes the employee’s name, account number, and bank information.
Some numeric fields may come as strings, so we convert them to proper JavaScript numbers (parseInt / parseFloat) for accurate calculations and display.
The results are ordered by creation date, which helps when rendering items in a UI or processing them sequentially.

This method makes it easy to work with all items in a payroll batch while keeping the data enriched and consistent.

Fetching a Single Payroll Item (`PayrollItemModel.findById`)

Sometimes, you need to look at one specific employee’s payment (for example, to retry a failed transaction or investigate an issue). The findById method helps in fetching a single payroll item along with the employee’s details, so you have everything you need in one place.

Here’s how we implement it:

static async findById(id: number): Promisenull> {
  const result = await query(
    `SELECT
       pi.id, pi.payroll_id, pi.employee_id, pi.amount, pi.status,
       pi.transaction_reference, pi.error_message, pi.processed_at,
       pi.created_at, pi.updated_at,
       e.name as employee_name, e.employee_id as employee_identifier,
       e.account_number, e.bank_code, e.bank_name
     FROM payroll_items pi
     JOIN employees e ON pi.employee_id = e.id
     WHERE pi.id = $1`,
    [id]
  );

  if (result.rows.length === 0) return null;

  const row = result.rows[0];

  // Convert numeric fields to proper JavaScript numbers for easier calculations and display
  return {
    ...row,
    employee_id: parseInt(row.employee_id, 10),
    id: parseInt(row.id, 10),
    payroll_id: parseInt(row.payroll_id, 10),
    amount: parseFloat(row.amount),
  };
}

Here’s what’s happening in the code:

We use a JOIN with the employees table to include employee info such as name, account number, and bank details.
If the ID doesn’t exist, the method returns null so you can handle missing records gracefully.
Numeric fields are converted to JavaScript numbers, making it easy to calculate totals or display amounts in the UI.

This method ensures that whenever you need a single payroll item, you get a complete, ready-to-use record.

Updating Payroll Item Status (`PayrollItemModel.updateStatus`)

As individual employee payments are processed, this method updates the payroll item’s status, stores transaction references from external payment providers, captures error messages on failure, and timestamps completion or failure events. This fine-grained tracking enables reliable retries, audits, and reconciliation with external payment systems.

Here’s the implementation:

static async updateStatus(
  id: number,
  status: PayrollStatus,
  transactionReference?: string,
  errorMessage?: string
): Promise {
  const updates: string[] = ['status = $2', 'updated_at = NOW()'];
  const values: any[] = [id, status];

  // Add transaction reference if provided (from Monnify API response)
  if (transactionReference) {
    updates.push(`transaction_reference = $${values.length + 1}`);
    values.push(transactionReference);
  }

  // Add error message if provided (from failed payment)
  if (errorMessage) {
    updates.push(`error_message = $${values.length + 1}`);
    values.push(errorMessage);
  }

  // Set processed_at timestamp for terminal states
  if (status === PayrollStatus.COMPLETED || status === PayrollStatus.FAILED) {
    updates.push(`processed_at = NOW()`);
  }

  const result = await query(
    `UPDATE payroll_items SET ${updates.join(
      ', '
     )} WHERE id = $1 RETURNING *`,
     values
   );
   return result.rows[0];
 }
}

Here’s what’s happening in the code:

We build a dynamic SET clause to update only the fields provided – status is required, while transaction reference and error message are optional.
Terminal states (COMPLETED or FAILED) trigger an automatic timestamp on processed_at, so we always know when a payment finished.
The method returns the updated payroll item, ready for further processing, logging, or UI display.

This ensures each payroll item is tracked accurately throughout its lifecycle, enabling reliable retries and complete audit trails.

Overall Payroll Flow

In this payroll flow, an administrator creates a payroll batch, which generates individual payroll items for each employee. The payroll is then handed off to background workers that process each payroll item independently via an external payment service.

As each payment succeeds or fails, payroll items are updated accordingly. Once processing concludes, the payroll batch status is updated to reflect the overall outcome, whether fully successful, partially successful, or failed.

This architecture provides scalability, resilience, and strong auditability for real-world payroll systems.

Building the Monnify Client

The Monnify client is the bridge between our application and Monnify's payment API. In this section, we'll build a reusable client that handles authentication, bulk transfers, and transaction tracking. The client automatically manages API tokens, retries failed requests, and provides a clean interface for the rest of our application.

This module implements a reusable Monnify API client responsible for handling authentication, bulk payroll disbursements, authorization, transaction tracking, and balance checks in a secure and production-ready manner. It abstracts all Monnify-specific logic behind a single class, making it easy to integrate into background jobs, payroll processors, or service layers.

We’ll begin by creating a new file at src/config/monnify.ts where we’ll implement the Monnify client.

Configuration and Environment Setup

Start by loading the configuration from environment variables using dotenv, ensuring that sensitive credentials are never hardcoded. These include the Monnify API key, secret key, base URL, and contract code (wallet account number). This setup allows the same client to be safely used across development, staging, and production environments.

import axios, { AxiosInstance } from 'axios';
import dotenv from 'dotenv';

dotenv.config();

export interface MonnifyConfig {
  apiKey: string;
  secretKey: string;
  baseUrl: string;
  contractCode: string;
}

Create the `MonnifyClient` Class

Next, you’ll define the MonnifyClient class. This class encapsulates all communication with the Monnify API. It internally manages API credentials, an Axios HTTP client, an access token, and token expiry tracking.

export class MonnifyClient {
  private readonly apiKey: string;
  private readonly secretKey: string;
  private baseUrl: string;
  private contractCode: string;
  private client: AxiosInstance;

  private accessToken: string | null = null;
  private tokenExpiry: number = 0;

This design ensures authentication is handled transparently and automatically for every request.

Axios Client and Request Interceptor

Inside the constructor, initialize the Monnify client with credentials from environment variables. The Axios instance is created with the Monnify base URL and JSON headers.

  constructor() {
    this.apiKey = process.env.MONNIFY_API_KEY || '';
    this.secretKey = process.env.MONNIFY_SECRET_KEY || '';
    this.baseUrl = process.env.MONNIFY_BASE_URL || 'https://api.monnify.com';
    this.contractCode = process.env.MONNIFY_CONTRACT_CODE || '';

    this.client = axios.create({
      baseURL: this.baseUrl,
      headers: {
        'Content-Type': 'application/json',
      },
    });

We attach the request interceptor to this client to automatically inject a valid Bearer token into every outgoing request (except the authentication endpoint). Before each request, the interceptor ensures the client is authenticated, preventing unauthorized requests and eliminating token-related boilerplate across the codebase.

    this.client.interceptors.request.use(async (config: any) => {
      // Skip auth for the login endpoint itself
      if (config.url?.includes('/auth/login')) {
        return config;
      }

      // Ensure a valid token exists before every request
      await this.ensureAuthenticated();

      if (this.accessToken) {
        config.headers.Authorization = `Bearer ${this.accessToken}`;
      }

      return config;
    });
  }

Authenticate with Monnify

Authentication is handled using Monnify’s Basic Auth mechanism, where the API key and secret key are base64-encoded and sent to the /auth/login endpoint. Upon successful authentication, the client stores the returned access token and sets an internal expiry timestamp slightly below the official token lifetime to avoid edge-case expirations. Any authentication failure is logged and surfaced as a controlled error to prevent silent failures.


  private async authenticate(): Promise<void> {
    try {
      // Encode credentials as Base64 for Basic Auth
      const credentials = Buffer.from(
        `${this.apiKey}:${this.secretKey}`
      ).toString('base64');

      const response = await axios.post(
        `${this.baseUrl}/api/v1/auth/login`,
        {},
        {
          headers: {
            Authorization: `Basic ${credentials}`,
            'Content-Type': 'application/json',
          },
        }
      );

      this.accessToken = response.data.responseBody.accessToken;
      // Set expiry to 23 hours (Monnify tokens typically last 24 hours)
      // This prevents edge cases where token expires mid-request
      this.tokenExpiry = Date.now() + 23 * 60 * 60 * 1000;
    } catch (error: any) {
      console.error(
        'Monnify authentication error:',
        error.response?.data || error.message
      );
      throw new Error('Failed to authenticate with Monnify');
    }
  }

Automatic Token Refresh (`ensureAuthenticated`)

Before any API call, the client verifies whether a valid access token exists or if the token has expired. If so, it transparently re-authenticates.

  private async ensureAuthenticated(): Promise<void> {
    if (!this.accessToken || Date.now() >= this.tokenExpiry) {
      await this.authenticate();
    }
  }

This ensures that long-running processes such as payroll queues or background workers can safely make Monnify requests without manual token handling.

Initiating Bulk Transfers

The initiateBulkTransfer method handles the creation of a bulk disbursement batch, typically used for payroll payments. It validates input transfers to ensure each payment has a valid amount, destination account number, and bank code.

A structured batch request is then constructed, including a unique batch reference, source account (contract code), narration, and a list of transactions. The request is logged for traceability and sent to Monnify’s batch disbursement endpoint. Any API error is normalized and returned with meaningful messaging to aid debugging and retries.

  async initiateBulkTransfer(
    transfers: Array<{
      amount: number;
      recipientAccountNumber: string;
      recipientBankCode: string;
      recipientName: string;
      narration: string;
      reference: string;
    }>
  ): Promise<any> {
    await this.ensureAuthenticated();

We validate inputs early to fail fast:

    if (!transfers || transfers.length === 0) {
      throw new Error('No transfers provided');
    }

    if (!this.contractCode) {
      throw new Error('Monnify contract code is not configured');
    }

Each transfer is validated individually:

    for (const transfer of transfers) {
      if (!transfer.amount || transfer.amount <= 0) {
        throw new Error(`Invalid amount for transfer: ${transfer.reference}`);
      }
      if (!transfer.recipientAccountNumber) {
        throw new Error(`Missing account number for transfer: ${transfer.reference}`);
      }
      if (!transfer.recipientBankCode) {
        throw new Error(`Missing bank code for transfer: ${transfer.reference}`);
      }
    }

We then construct the batch payload:

    const requestBody = {
      title: 'Bulk Payroll Transfers',
      batchReference: `BATCH_${Date.now()}`,
      narration: 'Payroll batch disbursement',
      sourceAccountNumber: this.contractCode,
      onValidationFailure: 'CONTINUE',
      notificationInterval: 50,
      transactionList: transfers.map((t) => ({
        amount: t.amount,
        reference: t.reference,
        narration: t.narration,
        destinationBankCode: t.recipientBankCode,
        destinationAccountNumber: t.recipientAccountNumber,
        currency: 'NGN',
      })),
    };

Finally, we send the request and normalize errors:

    try {
      const response = await this.client.post(
        '/api/v2/disbursements/batch',
        requestBody
      );
      return response.data;
    } catch (error: any) {
      const errorData = error.response?.data;
      const message =
        errorData?.responseMessage ||
        errorData?.message ||
        `Monnify API error (${error.response?.status})`;
      throw new Error(message);
    }
  }

Authorizing Bulk Transfers (OTP Validation)

Some bulk transfers require OTP authorization. The authorizeBulkTransfer method validates the presence of a batch reference and authorization code before submitting them to Monnify’s OTP validation endpoint. This step finalizes the batch disbursement and allows processing to continue. Errors are logged and surfaced clearly for operational visibility.

async authorizeBulkTransfer(
reference: string,
authorizationCode: string
): Promise<any> {
await this.ensureAuthenticated();
    if (!reference) {
      throw new Error('Batch reference is required');
    }

    if (!authorizationCode) {
      throw new Error('Authorization code (OTP) is required');
    }

    const requestBody = {
      reference,
      authorizationCode,
    };

    try {
      const response = await this.client.post(
        '/api/v2/disbursements/batch/validate-otp',
        requestBody
      );

      return response.data;
    } catch (error: any) {
      const errorDetails = error.response?.data || error.message;
      console.error(
        'Monnify authorization error:',
        JSON.stringify(errorDetails, null, 2)
      );

      if (error.response) {
        const errorData = error.response.data;
        const errorMessage =
          errorData?.responseMessage ||
          errorData?.message ||
          `Monnify API error (${error.response.status})`;
        throw new Error(errorMessage);
      }
      throw error;
    }
}

Transaction Status Lookup

The getTransactionStatus method retrieves the real-time status of an individual transaction using its reference.

async getTransactionStatus(transactionReference: string): Promise<any> {
await this.ensureAuthenticated();
    try {
      const response = await this.client.get(
        `/api/v2/disbursements/${transactionReference}/status`
      );
      return response.data;
    } catch (error: any) {
      console.error(
        'Monnify status check error:',
        error.response?.data || error.message
      );
      throw error;
    }
}

This is useful for reconciliation, webhook fallbacks, or manual verification of disbursement outcomes.

Batch Details Retrieval

The getBatchDetails method fetches detailed information about an entire disbursement batch, including the state of individual transactions.

async getBatchDetails(batchReference: string): Promise<any> {
await this.ensureAuthenticated();
    if (!batchReference) {
      throw new Error('Batch reference is required');
    }

    try {
      const response = await this.client.get(
        `/api/v2/disbursements/batch/${batchReference}`
      );
      return response.data;
    } catch (error: any) {
      console.error(
        'Monnify batch details error:',
        error.response?.data || error.message
      );
      throw error;
    }
}

This is particularly useful when reconciling payroll runs or recovering from partial failures.

Wallet Balance Check

Finally, we can query the available balance of the Monnify wallet.

The getAccountBalance method retrieves the available balance of the configured Monnify wallet (contract account).

Create src/config/monnify.ts:

async getAccountBalance(): Promise<any> {
await this.ensureAuthenticated();

    try {
      const response = await this.client.get(
        `/api/v2/disbursements/wallet-balance?accountNumber=${this.contractCode}`
      );
      return response.data;
    } catch (error: any) {
      console.error(
        'Monnify balance check error:',
        error.response?.data || error.message
      );
      throw error;
    }
}

export const monnifyClient = new MonnifyClient();

Key features of this client:

Automatic token management: The client automatically handles authentication and refreshes tokens before they expire.
Request interceptor: Every API request automatically includes the authentication token.
Bulk transfers: Uses Monnify's batch disbursement API for efficient payroll processing.
Error handling: Comprehensive error handling with meaningful error messages.

Implementing Background Job Processing

To avoid blocking HTTP requests and to ensure reliable retries, payroll execution is handled asynchronously using a background job processor. This worker is responsible for orchestrating bulk payroll disbursements, coordinating with Monnify, updating payroll and payroll item states, and handling retries safely.

Begin by creating a new file at src/jobs/payroll.processor.ts. All background payroll execution logic will live in this file.

Set Up the Payroll Processing Queue

We’ll create a Bull queue named payroll-processing and a backed by Redis. Redis connection details are loaded from environment variables, allowing flexibility across environments.

Default job options are configured to retry failed jobs up to three times using an exponential backoff strategy. This ensures resilience against transient failures such as network issues or temporary payment gateway downtime. Completed jobs are automatically removed from the queue to keep Redis storage clean.

import Queue from 'bull';
import { monnifyClient } from '../config/monnify';
import {
 PayrollItemModel,
 PayrollModel,
 PayrollStatus,
} from '../models/payroll';
import { EmployeeModel } from '../models/employee';

export const payrollQueue = new Queue('payroll-processing', {
 redis: {
 host: process.env.REDIS_HOST || 'localhost',
 port: Number(process.env.REDIS_PORT || 6379),
},
defaultJobOptions: {
 attempts: 3,
 backoff: { 
  type: 'exponential', 
  delay: 2000 
},
 removeOnComplete: true,
},
});

Queue Processor Registration

The queue registers a processor function using payrollQueue.process, which receives jobs containing a payrollId. Each job triggers the processBulkPayroll function, making the queue responsible for executing one payroll batch at a time.

payrollQueue.process(async (job) => {
 return processBulkPayroll(job.data.payrollId);
});

This design decouples payroll execution from HTTP requests and allows processing to happen asynchronously in background workers.

Bulk Payroll Processing Flow (`processBulkPayroll`)

When a payroll job is picked up, the system first fetches all payroll items associated with the given payroll ID. It filters out only items that are eligible for processing: those still in a PENDING state or previously marked as PROCESSING but missing a transaction reference.

async function processBulkPayroll(payrollId: number) {

const items = await PayrollItemModel.findByPayrollId(payrollId);

Also, it filters payroll items to include only those that still require processing. This prevents duplicate payments when jobs are retried.

const payable = items.filter(
  (i) =>
    i.status === PayrollStatus.PENDING ||
    (i.status === PayrollStatus.PROCESSING && !i.transaction_reference)
);

if (payable.length === 0) return;

If no payable items remain, the function exits early, avoiding unnecessary API calls.

Once we confirm there are payable items, we update the overall payroll status:

  await PayrollModel.updateStatus(payrollId, PayrollStatus.PROCESSING);

This provides immediate visibility that disbursement is underway.

Building the Bulk Transfer Payload

Create a variable to store the transfer list that will be sent to Monnify.

  const transfers = [];

For each payable payroll item, the corresponding employee record is fetched to retrieve bank and account details. A unique payment reference is generated using the payroll ID and payroll item ID, ensuring traceability across systems. Each payroll item is immediately marked as PROCESSING before initiating payment to prevent concurrent workers from attempting to process the same item.

A transfer object is then constructed containing the payment amount, recipient bank details, narration, and unique reference. These transfer objects are accumulated into a single batch request.

for (const item of payable) {
const employee = await EmployeeModel.findById(item.employee_id);
if (!employee) throw new Error('Employee not found');

    const reference = `PAYROLL_${payrollId}_${item.id}`;

    await PayrollItemModel.updateStatus(item.id, PayrollStatus.PROCESSING);

    transfers.push({
      amount: Number(item.amount),
      reference,
      recipientAccountNumber: employee.account_number,
      recipientBankCode: employee.bank_code,
      recipientName: employee.name,
      narration: `Payroll payment`,
    });

}

Initiating Bulk Disbursement via Monnify

Once all transfers are prepared, the system initiates a bulk transfer through the Monnify client.

const response = await monnifyClient.initiateBulkTransfer(transfers);

if (!response?.requestSuccessful) {
  throw new Error('Bulk transfer initiation failed');
}

If Monnify doesn’t confirm successful initiation, the job throws an error, allowing Bull’s retry mechanism to take over. This ensures failed initiation attempts are retried safely without manual intervention.

Storing Transaction References

After a successful bulk transfer initiation, Monnify returns a list of transactions containing unique transaction references. The system matches each response entry to its corresponding payroll item using the generated reference and updates the payroll item record with the Monnify transaction reference while keeping its status as PROCESSING.

const results = response.responseBody?.transactionList || [];

for (const item of payable) {
const ref = `PAYROLL_${payrollId}_${item.id}`;
const match = results.find((r: any) => r.reference === ref);

    if (match?.transactionReference) {
      await PayrollItemModel.updateStatus(
        item.id,
        PayrollStatus.PROCESSING,
        match.transactionReference
      );
    }

}

await updatePayrollStats(payrollId);
}

This step is critical for later reconciliation through webhooks or status polling.

Payroll Statistics Reconciliation (`updatePayrollStats`)

After initiating payments, the system recalculates payroll-level statistics by refetching all payroll items.

async function updatePayrollStats(payrollId: number) {
const items = await PayrollItemModel.findByPayrollId(payrollId);

const completed = items.filter(
  (i) => i.status === PayrollStatus.COMPLETED
).length;

The overall payroll status is derived from these counts:

const failed = items.filter((i) => i.status === PayrollStatus.FAILED).length;

let status = PayrollStatus.PROCESSING;

if (completed === items.length) {
  status = PayrollStatus.COMPLETED;
} else if (failed === items.length) {
  status = PayrollStatus.FAILED;
} else if (completed > 0) {
  status = PayrollStatus.PARTIALLY_COMPLETED;
}

 await PayrollModel.updateStatus(payrollId, status, completed, failed);
}

If all items are completed, the payroll is marked as COMPLETED. If all failed, it’s marked as FAILED. If some succeeded and some failed, it’s marked as PARTIALLY_COMPLETED. Otherwise, it remains in PROCESSING. The payroll record is then updated with the new status and aggregate counts, providing an accurate real-time snapshot of payroll execution.

Queue Entry Point (`processPayrollItems`)

The processPayrollItems function serves as the public entry point for triggering payroll execution.

export async function processPayrollItems(payrollId: number) {
  await payrollQueue.add({ payrollId, type: 'bulk' });
}

It simply enqueues a payroll job with the relevant payroll ID, allowing controllers or services to initiate payroll processing without coupling themselves to queue logic or payment execution details.

Role in the Overall Payroll Architecture

This queue worker acts as the execution engine of the payroll system. It:

Bridges payroll domain models with the Monnify payment gateway
Ensures safe retries through Bull’s job management and maintains idempotency
Continuously synchronizes payroll and payroll item states

By offloading payment execution to background workers, the system achieves scalability, reliability, and operational resilience required for real-world payroll processing.

Key features of the job processor:

Exponential backoff: Failed jobs are retried with increasing delays (2s, 4s, 8s).
Bulk processing: All payroll items are processed as a single batch transfer.
Status tracking: Each item's status is updated throughout the process.
Automatic cleanup: Completed jobs are automatically removed from the queue.

Creating the API Controllers

Next, we’ll build the HTTP controller layer for managing employees in the payroll system using Express.js. It exposes RESTful API endpoints that handle incoming requests, perform validation, interact with the employee data model, and return appropriate HTTP responses.

The controller acts as the bridge between client-facing APIs and the underlying business logic encapsulated in the EmployeeModel.

Controller Responsibilities

The EmployeeController is responsible for:

Validating incoming request data
Calling the appropriate model methods
Handling errors gracefully
Returning meaningful HTTP status codes and JSON responses

Each method follows a consistent structure using try–catch blocks to ensure reliability and simplify error handling.

Start by creating a new file at src/controllers/employee.controller.ts. This file will contain all the endpoints needed to manage employees in the payroll system.

At the top of the file, import the required Express types and the employee model:

import { Request, Response } from 'express';
import { EmployeeModel, CreateEmployeeInput } from '../models/employee';

export class EmployeeController {
  // Controller methods will go here
}

Each method inside this class will map to a specific API endpoint.

Creating an Employee (`createEmployee`)

We’ll start with an endpoint for creating a new employee.

This endpoint handles the creation of a new employee record. It extracts the request body and validates the presence of required fields such as name, email, salary, bank account number, and bank code.

static async createEmployee(req: Request, res: Response): Promise<void> {
try {
const data: CreateEmployeeInput = req.body;

      if (
        !data.name ||
        !data.email ||
        !data.salary ||
        !data.account_number ||
        !data.bank_code
      ) {
        res.status(400).json({
          error:
            'Missing required fields: name, email, salary, account_number, bank_code',
        });
        return;
      }

      const employee = await EmployeeModel.create(data);
      res.status(201).json({
        message: 'Employee created successfully',
        data: employee,
      });
    } catch (error: any) {
      console.error('Error creating employee:', error);
      res
        .status(500)
        .json({ error: error.message || 'Failed to create employee' });
    }

}

If any required field is missing, the request is rejected with a 400 Bad Request response.

Upon successful validation, the controller delegates employee creation to the EmployeeModel.create method and returns a 201 Created response containing the newly created employee. Any unexpected error during the process results in a 500 Internal Server Error.

Fetching All Employees (`getAllEmployees`)

Next, we’ll add an endpoint for retrieving all employee records from the system.

This endpoint simply calls EmployeeModel.findAll and returns the result as a JSON response. This API is typically used for administrative dashboards, payroll preparation, or reporting purposes.

static async getAllEmployees(req: Request, res: Response): Promise<void> {
  try {
    const employees = await EmployeeModel.findAll();
    res.json({ data: employees });
  } catch (error: any) {
    console.error('Error fetching employees:', error);
    res
      .status(500)
      .json({ error: error.message || 'Failed to fetch employees' });
  }
}

If the retrieval is successful, the controller responds with the full list of employees. If something goes wrong, such as a database or unexpected runtime error, the error is logged and a 500 Internal Server Error is returned to the client.

Fetching a Single Employee (`getEmployeeById`)

After listing all employees, the next logical step is being able to fetch a single employee by their ID.

This endpoint retrieves a specific employee by ID, which is parsed from the URL parameters. If the employee doesn’t exist, the controller responds with a 404 Not Found. Otherwise, the employee data is returned in a successful response. This endpoint is useful for viewing or editing individual employee details.

  static async getEmployeeById(req: Request, res: Response): Promise<void> {
    try {
      const { id } = req.params;
      const employee = await EmployeeModel.findById(parseInt(id));

      if (!employee) {
        res.status(404).json({ error: 'Employee not found' });
        return;
      }

      res.json({ data: employee });
    } catch (error: any) {
      console.error('Error fetching employee:', error);
      res
        .status(500)
        .json({ error: error.message || 'Failed to fetch employee' });
    }
  }

Updating an Employee (`updateEmployee`)

Now that we can retrieve individual employees, the next step is allowing their details to be updated.

This endpoint allows partial updates to an existing employee record. It first checks whether the employee exists before attempting an update.

If the employee isn’t found, a 404 Not Found response is returned. If the employee exists, the controller forwards the update payload to EmployeeModel.update and returns the updated employee record. This approach ensures data integrity and prevents silent failures.

  static async updateEmployee(req: Request, res: Response): Promise<void> {
    try {
      const { id } = req.params;
      const data: Partial = req.body;

      const employee = await EmployeeModel.findById(parseInt(id));
      if (!employee) {
        res.status(404).json({ error: 'Employee not found' });
        return;
      }

      const updated = await EmployeeModel.update(parseInt(id), data);
      res.json({
        message: 'Employee updated successfully',
        data: updated,
      });
    } catch (error: any) {
      console.error('Error updating employee:', error);
      res
        .status(500)
        .json({ error: error.message || 'Failed to update employee' });
    }
  }

Deleting an Employee (`deleteEmployee`)

Finally, the last endpoint in the EmployeeController handles employee deletion.

Before deleting, it verifies that the employee exists to avoid invalid delete operations. If found, the employee record is removed using EmployeeModel.delete, and a success message is returned. If the employee doesn’t exist, the controller responds with a 404 Not Found.

 static async deleteEmployee(req: Request, res: Response): Promise<void> {
    try {
      const { id } = req.params;

      const employee = await EmployeeModel.findById(parseInt(id));
      if (!employee) {
        res.status(404).json({ error: 'Employee not found' });
        return;
      }

      await EmployeeModel.delete(parseInt(id));
      res.json({ message: 'Employee deleted successfully' });
    } catch (error: any) {
      console.error('Error deleting employee:', error);
      res
        .status(500)
        .json({ error: error.message || 'Failed to delete employee' });
    }
  }

Error Handling Strategy

All controller methods use structured error handling to log errors internally while returning clean and user-friendly error messages to API consumers. This separation ensures sensitive implementation details are not leaked while still providing useful feedback for debugging and client-side handling.

Role in the Overall Payroll System

The EmployeeController provides the foundational APIs required for managing employee records, which are essential inputs for payroll processing. By cleanly separating HTTP concerns from business logic and persistence layers, this controller supports maintainability, scalability, and clear system boundaries within the payroll architecture.

Payroll Controller

This module defines the PayrollController, which serves as the primary HTTP-facing orchestration layer for payroll operations in the system. It exposes RESTful APIs that allow clients to create payrolls, retrieve payroll data, trigger payroll processing, reconcile payment results, authorize bulk transfers, and monitor transaction and account statuses.

Controller Responsibilities

The PayrollController is responsible for:

Accepting and validating client requests related to payrolls
Managing payroll lifecycle transitions (creation → processing → completion)
Triggering background job execution for bulk payroll disbursement
Reconciling payment results with Monnify
Providing real-time payroll and transaction status visibility
Acting as a safe boundary between external clients and internal services

To get started, create a new file src/controllers/payroll.controller.ts. This is where we’ll define all payroll-related endpoints.

At the top of src/controllers/payroll.controller.ts, we start with the following imports:

import { Request, Response } from 'express';
import {
  PayrollModel,
  PayrollItemModel,
  PayrollStatus,
} from '../models/payroll';
import { processPayrollItems } from '../jobs/payroll.processor';
import { monnifyClient } from '../config/monnify';

Here’s what each of these is responsible for:

Request and Response (from Express): These types give us strongly typed access to incoming HTTP requests and outgoing responses.
PayrollModel: This model handles payroll batch operations such as creating payrolls, fetching them, and updating their overall status.
PayrollItemModel: This model lets us fetch and update those items, especially during processing and reconciliation.
PayrollStatus: This is an enum that defines the valid states of a payroll or payroll item (for example: PENDING, PROCESSING, COMPLETED, FAILED). Using an enum helps keep state transitions explicit and consistent across the system.
processPayrollItems: This function is responsible for handing off payroll processing to background workers. Instead of processing payrolls synchronously in the HTTP request, we queue the work and let workers handle it asynchronously.
monnifyClient: This is our gateway to the external payment service. We use it to authorize bulk transfers, check transaction statuses, reconcile payments, and fetch account balances.

Together, these imports give the controller everything it needs to process payroll operations.

With our imports in place, we can now define the controller class itself. This class will serve as the single home for all payroll-related endpoints.

export class PayrollController {
  // Payroll endpoints will live here
}

Creating a Payroll (`createPayroll`)

With the controller in place, we’ll begin by implementing the endpoint create payroll. This endpoint initializes a new payroll batch, allowing us to either process all employees or a subset by their IDs.

static async createPayroll(req: Request, res: Response): Promise<void> {
try {
const { payroll_period, employee_ids } = req.body;

      if (!payroll_period) {
        res.status(400).json({ error: 'payroll_period is required' });
        return;
      }

      const processedEmployeeIds = employee_ids
        ? employee_ids
            .map((id: any) => parseInt(id, 10))
            .filter((id: number) => !isNaN(id))
        : undefined;

      const payroll = await PayrollModel.create({
        payroll_period,
        employee_ids: processedEmployeeIds,
      });

      res.status(201).json({
        message: 'Payroll created successfully',
        data: payroll,
      });
    } catch (error: any) {
      console.error('Error creating payroll:', error);
      res
        .status(500)
        .json({ error: error.message || 'Failed to create payroll' });
    }

}

Here’s what’s happening in the code:

The endpoint requires a payroll_period and optionally accepts a list of employee IDs to support partial payroll runs.
Incoming employee IDs are normalized and validated to ensure they are valid integers before being passed to the payroll model.
The controller delegates the actual creation logic to PayrollModel.create, which computes totals and creates payroll items.
On success, the API responds with a 201 Created status and the newly created payroll record.

Fetching All Payrolls (`getAllPayrolls`)

This endpoint retrieves all payroll batches in the system. It’s typically used for administrative dashboards and payroll history views. The controller simply delegates to PayrollModel.findAll and returns the results in a structured JSON response.

static async getAllPayrolls(req: Request, res: Response): Promise<void> {
try {
const payrolls = await PayrollModel.findAll();
res.json({ data: payrolls });
} catch (error: any) {
console.error('Error fetching payrolls:', error);
res
.status(500)
.json({ error: error.message || 'Failed to fetch payrolls' });
}
}

static async getPayrollById(req: Request, res: Response): Promise<void> {
try {
const { id } = req.params;
const payroll = await PayrollModel.findById(parseInt(id));

      if (!payroll) {
        res.status(404).json({ error: 'Payroll not found' });
        return;
      }

      const items = await PayrollItemModel.findByPayrollId(payroll.id);

      res.json({
        data: {
          ...payroll,
          items,
        },
      });
    } catch (error: any) {
      console.error('Error fetching payroll:', error);
      res
        .status(500)
        .json({ error: error.message || 'Failed to fetch payroll' });
    }
}

Fetching a Payroll with Items (`getPayrollById`)

Next, we’ll implement an endpoint to retrieve a single payroll by its ID along with all associated payroll items. This is useful for administrative dashboards and payroll history views.

static async getPayrollById(req: Request, res: Response): Promise<void> {
try {
const { id } = req.params;
const payroll = await PayrollModel.findById(parseInt(id));

      if (!payroll) {
        res.status(404).json({ error: 'Payroll not found' });
        return;
      }

      const items = await PayrollItemModel.findByPayrollId(payroll.id);

      res.json({
        data: {
          ...payroll,
          items,
        },
      });
    } catch (error: any) {
      console.error('Error fetching payroll:', error);
      res
        .status(500)
        .json({ error: error.message || 'Failed to fetch payroll' });
    }

}

In the code, we read the id parameter from the URL and convert it to an integer.

If the payroll does not exist, a 404 Not Found response is returned. When found, the controller aggregates payroll metadata and its child payroll items into a single response object, making it convenient for detailed payroll inspection and UI rendering.

Processing a Payroll (`processPayroll`)

Next, we implement the processPayroll endpoint. This endpoint initiates payroll execution. Before queuing the payroll for processing, the controller enforces important state checks to prevent duplicate or invalid execution, ensuring payrolls that are already PROCESSING or COMPLETED cannot be reprocessed.

static async processPayroll(req: Request, res: Response): Promise<void> {
try {
const { id } = req.params;

      const payroll = await PayrollModel.findById(Number(id));

      if (!payroll) {
        res.status(404).json({ error: 'Payroll not found' });
        return;
      }

      if (
        payroll.status === PayrollStatus.COMPLETED ||
        payroll.status === PayrollStatus.PROCESSING
      ) {
        res.status(400).json({
          error: `Payroll already ${payroll.status}`,
        });
        return;
      }

      // Queue the payroll for processing
      await processPayrollItems(payroll.id);

      res.json({
        message: 'Payroll queued for bulk processing',
        data: {
          payroll_id: payroll.id,
          processing_mode: 'bulk',
        },
      });
    } catch (error: any) {
      console.error('Error processing payroll:', error);
      res.status(500).json({
        error: error.message || 'Failed to process payroll',
      });
    }
}

Here’s what’s happening in the code:

We get the id parameter from the URL and convert it to a number.
If no payroll is found with the given ID, we return a 404 Not Found response.
Before queuing, we check the payroll’s current status. Payrolls that are already PROCESSING or COMPLETED cannot be reprocessed.
Valid payrolls are handed off to processPayrollItems, which runs the bulk execution in background workers (Bull jobs).
Once queued, we respond with a JSON object confirming the payroll is ready for bulk processing.

Reconciling Payroll Payments (`reconcilePayroll`)

Next, we’ll implement the endpoint that reconciles payroll payments. This ensures that the statuses of payroll items in our system match the actual payment outcomes from Monnify.

static async reconcilePayroll(req: Request, res: Response): Promise<void> {
try {
const { id } = req.params;

      const payroll = await PayrollModel.findById(Number(id));
      if (!payroll) {
        res.status(404).json({ error: 'Payroll not found' });
        return;
      }

      const items = await PayrollItemModel.findByPayrollId(Number(id));

      const itemsToReconcile = items.filter(
        (item) => item.transaction_reference
      );

      if (itemsToReconcile.length === 0) {
        res.json({
          message: 'No items to reconcile (no transaction references found)',
          reconciled: 0,
        });
        return;
      }

      let updated = 0;
      let errors = 0;

      for (const item of itemsToReconcile) {
        try {
          const txStatus = await monnifyClient.getTransactionStatus(
            item.transaction_reference!
          );

          const responseBody = txStatus.responseBody || txStatus;
          const paymentStatus =
            responseBody.paymentStatus || responseBody.status;

          if (
            paymentStatus === 'PAID' &&
            item.status !== PayrollStatus.COMPLETED
          ) {
            await PayrollItemModel.updateStatus(
              item.id,
              PayrollStatus.COMPLETED,
              item.transaction_reference
            );
            updated++;
          } else if (
            paymentStatus === 'FAILED' &&
            item.status !== PayrollStatus.FAILED
          ) {
            const errorMessage =
              responseBody.paymentDescription ||
              responseBody.failureReason ||
              'Transaction failed';
            await PayrollItemModel.updateStatus(
              item.id,
              PayrollStatus.FAILED,
              item.transaction_reference,
              errorMessage
            );
            updated++;
          }
        } catch (error: any) {
          errors++;
          console.error(`Error reconciling item ${item.id}:`, error.message);
        }
      }

      // Update payroll stats
      await PayrollController.updatePayrollStats(Number(id));

      res.json({
        message: 'Payroll reconciled successfully',
        reconciled: updated,
        errors,
        total: itemsToReconcile.length,
      });
    } catch (error: any) {
      console.error('Error reconciling payroll:', error);
      res.status(500).json({
        error: error.message || 'Failed to reconcile payroll',
      });
    }
}

The endpoint retrieves all payroll items with transaction references and queries Monnify for each transaction’s status. Based on the response, payroll items are updated to either COMPLETED or FAILED, with failure reasons captured where applicable.

Errors during reconciliation are tracked and logged without aborting the entire reconciliation process. After reconciliation, payroll-level statistics are recalculated to ensure consistency between item-level and batch-level states.

Payroll Statistics Update (Internal Helper)

The private updatePayrollStats method recalculates payroll status based on the aggregate states of its payroll items.

private static async updatePayrollStats(payrollId: number): Promise<void> {
const items = await PayrollItemModel.findByPayrollId(payrollId);

    const completed = items.filter(
      (i) => i.status === PayrollStatus.COMPLETED
    ).length;
    const failed = items.filter(
      (i) => i.status === PayrollStatus.FAILED
    ).length;
    const total = items.length;

    let status: PayrollStatus;
    if (completed === total) {
      status = PayrollStatus.COMPLETED;
    } else if (failed === total) {
      status = PayrollStatus.FAILED;
    } else if (completed > 0) {
      status = PayrollStatus.PARTIALLY_COMPLETED;
    } else {
      status = PayrollStatus.PROCESSING;
    }

    await PayrollModel.updateStatus(payrollId, status, completed, failed);

}

The endpoint determines whether a payroll is fully completed, fully failed, partially completed, or still processing, and updates the payroll record accordingly.

This logic guarantees that the payroll’s summary status always reflects the true execution state of its underlying payments.

Fetching Payroll Status Summary (`getPayrollStatus`)

Next, we’ll implement the getPayrollStatus endpoint. This endpoint provides a comprehensive status snapshot of a payroll. In addition to returning payroll metadata and items, it computes a summary breakdown of completed, failed, pending, and processing items. This endpoint is particularly useful for real-time dashboards, monitoring tools, and operational visibility.

static async getPayrollStatus(req: Request, res: Response): Promise<void> {
try {
const { id } = req.params;
const payroll = await PayrollModel.findById(parseInt(id));

      if (!payroll) {
        res.status(404).json({ error: 'Payroll not found' });
        return;
      }

      const items = await PayrollItemModel.findByPayrollId(payroll.id);

      res.json({
        data: {
          ...payroll,
          items,
          summary: {
            total: items.length,
            completed: items.filter((i) => i.status === PayrollStatus.COMPLETED)
              .length,
            failed: items.filter((i) => i.status === PayrollStatus.FAILED)
              .length,
            pending: items.filter((i) => i.status === PayrollStatus.PENDING)
              .length,
            processing: items.filter(
              (i) => i.status === PayrollStatus.PROCESSING
            ).length,
          },
        },
      });
    } catch (error: any) {
      console.error('Error fetching payroll status:', error);
      res
        .status(500)
        .json({ error: error.message || 'Failed to fetch payroll status' });
    }
}

Authorizing Bulk Transfers (`authorizeBulkTransfer`)

Next, we’ll implement the authorizeBulkTransfer endpoint. Some bulk disbursements require OTP authorization from Monnify. This endpoint accepts a batch reference and authorization code, validates their presence, and forwards them to the Monnify client for verification. Successful authorization allows the bulk transfer to proceed, while failures are clearly reported to the client.

static async authorizeBulkTransfer(
req: Request,
res: Response
): Promise<void> {
try {
const { reference, authorizationCode, payrollId } = req.body;

      if (!reference) {
        res.status(400).json({ error: 'Batch reference is required' });
        return;
      }

      if (!authorizationCode) {
        res.status(400).json({ error: 'Authorization code (OTP) is required' });
        return;
      }

      const result = await monnifyClient.authorizeBulkTransfer(
        reference,
        authorizationCode
      );

      res.json({
        message: 'Bulk transfer authorized successfully',
        data: result,
      });
    } catch (error: any) {
      console.error('Error authorizing bulk transfer:', error);
      res.status(500).json({
        error: error.message || 'Failed to authorize bulk transfer',
      });
    }
}

Here is what’s happening in the code:

Firstly, we get the batch reference, OTP, and optional payroll ID from the request body.
We return a 400 Bad Request if the reference or OTP is missing.
Next, we send the reference and OTP to Monnify to approve the bulk transfer.
If successful, return a JSON confirmation with Monnify’s response.

Checking Transaction Status (`checkTransactionStatus`)

This endpoint allows clients or administrators to query the status of an individual transaction using its reference. It delegates the lookup to the Monnify client and returns the raw response, making it useful for debugging, audits, or manual verification workflows.

static async checkTransactionStatus(
req: Request,
res: Response
): Promise<void> {
try {
const { reference } = req.params;

      if (!reference) {
        res.status(400).json({ error: 'Transaction reference is required' });
        return;
      }

      const status = await monnifyClient.getTransactionStatus(reference);
      res.json({ data: status });
    } catch (error: any) {
      console.error('Error checking transaction status:', error);
      res
        .status(500)
        .json({ error: error.message || 'Failed to check transaction status' });
    }
}

Checking Wallet Balance (`getAccountBalance`)

This endpoint retrieves the current balance of the Monnify wallet associated with the payroll contract code. It’s typically used for pre-disbursement checks, monitoring available funds, or administrative reporting.

  static async getAccountBalance(req: Request, res: Response): Promise<void> {
    try {
      const balance = await monnifyClient.getAccountBalance();
      res.json({ data: balance });
    } catch (error: any) {
      console.error('Error fetching account balance:', error);
      res
        .status(500)
        .json({ error: error.message || 'Failed to fetch account balance' });
    }
  }

Error Handling and Resilience

All controller methods use structured try–catch blocks to ensure unexpected failures are logged and surfaced as controlled HTTP error responses. This approach prevents sensitive internal errors from leaking while maintaining clarity and debuggability for API consumers.

Role in the Overall Payroll Architecture

The PayrollController acts as the central coordinator of the payroll system. It bridges client requests, domain models, background job processing, and external payment services into a cohesive workflow.

By enforcing state transitions, delegating heavy processing to background workers, and providing reconciliation and monitoring capabilities, this controller ensures payroll execution remains reliable, auditable, and scalable in real-world production environments.

Setting Up Webhook Handlers

Webhooks are essential for receiving real-time payment status updates from Monnify. When a payment completes or fails, Monnify sends a notification to your webhook endpoint.

Start by creating a new file src/routes/monnify.webhook.ts. This file will contain everything related to handling Monnify webhook events.


import { Router, Request, Response } from 'express';
import crypto from 'crypto';
import {
PayrollItemModel,
PayrollModel,
PayrollStatus,
} from '../models/payroll';

const router = Router();

function verifySignature(req: Request): boolean {
const signature = req.headers['monnify-signature'] as string;
if (!signature) return false;

const secret = process.env.MONNIFY_WEBHOOK_SECRET!;
const hash = crypto
.createHmac('sha512', secret)
.update(JSON.stringify(req.body))
.digest('hex');

return hash === signature;
}

router.post('/monnify/webhook', async (req: Request, res: Response) => {
try {
console.log('Monnify Webhook:', JSON.stringify(req.body, null, 2));

    const { eventType, eventData } = req.body;

    if (!eventData?.reference) {
      console.warn('Missing reference, ignoring webhook');
      return res.status(200).send('Ignored');
    }

    const paymentReference = eventData.reference;
    const transactionReference = eventData.transactionReference;
    const description = eventData.transactionDescription || '';

    // Parse our reference format: PAYROLL_{payrollId}_{itemId}
    const [prefix, payrollIdStr, itemIdStr] = paymentReference.split('_');

    if (prefix !== 'PAYROLL') {
      console.warn('Invalid payment reference format:', paymentReference);
      return res.status(200).send('Ignored');
    }

    const payrollId = Number(payrollIdStr);
    const itemId = Number(itemIdStr);

    if (isNaN(payrollId) || isNaN(itemId)) {
      console.warn('Invalid payroll/item IDs:', paymentReference);
      return res.status(200).send('Ignored');
    }

    const item = await PayrollItemModel.findById(itemId);

    if (!item) {
      console.warn('Payroll item not found:', itemId);
      return res.status(200).send('Ignored');
    }

    // Idempotency check - don't process already finalized items
    if (
      item.status === PayrollStatus.COMPLETED ||
      item.status === PayrollStatus.FAILED
    ) {
      console.log(`Item ${itemId} already finalized (${item.status})`);
      return res.status(200).send('Already processed');
    }

    // Update status based on event type
    if (
      eventType === 'SUCCESSFUL_DISBURSEMENT' ||
      eventData.status === 'SUCCESS'
    ) {
      await PayrollItemModel.updateStatus(
        itemId,
        PayrollStatus.COMPLETED,
        transactionReference
      );
      console.log(`✅ Payroll item ${itemId} COMPLETED`);
    } else if (
      eventType === 'FAILED_DISBURSEMENT' ||
      eventType === 'REVERSED_DISBURSEMENT' ||
      eventData.status === 'FAILED'
    ) {
      await PayrollItemModel.updateStatus(
        itemId,
        PayrollStatus.FAILED,
        transactionReference,
        description
      );
      console.log(`Payroll item ${itemId} FAILED`);
    } else {
      console.log(`Unhandled Monnify eventType: ${eventType}`);
    }

    // Update overall payroll stats
    await updatePayrollStats(payrollId);

    return res.status(200).send('OK');

} catch (error: any) {
console.error('Monnify webhook error:', error.message);
return res.status(200).send('OK'); // Always return 200 to prevent retries
}
});

export default router;

async function updatePayrollStats(payrollId: number) {
const items = await PayrollItemModel.findByPayrollId(payrollId);

const completed = items.filter(
(i) => i.status === PayrollStatus.COMPLETED
).length;

const failed = items.filter((i) => i.status === PayrollStatus.FAILED).length;

let status = PayrollStatus.PROCESSING;

if (completed === items.length) {
status = PayrollStatus.COMPLETED;
} else if (failed === items.length) {
status = PayrollStatus.FAILED;
} else if (completed > 0) {
status = PayrollStatus.PARTIALLY_COMPLETED;
}

await PayrollModel.updateStatus(payrollId, status, completed, failed);
}

Key webhook implementation details:

Signature verification: The verifySignature function validates that webhooks actually come from Monnify.
Idempotency: The handler checks if an item is already finalized before processing.
Always return 200: Even on errors, return 200 to prevent Monnify from retrying indefinitely.
Reference parsing: Our reference format PAYROLL_{payrollId}_{itemId} lets us identify which payment item to update.

Wiring Up Routes

Employee Routes

We’ll start by defining routes for employee management. These routes expose CRUD operations for employees and simply delegate the actual logic to the EmployeeController.

Create the file src/routes/employee.routes.ts:

import { Router } from 'express';
import { EmployeeController } from '../controllers/employee.controller';

const router = Router();

router.post('/', EmployeeController.createEmployee);
router.get('/', EmployeeController.getAllEmployees);
router.get('/:id', EmployeeController.getEmployeeById);
router.put('/:id', EmployeeController.updateEmployee);
router.delete('/:id', EmployeeController.deleteEmployee);

export default router;

What this gives us:

A clean /api/employees entry point for all employee-related operations
Clear separation between routing (URLs) and business logic (controllers)
A predictable REST structure that’s easy to extend later

Payroll Routes

Next, we define routes for payroll operations. Payroll is more complex than employees, so this router exposes endpoints for creation, processing, reconciliation, authorization, and monitoring.

Create the file src/routes/payroll.routes.ts:

import { Router } from 'express';
import { PayrollController } from '../controllers/payroll.controller';

const router = Router();

router.post('/', PayrollController.createPayroll);
router.get('/', PayrollController.getAllPayrolls);
router.get('/:id', PayrollController.getPayrollById);
router.post('/:id/process', PayrollController.processPayroll);
router.post('/batch/authorize', PayrollController.authorizeBulkTransfer);
router.get('/:id/status', PayrollController.getPayrollStatus);
router.get(
  '/transaction/:reference/status',
  PayrollController.checkTransactionStatus
);
router.get('/account/balance', PayrollController.getAccountBalance);
router.post('/:id/reconcile', PayrollController.reconcilePayroll);

export default router;

What’s happening here:

Each route maps directly to a well-defined payroll operation
Long-running or sensitive actions (processing, reconciliation, authorization) are clearly separated
Monitoring and operational endpoints (status, transaction lookup, balance checks) are first-class citizens

Main Application Entry Point

With all routes defined, we now bring everything together in the main application file. This is where we configure middleware, register routes, and start the server.

Create the file src/index.ts:

import express, { Application, Request, Response } from 'express';
import cors from 'cors';
import helmet from 'helmet';
import dotenv from 'dotenv';
import path from 'path';
import { pool } from './config/database';
import employeeRoutes from './routes/employee.routes';
import payrollRoutes from './routes/payroll.routes';
import monnifyWebhookRoutes from './routes/monnify.webhook';

dotenv.config();

const app: Application = express();
const PORT = process.env.PORT || 3008;

// Middleware
app.use(
  helmet({
    contentSecurityPolicy: false,
  })
);
app.use(
  cors({
    origin: '*',
    methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
    allowedHeaders: ['Content-Type', 'Authorization'],
  })
);
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Health check endpoint
app.get('/health', async (req: Request, res: Response) => {
  try {
    await pool.query('SELECT 1');
    res.json({ status: 'healthy', database: 'connected' });
  } catch (error) {
    res.status(500).json({ status: 'unhealthy', database: 'disconnected' });
  }
});

// Routes
app.use('/api/employees', employeeRoutes);
app.use('/api/payrolls', payrollRoutes);
app.use('/api', monnifyWebhookRoutes);

// 404 handler
app.use((req: Request, res: Response) => {
  res.status(404).json({ error: 'Route not found' });
});

// Error handler
app.use((err: any, req: Request, res: Response, next: any) => {
  console.error('Error:', err);
  res.status(err.status || 500).json({
    error: err.message || 'Internal server error',
  });
});

app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
  console.log(`Environment: ${process.env.NODE_ENV || 'development'}`);
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  console.log('SIGTERM signal received: closing HTTP server');
  await pool.end();
  process.exit(0);
});

process.on('SIGINT', async () => {
  console.log('SIGINT signal received: closing HTTP server');
  await pool.end();
  process.exit(0);
});

Testing the System

Now let's test the complete payroll flow.

Start the application:

docker-compose up -d
npm run dev

Create employees:

curl -X POST http://localhost:3008/api/employees \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john.doe@company.com",
    "salary": 50000,
    "account_number": "0123456789",
    "bank_code": "058",
    "bank_name": "GTBank"
  }'

Create a few more employees with different salaries to see how it’s handled.

Create a payroll:

curl -X POST http://localhost:3008/api/payrolls \
  -H "Content-Type: application/json" \
  -d '{
    "payroll_period": "2024-12"
  }'

This creates a payroll with all active employees.

Process the payroll:

curl -X POST http://localhost:3008/api/payrolls/1/process

This queues the payroll for background processing. The system will:

Create a bulk transfer request to Monnify
Update each payroll item with a transaction reference
Wait for webhooks to update final status

Authorize the bulk transfer (if OTP is required):

After processing, Monnify sends an OTP to your registered email. Use it to authorize:

curl -X POST http://localhost:3008/api/payrolls/batch/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "BATCH_1702123456789",
    "authorizationCode": "123456",
    "payrollId": 1
  }'

Check the payroll status:

curl http://localhost:3008/api/payrolls/1/status

This returns detailed status including a summary of completed, failed, and pending items.

Now, reconcile if needed – if webhooks were missed or you need to sync status:

curl -X POST http://localhost:3008/api/payrolls/1/reconcile

Setting Up Webhooks for Production

For Monnify to send webhooks to your local development environment, you'll need to expose your local server. You can use ngrok:

ngrok http 3008

Then configure the webhook URL in your Monnify dashboard:

https://your-ngrok-url.ngrok.io/api/monnify/webhook

For production, use your actual server URL and ensure HTTPS is enabled.

Then when transactions are successful it will be revealed on the monnify dashboard as well as the transactions that failed.

Conclusion

You've built a complete payroll system that:

Manages employees with their bank account details
Creates payroll batches with automatic amount calculation
Processes bulk payments using Monnify's disbursement API
Uses background jobs to prevent request timeouts
Handles webhooks for real-time status updates
Supports reconciliation to ensure data consistency

Key Takeaways

Background jobs are essential: Processing payments synchronously would timeout for large payrolls. Bull and Redis provide reliable async processing.
Idempotency matters: Both the webhook handler and reconciliation process check current status before updating, preventing duplicate processing.
Bulk transfers save time: Monnify's batch API lets you process hundreds of payments with a single OTP authorization.
Status tracking is critical: The system tracks status at both the payroll and individual item level, making it easy to identify and handle failures.
Reconciliation is your safety net: When webhooks fail or get delayed, the reconciliation endpoint ensures your database stays in sync with actual payment status.

References:

Monnify Docs

David Aniebo - freeCodeCamp.org

How to Design APIs for AI Agents

Table Of Contents

Prerequisites

Why “Good Enough for Devs” Is Not Good Enough for Agents

Principle 1: Deterministic Behavior

Prefer Explicit State Over Hidden Magic

Make Writes Safe: Idempotency and Intent Keys

Pagination and Sorting: One Pattern, Everywhere

Timeouts, Partial Success, and Async Work

Principle 2: Strong Schemas

Treat OpenAPI as a Contract, Not a Souvenir

Describe Intent in Natural Language, Precisely

Examples Are Part of the Contract

JSON Schema Strictness Helps Tool-Calling Stacks

Name Things Consistently

Principle 3: Guardrails at the API Boundary

Authorization Should Be Narrow and Explicit

Validate Hard, Fail Loud and Structured

Separate “Read the World” from “Change the World”

Observability is a Product Feature

Patterns That Bridge APIs and Agent Runtimes

Workflow Documentation: Sequences, Not Just Endpoints

Hypermedia and “Next Steps”

Tool-Oriented Surfaces (For Example, MCP)

Metadata for Discovery (llms.txt and Friends)

A Practical Before/After

Weak Pattern (Agent-hostile)

Stronger Pattern (Agent-friendly)

Checklist: Is Your API Agent-Ready?

Conclusion

A Developer’s Guide to Lazy Loading in React and Next.js

Table of Contents

What is Lazy Loading?

Prerequisites

How to Use React.lazy for Code Splitting

My App

How to Use Suspense with React.lazy

My App

How to Handle Errors with Error Boundaries

How to Use next/dynamic in Next.js

Custom Loading UI

Disable Server-Side Rendering

Load on Demand

Named Exports

Using Suspense with next/dynamic

React.lazy vs next/dynamic: When to Use Each

When to Use React.lazy

When to Use next/dynamic

Real-World Examples

Example 1: Route-Based Code Splitting in React

Example 2: Lazy Loading a Heavy Chart Library in Next.js

Analytics

Example 3: Lazy Loading a Modal

Example 4: Lazy Loading External Libraries

Conclusion

How to Share Components Between Server and Client in NextJS

Table of Contents

What are Server and Client Components?

Prerequisites

How to Pass Data from Server to Client via Props

{post.title}

How to Pass Server Components as Children to Client Components

What Props Are Allowed Between Server and Client

Allowed Types

Not Allowed

Passing Server Actions as props

How to Share Data with Context and React.cache

Settings for {user.name}

How to Use Third-Party Components in Both Environments

Gallery

How to Prevent Environment Poisoning with server-only and client-only

Real-World Examples

Example 1: Layout with Shared Server and Client Pieces

Example 2: Product Page with Server Data and Client Add-to-Cart

{product.name}

Example 3: Theme Provider Wrapping Server Content

Example 4: Shared Utility Without Directives

Conclusion

How to Build Real-Time Update Systems with MQTT and Express.js

Metadata for Discovery (`llms.txt` and Friends)

How to Use `React.lazy` for Code Splitting

How to Use `Suspense` with `React.lazy`

How to Use `next/dynamic` in Next.js

`React.lazy` vs `next/dynamic`: When to Use Each

When to Use `React.lazy`

When to `Use next/dynamic`

What `QueryProvider` actually does