DEV Community: Ado Daniel Nj

How I Built the Matchmaking Engine Behind Beta Gamer

Ado Daniel Nj — Sun, 05 Jul 2026 12:26:34 +0000

A technical deep dive into the nested group matchmaking engine, bot injection system, and game state manager powering Beta Gamer, a multi-tenant Games as a Service API built solo from Cameroon.

This is the technical post I promised in the previous one.

If you haven't read the story behind Beta Gamer yet, the short version is: I built a Games as a Service API that lets any developer embed real-time multiplayer games into their product with a single integration. 10 games. Multi-tenant. WebSocket-based. Built solo from Scratch.

This post is about three specific engineering problems I had to solve that I hadn't seen clearly documented anywhere else.

Problem 1: A Matchmaking Engine That Thinks in Nested Groups

Most matchmaking systems think in players. Two players join a queue, their ratings are close enough, they get matched. Simple.

That works for 1v1. It falls apart the moment you need group or team games like battle royale, or anything where the structure of a match is more complex than two individuals facing each other.

I needed a different mental model entirely.

The structure I landed on is a nested array:

[
  [player1, player2],   // group 1
  [player3, player4],   // group 2
  [player5],            // group 3
]

The outer array is the match. The inner arrays are the groups. The engine doesn't care how many groups there are or how many players are in each. It just reads the structure and executes.

This means:

1v1 Chess is [[p1], [p2]]
4-player Ludo is [[p1], [p2], [p3], [p4]]
2v2 team game is [[p1, p2], [p3, p4]]
2v2v2 three-way team game is [[p1, p2], [p3, p4], [p5, p6]]
A game with 100 solo players is 100 arrays of one player each

One data structure. Zero special cases. Every game type falls out of configuration, not separate codepaths.

Each game defines its own rules via a config:

interface MatchConfig {
  groupMinSize: number;   // minimum players per group
  groupMaxSize: number;   // maximum players per group
  minGroups: number;      // minimum groups needed to start a match
  maxGroups: number;      // maximum groups per match
  groupWaitMs: number;    // how long to wait for a group to fill
  lobbyWaitMs: number;    // how long to wait for the pool to fill
}

A fixed-size game sets groupMinSize === groupMaxSize. A flexible game sets them differently and the match starts when the minimum is met.

Two-Stage Pipeline

The matchmaker runs in two stages.

Stage 1 - Queue to Group. Players join a queue. The matchmaker collects them into forming groups. When a group hits groupMaxSize it promotes immediately. When groupWaitMs fires, any group at or above groupMinSize promotes. Groups below minimum wait or dissolve.

Player joins queue
       |
Assigned to forming group
       |
Group hits maxSize? -> Promote immediately
       |
Timer fires -> group >= minSize? -> Promote
                               -> below minSize? -> Wait or dissolve

Stage 2 - Group to Match. Promoted groups enter a pool. When the pool reaches maxGroups, the match fires immediately. When lobbyWaitMs fires, if the pool has at least minGroups, the match fires with whatever is available.

Group promoted -> enters pool
                      |
pool.length >= maxGroups? -> Fire match immediately
                      |
lobbyWaitMs fires -> pool.length >= minGroups? -> Fire match
                                              -> Wait

This two-stage design is what makes flexible group sizes possible. A lobby of 4 that only fills 3 does not cancel. It checks against groupMinSize and proceeds if the threshold is met.

One Critical Boundary

The matchmaker answers exactly one question: who plays against whom?

It assembles Array<Array<Player>> and hands it to the game engine. What happens inside the match, turn order, whether a whole group moves together or players alternate individually, how simultaneous moves are resolved, that is the game engine's responsibility entirely. The matchmaker does not know and does not need to know.

This separation is intentional. A Chess engine and a Ludo engine have completely different turn structures. The matchmaker serving both of them should be agnostic to both.

Tenant (Developers) Hooks

Tenants on hosted matchmaking can bypass either stage:

submitGroup(game, group, config) - skip the queue, inject a pre-formed group directly into the pool
startMatch(game, groups, config) - skip the pool, force a match to start immediately

// Tenant submits a pre-formed group of their own players
matchmaker.submitGroup('chess', {
  id: 'group-abc',
  players: [{ playerId: 'u1', username: 'Alice', ... }],
  createdAt: Date.now(),
}, chessConfig);

// Tenant forces two groups into a match immediately
matchmaker.startMatch('chess', [group1, group2], chessConfig);

The matchmaker does not care how the groups were formed on the tenant's side. It just executes.

Problem 2: Injecting Bots Into Live WebSocket Sessions via REST

This one took me longer than I expected.

The problem: a tenant has a hosted session in a pending state. Not enough real players are online. They want to fill the empty slots with bots. They call a REST endpoint to trigger this. But the game room might already exist as a live in-memory WebSocket session on the server.

A REST handler and a WebSocket server are two different runtime contexts. The REST handler can write to the database. It cannot directly reach into the socket server and mutate a live room.

The solution is an internal event bus.

// REST endpoint - bot injection handler
if (room) {
  socketEventbus.dispatch('bot:inject', {
    game,
    roomId: room.id,
    botPlayer: {
      id:         botPlayer.id,
      socketId:   '',
      username:   botPlayer.displayName,
      isBot:      true,
      difficulty: botPlayer.difficulty,
    },
  });
}

// Socket server - listens for injection events
socketEventbus.on('bot:inject', (payload: BotInjectPayload) => {
  const room = multiGameStateManager.getRoom(payload.roomId);
  if (!room) return;
  room.players.push({
    id:         payload.botPlayer.id,
    socketId:   payload.botPlayer.socketId,
    username:   payload.botPlayer.username,
    isBot:      true,
    difficulty: payload.botPlayer.difficulty,
  });
  // notify existing players that a bot joined
});

The REST layer and the WebSocket layer are fully decoupled. Neither knows about the other's internals. The event bus is the only bridge.

One detail that matters: if the room does not exist in memory yet, the session is pending and no one has connected, the endpoint only updates the database. When players connect and the room initialises, it reads the updated player list from the database and the bot is already there. No injection event needed.

Tenants can also bring their own bots. If the request body contains a playerId, that specific bot is used. If not, the platform picks from the tenant's configured bot pool automatically.

Problem 3: Game State That Survives Everything

Reconnection

When a player disconnects, the game does not end. The room switches to paused and a 60-second reconnection window opens.

handleDisconnect(socketId: string, reconnectWindow = 60_000): void {
  // pause room, start countdown
  if (room.state === 'playing') room.state = 'paused';
  const timeout = setTimeout(() => this.handlePlayerQuit(playerId), reconnectWindow);
  this.disconnectedPlayers.set(playerId, { roomId, timeout });
}

handleReconnect(playerId: string, newSocketId: string): boolean {
  // clear countdown, remap socket, resume game
  clearTimeout(disconnectData.timeout);
  player.socketId = newSocketId;
  if (room.state === 'paused') room.state = 'playing';
  return true;
}

If the window expires, the player is treated as having quit. With remaining players, the game continues and the turn index adjusts. With one player left, that player wins. With zero, the room is deleted.

Singleton Across Hot Reloads

Next.js re-evaluates modules on every file change in development. A regular module-level singleton gets destroyed on every hot reload and all active rooms are lost.

The fix is attaching the singleton to globalThis:

const g = globalThis as any;
if (!g.__multiGameStateManager) {
  g.__multiGameStateManager = new MultiGameStateManager();
}
export const multiGameStateManager: MultiGameStateManager = g.__multiGameStateManager;

First load creates the instance. Every subsequent reload finds it already there and reuses it. Rooms survive hot reloads completely.

AFK Timer Cleanup

Every room runs an AFK timer. If a player stalls their turn, they get forfeited. But when a game ends normally, if the AFK timer is not cleared, it fires later into a room that no longer exists.

endGame(roomId: string, winner?: string): void {
  room.state = 'finished';
  room.winner = winner;
  clearAfkTimer(roomId);  // always clear before deleting
  setTimeout(() => this.deleteRoom(roomId), 5_000);
}

Clear the timer first. Then schedule the cleanup. Order matters.

What I Haven't Built Yet

Everything above is turn-based. One player or group acts, then the next. The server is the authority on state because moves are sequential.

Simultaneous move games, football, shooters, anything where every player acts at the same time, are a different problem entirely. You need a tick-based system that collects moves within a window, validates each against the same snapshot of game state, resolves conflicts, then broadcasts the result atomically.

The nested group structure already supports it. [[p1, p2], [p3, p4]] works for a 2v2 shooter exactly as it does for a 2v2 turn-based game. The matchmaker does not change. The game engine does.

That is the next frontier. When I solve it, there will be another post.

Beta Gamer docs: https://beta-gamer.onrender.com/docs/overview
npm: @beta-gamer/react and @beta-gamer/react-native

I Almost Didn't Build Beta Gamer

Ado Daniel Nj — Sun, 05 Jul 2026 01:02:22 +0000

The real story behind building a multiplayer game API from Cameroon - the failed 3D game, the financial pressure, the nights I almost quit, and why I kept going anyway.

I wanted to build a game like Free Fire.

Not an API. Not a platform. Not infrastructure. A real game. Something with players running, shooting, the kind of chaos that makes people forget they have responsibilities.

I watched tutorials on Three.js and got started. Built an object class for each game component, hooked everything into a central render method, watched a 3D world appear on my screen from nothing. That feeling, I don't think I'll ever forget it. 🎮

Then the game started scaling.

Player controllers. Animation states. Interactions. Physics. Collision detection at speed. The tutorials had gotten me through the door. But scaling is where tutorials stop and real engineering begins. It became clear fast that I didn't have the architecture for what I was trying to build. I had to stop, step back, and go back to vanilla JS and 2D games.

That wasn't failure. That was education. I learned more about how 3D games actually work from crashing into those walls than I ever could have from just following along. I understand 3D game architecture better now because of that breakdown.

But it forced a question. If I can't build the game I want yet, while learning ... what can I build that actually matters?

The Problem I Kept Seeing

Every time I looked at apps, betting platforms, fintech products, social apps, I kept asking the same question. Why does adding a multiplayer game to your product require hiring an entire game engineering team? Why is that barrier so high?

A game company wants Ludo. A fintech app, Duolingo wants Chess as a loading interface. A social platform wants something to keep users engaged. None of them want to learn WebSocket architecture, matchmaking theory, or game state synchronization. They just want the game.

Nobody had built the bridge.

So I decided to. A Games as a Service API. One integration and any developer can embed real-time multiplayer games into their product. Under their brand. With their rules. Without touching a single line of game logic.

I called it Beta Gamer. And I started looking for people to build it with me.

The Part Nobody Talks About

I found nobody.

Not because people weren't interested. Because I couldn't pay them. And you cannot ask people to dedicate serious time to your vision without compensating them. That's just reality.

See, the thing about being an African freelance developer is that your income is your oxygen. When a freelance project comes in, you eat. When it doesn't, you don't. No income means no internet. No internet means no development. The loop is vicious and most people outside of it don't understand how completely it can shut you down. 🥀🥀

There were periods I couldn't work on Beta Gamer at all. Not because I didn't want to. Because I had to survive first.

There were nights I thought, should I just ship it with 2 games? Get something out there, prove the concept, add more later? But I knew what that meant. The matchmaking engine I was building was designed to scale. Shipping early and upgrading it later would have been hell. The architecture would have fought me every step of the way.

So I made a decision that cost me time but saved me from a worse problem. I would build it right the first time, even if it took longer.

That decision required patience I sometimes didn't have. Power cuts in the middle of sessions. Mobile data as my only connection. Academic deadlines running parallel to a platform that needed my full attention. Supabase requiring me to be online just to test authentication flows, or searching a bug,

which sounds like a small thing until your data budget runs out at 11pm and you're mid-feature.

I won't pretend it didn't get to me. It did.

But here's the thing about building something genuinely hard. The difficulty becomes the proof. Every impossible thing you solve gets baked into the product permanently. It stays there, working, long after the stress of building it is forgotten.

What Kept Me Going

Honestly? The problems. 🔥

Every new thing I added that seemed impossible before I tried it. Like figuring out how to let external tenants inject bots into live WebSocket sessions through an API endpoint. Not hardcoded bots. Not internal bots. Bots controlled from outside the system entirely, by companies integrating Beta Gamer into their own products. I solved that and sat back and just stared at the screen.

Or designing the group matchmaking engine.

Most platforms build 1v1 first and bolt group support on later. That's why their matchmaking systems become a mess. I started with the general solution and let everything else follow.

The structure is Group[x] vs Group[y], where x and y are player counts that fall within a min and max defined per game. A game with fixed sizes just sets min and max equal. A game with flexible sizes sets them differently and the match starts when the minimum is met. 1v1 Chess is Group[1] vs Group[1]. Four player Ludo is four groups of one. A flexible team game is Group[2-4] vs Group[2-4].

One engine. One set of rules. Every game type falls out of configuration, not separate code. Reusable. Modular. The game defines its own rules and the engine just executes them.

And if tenants want to manage their own matchmaking logic from outside the system? They can do that too.

Then there's the thinking I haven't fully built yet but can't stop thinking about. Turn-based games, Chess, Ludo, Checkers, one player moves then the other. Clean. But football, shooting games, everyone moves simultaneously. Different timing model. Different conflict resolution. Different architecture entirely.

That thought kept me at the keyboard on nights I probably should have slept.

Where Beta Gamer Is Now

10 games live. Chess, Ludo, 8-Ball Pool, Archery, Piano Tiles, Connect 4, Check (Chkobe, an African card game similar to Uno), and more. Multi-tenant architecture with isolated matchmaking per partner. Hosted matchmaking mode where tenants control their own queues. Bots injectable via API endpoint. Flexible group sizes with configurable min and max per game.

The SDK ships three things separately. UI components, socket hooks, and game hooks. Tenants can use the default UI, replace it entirely, or just take the hooks and build whatever interface they want on top. You will never know it is Beta Gamer running underneath unless someone tells you. That is the point.

React and React Native packages are live on npm: @beta-gamer/react and @beta-gamer/react-native.

Built alone. In roughly 5 to 6 months of real working time, stretched across a longer calendar of power cuts, connectivity drops, financial pressure, and a full academic load that ended with a BSc in Computer Science from the University of Buea.

About 80% done. Not because I ran out of ideas. Because I refuse to ship something until it is right.

What I Hope For

I am not writing this for sympathy. I am writing it because I think there are developers reading this who are building something real, under real constraints, with no safety net, and they need to know that the building is worth it even before the reward shows up.

The next post will be the technical one. How the group engine actually works. How bot injection via API is architected. How I think about simultaneous move resolution for real-time games.

But I wanted to tell this part first.

Because the code does not exist without the person who wrote it. And the person is never just the code. 🏗️

Beta Gamer docs (Demo): https://beta-gamer.onrender.com/docs/overview
npm: @beta-gamer/react and @beta-gamer/react-native

Archive: A Narrative Investigation Game About Curating Human History

Ado Daniel Nj — Mon, 22 Jun 2026 03:23:20 +0000

This is a submission for the June Solstice Game Jam

Archive — The Last Historian of Humanity

What if history wasn't discovered... but selected?

History is often treated as something permanent—something waiting to be uncovered.

Archive asks a different question:

What happens when humanity loses the ability to tell the difference between truth, memory, and fabrication?

You play as the final Archivist after the collapse of civilization. Humanity's knowledge survives, but it has become fragmented, contradictory, and corrupted. Your responsibility is no longer to preserve everything—you must decide what deserves to be remembered.

Every decision changes the civilization that will inherit your version of history.

What I Built

Archive is a narrative investigation game where players reconstruct humanity's past by examining historical memories, investigating evidence, resolving contradictions, and deciding what becomes official history.

Unlike traditional mystery games, there is rarely a perfect answer.

Instead, every investigation asks questions such as:

Should conflicting memories be preserved?
Is stability more important than truth?
Can compassion justify rewriting history?
If no one can verify the past, what does "truth" even mean?

Each recovered memory is presented as a historical article. Players investigate through classified documents, research papers, witness testimonies, forensic reports, personal journals, and government archives before making irreversible decisions.

Those decisions reshape the civilization that follows.

By the end of the game, players don't simply receive a score—they discover the kind of society they created.

Why It Fits the Theme

The June Solstice represents a turning point.

It is the moment when one season gives way to another, when light begins yielding to darkness, or darkness begins yielding to light.

Archive explores a similar transition.

Not between seasons...

but between certainty and uncertainty.

Human civilization reaches a moment where objective history begins to disappear. Every decision the player makes determines what survives that transition.

The game is ultimately about how societies evolve through the stories they choose to preserve.

Core Gameplay

Players:

Recover fragmented historical memories.
Explore multiple investigation paths.
Analyze evidence with varying reliability and bias.
Resolve contradictions between historical accounts.
Decide which memories become part of civilization's official record.
Shape the philosophical identity of humanity's future.

No two playthroughs necessarily create the same civilization.

Video Demo

the-last-memory-of-earth.vercel.app

The video demonstrates:

Archive exploration
Investigation system
Evidence paths
Decision making
Civilization evaluation
Multiple possible historical outcomes.

Sorry about the low vibe during that, i was extremely tired 😅.

Code

GitHub Repository:

(https://github.com/acetennyson/The-Last-Memory-of-Earth/)

Test Live

Public domain:

(https://the-last-memory-of-earth.vercel.app/)

How I Built It

Archive was designed around one core philosophy:

History is not merely remembered, it is curated.

Rather than treating lore as optional background reading, every piece of narrative content exists as gameplay.

The project includes systems for:

branching investigations
layered evidence
contradictory historical records
civilization philosophy
procedural ending evaluation
markdown-powered historical articles
dynamic narrative progression

The game is built using React, TypeScript, Capacitor, and a fully data-driven content architecture that allows new story arcs, memories, investigations, and evidence to be added without modifying gameplay systems.

One of the biggest design challenges was avoiding "good" and "bad" endings.

Instead, the game evaluates the civilization created by the player's accumulated decisions across values such as Truth, Freedom, Compassion, Progress, Power, and Legacy.

The result is an ending that reflects who humanity became, rather than simply whether the player succeeded.

Prize Category

Best Ode to Alan Turing

Archive is deeply inspired by questions surrounding computation, information, and artificial intelligence.

As the Archive evolves, it begins connecting information in ways humans never anticipated, raising questions similar to those explored by Alan Turing:

Can a machine create knowledge?
Can intelligence emerge from information alone?
When does computation become interpretation?

Rather than focusing on AI as a tool, the game explores AI as a historical force capable of reshaping civilization itself.

Best Google AI Usage

Google AI played an important role throughout development.

It was used as a creative collaborator for:

worldbuilding
historical consistency
narrative iteration
investigation design
story arc refinement
gameplay balancing
technical architecture discussions

Rather than generating finished content automatically, Google AI became part of the iterative design process, helping refine ideas while preserving a consistent narrative vision.

Final Thoughts

Archive isn't about winning.

It isn't even about discovering the truth.

It's about confronting one uncomfortable possibility:

History never remembers everything.

Only what someone chose to preserve.

The Weekend I Finally Finished 17 Projects

Ado Daniel Nj — Fri, 12 Jun 2026 00:09:11 +0000

You know that feeling when you open a folder you haven't touched in months and find... yourself?

Not metaphorically. I mean literally — old projects you don't even remember writing, with code that's somehow good? And you're sitting there like, "wait, I wrote this?"

That was my Saturday.

The Mess

I decided it was time. My portfolio was a ghost town. My GitHub was full of half-finished dreams. You know the drill — you start a project, get 80% there, then a shinier thing comes along and suddenly it's gathering dust for a year.

I had 17 of those.

LIS — An AI tutoring app for Cameroonian students. Works offline. Has a Learning DNA that adapts to how you study. I literally submitted this for a social impact prize and then... just left it there.
Mbende Stay — A booking platform with mobile money payments. Fully functional. Zero visitors.
"418 I'm a Teapot" — A game where you play as a teapot that can never win and an AI roasts you every time you fail. I'm not kidding.
elementTouch — A JavaScript library I built from scratch. Drag and drop. Typewriter effects, and more. A whole code editor. Just... sitting there.

And I'm looking at all of this thinking: bro, you really just built things and then forgot to tell anyone?

So I made a decision: polish them all, put them in my portfolio, and actually show the work.

First step: build an admin import tool. One click, seed 17 projects into Firestore. Felt like a genius.

Then the Universe Laughed

npm run build

ReferenceError: location is not defined
    at v (.next/server/app/admin/blog/new/page.js:1:11128)
    at y (.next/server/app/admin/projects/import/page.js:1:16875)
    at y (.next/server/app/admin/projects/new/page.js:1:8262)
    at j (.next/server/app/admin/resumes/new/page.js:1:4056)

Four pages. Dead. And I have no idea where location is coming from.

You ever debug a Firebase + Next.js app and feel like you're chasing a ghost? Because I was definitely chasing a ghost.

Turns out, Firebase's SDK references location (as in window.location) at the module level. Not inside a function you call. At import time. So when Next.js tries to server-render your admin page, Node.js is like "what's location? never heard of her."

The fix?

import dynamic from "next/dynamic"
export default dynamic(() => import("./page.client"), { ssr: false })

I wrapped each page in next/dynamic with ssr: false. Basically told Next.js: "Don't even look at this page on the server. Not once. Not ever. Just send the JS and let the browser figure it out."

Moved all the actual code to page.client.tsx. Build passed. I felt like a god for approximately 12 minutes.

The Betrayal

Then I looked at my blog.

You see, my blog posts are stored in Firestore as HTML. And somewhere along the way, I'd written them with beautiful Tailwind dark mode classes:

<div class="not-dark:bg-white dark:bg-gray-900 dark:shadow-lg">

Here's the problem: Tailwind v4's JIT compiler has never heard of your database.

It scans your source files — your app/, your components/, your lib/. It does NOT make a Firebase query to find class names.

So dark:bg-gray-900 in a blog post? Never compiled. It renders as plain text with zero styles. My "beautiful blog content" was just... floating in the void. No background. No shadow. Nothing.

I sat there staring at the screen feeling personally betrayed by a CSS framework.

But hey, I fixed it:

function prepareHtml(html: string): string {
  return html.replace(/\b(?:not-)?dark:[^\s"'>]+/g, "").trim()
}

Strip the prefixes. Then override everything with CSS variables:

.blog-content .text-gray-900 { color: inherit !important; }
.blog-content .bg-white, .blog-content .bg-gray-900 { background: transparent !important; }
.blog-content .shadow-md, .blog-content .shadow-lg { box-shadow: none !important; }

Now every hardcoded class respects the theme. Dark mode, light mode, it just works. The blog content is finally alive.

Then There Were 17

So now I've got 17 projects in my portfolio. On one page. One. Grid. Screen. You see the problem.

I needed pagination. Not the boring kind — something that actually looks good:

Chevrons that bounce when you hover
Page numbers with the accent color on active
Ellipsis that only show when there's actually a gap
A quiet little "Page X of Y · N projects" at the bottom

The button logic nearly broke me. You try handling "first page, last page, exactly 5 pages, exactly 6 pages, ellipsis-or-no-ellipsis" without your brain melting:

const pages = useMemo(() => {
  const p: (number | "...")[] = []
  if (totalPages <= 5) {
    for (let i = 0; i < totalPages; i++) p.push(i)
  } else {
    p.push(0)
    if (safePage > 2) p.push("...")
    // ... more edge cases
  }
  return p
}, [safePage, totalPages])

It works. It's clean. I'm proud of it.

What I Actually Learned

1. You probably have better code than you think

Open that old project. The one you're embarrassed about. I bet it's not as bad as you remember. We're all way too hard on ourselves.

2. Admin pages don't need SSR

If your page is behind a login wall, there's zero SEO value in server-rendering it. Just use ssr: false and save yourself the headache. Your admin panel will survive without being indexed by Google.

3. Tailwind v4 JIT is amazing until your content is dynamic

If your HTML lives in a database, plan ahead. CSS variables are your escape hatch. Hardcoded utility classes in data strings will come back to haunt you.

4. A portfolio is never done

Every time I thought "okay this is final," I found another project, another bug, another thing to improve. That's not failure. That's just what building in public looks like.

What's Left

elementTouch still has 2 unfinished tasks out of 7. I'll get to them.

And there's a missing admin/blog/edit/[id] page that keeps crashing the build. Just one day.

Anyway, that's my weekend. What's the most embarrassing bug you've fought with Next.js + Firebase? Drop it below so I don't feel alone.

My Portfolio

We Built a “Stripe for African Mobile Money” — Then Discovered Why It Couldn’t Exist

Ado Daniel Nj — Thu, 16 Apr 2026 09:31:42 +0000

As developers, we love hard problems.

So we set out to solve one that almost every African developer has faced:

“Why do I need a different integration for every mobile money provider in every country?”

Our answer was a project we called UAPL (Unified African Payment Layer) — a single API that could sit on top of providers like Campay, Flutterwave, MTN MoMo, Orange Money, Airtel Money, and others.

The goal?

Give developers a Stripe-like experience for mobile money across Africa.

Technically, we nailed it.

Legally, we walked into a wall we didn’t know existed.

This post is about the architecture we built, the performance we achieved, the failures we discovered before launch, and why we had to pivot the entire idea.

🧠 The Technical Vision

UAPL was designed as an orchestration layer with:

Adapter pattern for each provider
A Unified Payment Object (UPO) to normalize all APIs
Redis-backed transaction ledger for USSD/async flows
WebSocket events for real-time transaction updates
Automatic provider failover (MTN → Orange if one fails)
A clean SDK so devs never see provider differences

From a systems design perspective, it was beautiful.

You could write:

uapl.pay({
  amount: 5000,
  currency: "XAF",
  phone: "677000000"
})

And UAPL would figure out the provider, handle retries, normalize responses, and notify your app in real time.

We load-tested the orchestration layer. It was fast. Stateless. Horizontally scalable. Provider-agnostic. Exactly what African devs need.

💥 The Discovery That Changed Everything

While preparing for real integrations with Banque des États de l'Afrique Centrale (BEAC) zone providers, we went deeper into regulatory documentation and aggregator terms.

And then we saw it.

A sentence that changes everything for fintech builders:

Any entity that routes, orchestrates, settles, or intermediates payments between merchants and licensed providers may be classified as a Payment Service Provider (PSP).

Even if:

You never touch the money
You only pass API calls
You act as “middleware”

Legally, you are in the payment flow.

Which means:

You need PSP licenses
You fall under central bank regulation
Aggregators can block you for “reselling” their infrastructure
Settlement logic makes you a financial intermediary

In CEMAC, this is enforced under Commission Bancaire de l'Afrique Centrale (COBAC) oversight.

We weren’t building a developer tool.

We were accidentally building an unlicensed financial institution.

❌ The Failures We Caught Early

1. Automatic Failover Is Not Allowed

Our proudest feature:

If Campay's MTN API fails → automatically retry with Tranzak's MTN API

Sounds smart. Completely illegal in practice.

Why? Merchants are KYB’d per provider. You can’t reroute their transactions without explicit registration.

2. Settlement Scheduling Makes You a PSP

We planned:

“UAPL pays out to developers on a schedule”

That single sentence legally converts you into a money handler.

Instant PSP classification.

3. Aggregators Can Shut You Down Overnight

Platforms like Flutterwave or Campay can decide you are “reselling” their API as a platform.

They don’t need to argue. They just revoke your keys.

Game over.

4. The Illusion of “One License for Many Countries”

We assumed:

Get a CEMAC license → operate everywhere in the zone

Reality:

Country-level approvals
Telco-level approvals
Data residency considerations
Central bank notifications

A regional license is not a passport. It’s permission to start more paperwork.

🧩 The Big Realization

We thought we were building:

Stripe for African mobile money

But what we needed to build was:

Stripe.js for African mobile money

A critical difference.

One is a regulated payments company.

The other is a developer SDK.

🔁 The Pivot

We redesigned UAPL to be:

A pure SDK and orchestration library
Developers bring their own provider credentials
No routing of funds
No settlement
No payout control
No position in the legal payment chain

Now, that designs UAPL as a software. Not fintech.

And that version is legally unstoppable.

🧭 Lessons for Developers Building in Fintech

Before writing code, answer these:

Who is the regulator in this space?
Does my system decide where money goes?
Does my system delay, batch, or settle funds?
Am I unintentionally “intermediating” transactions?

If yes, you are not building a tool.

You are building a financial institution.

🗣️ Why I’m Sharing This

Because from an engineering standpoint, this was one of the best systems we’ve ever designed.

And it still would have failed.

Not due to bugs.
Not due to scaling.
Not due to product-market fit.

But because we didn’t start with regulatory research.

If you’re a developer building in Africa’s fintech space, learn from this before you spend months building the wrong thing.

Research first. Architect second. Code third.

418: I'm a Teapot

Ado Daniel Nj — Mon, 13 Apr 2026 07:24:53 +0000

This is a submission for the DEV April Fools Challenge

What I Built

418: I'm a Teapot (and You're a Bad Gamer)

A high performance, SEO-optimized, AI integrated gaming platform built solely to ensure the player
never wins.

You control a teapot. You run. You jump. You die. On every death, Gemini analyzes your failure and
adjusts the physics to be slightly more insulting next time. There is no finish line. There never was.

Key features:

Endless Runner — one button to jump. Except it's not always that button.
Rotating Controls — the jump key silently changes every run. The HUD shows last run's key. This is documented nowhere.
Input Gaslighting — every ~10th jump has a 200ms delay. Wall contact permanently degrades your grip. Mash the keyboard and gravity drops to near zero — the teapot floats away.
AI Vibe Check — on every death, your stats (jumps, wall hugs, rage mashes) are sent to Gemini. It returns new physics values and a personalized roast. Gets meaner over time.
Global Loss Leaderboard — powered by Firebase. Tracks deaths, not wins. "You are ranked #3 most pathetic globally."
Fake Patch Notes — v2.4.1 changelog includes "Fixed bug where player could win (unintended)" and "Removed finish line (was causing confusion)."
Fake Loading Tips — "Tip: There is no finish line. There never was."
Broken Controls Page — /controls documents the controls incorrectly. Never acknowledged.
Support Ticket System — after 5 deaths a "Report a Bug" button appears. Submit a complaint, receive HTTP 418 and a Gemini-generated gaslighting response.
Share Your Shame — one click shares your death count and AI roast to X, Facebook, WhatsApp, Telegram, Reddit, or LinkedIn.
418 Redirect — survive 90 seconds and get redirected to /418: {"status": 418, "message": "I'm a Teapot", "reason": "Server is currently brewing. Your victory has been lost in transit."}

Demo

Run here

Code

GitHub repo

How I Built It

Stack:

Next.js 16 — frontend + API routes. The game UI and the AI backend live in the same codebase, deployed as a single container.
Phaser 3 — 2D game engine running in a dynamically imported client component (no SSR). Handles physics, collision, procedural obstacle generation, and all the gaslighting mechanics.
Gemini 1.5 Flash (primary) + Groq / Llama 3.3 70B (fallback) — on every death, player action data is POSTed to /api/judge. The AI returns a JSON payload with new physics values (gravity, speed, jumpForce, mass, drag, delayEvery) and a personalized roast. The prompt explicitly instructs it to get meaner with each death.
Firebase Firestore — global leaderboard. Every death writes a record. Rank is calculated by counting sessions with fewer deaths.
Google Cloud Run — the entire app is Dockerized and deployed as a single container. Because some problems deserve enterprise-grade infrastructure.

The physics are real. jumpForce / mass determines jump height. drag affects mid-air deceleration.
Gemini can increase your mass to make your jumps pathetically short, or drop gravity to 50 so the
teapot floats off screen. The game is genuinely engineered to be bad.

The support ticket endpoint returns HTTP 418 by design. This is not a bug. It is the only honest thing
in the entire codebase.

Prize Category

Best Ode to Larry Masinter, The player character is a teapot. The win condition redirects to a raw
418 JSON response. The support system returns 418. The game is named after RFC 2324. Larry Masinter
wrote a joke in 1998 that has never been removed from the spec. This game is its spiritual successor.
It is completely useless. It took real engineering to make it this bad.

Best Google AI Usage. Gemini is not a hint system or a chatbot, it is a passive-aggressive game
designer that watches you fail and makes the next run worse. It also generates your death roast and
your support ticket rejection. Every interaction with the AI is designed to make you feel worse about
yourself. This is the correct use of AI.

Global Freelancer Sync — an AI-powered command center for freelancers managing clients

Ado Daniel Nj — Mon, 30 Mar 2026 06:05:51 +0000

This is a submission for the Notion MCP Challenge

What I Built

Global Freelancer Sync — an AI-powered command center for freelancers managing clients
across timezones.

As a freelancer in Cameroon (WAT), I work with clients in New York, London, and Tokyo. Every
week I face the same questions: Who should I reach out to right now? Is it a good time to
send this update? What should I even say?

Doing this manually for 8+ clients across 5 timezones is tedious and easy to get wrong. So I
built a system that handles it automatically.

Here's what it does:

Connects to your Notion Clients database and reads each client's timezone, project context, and last update
Shows a live world clock strip — who's available right now, who's sleeping, and how long until each client's window opens
Uses AI (Gemini, Claude, DeepSeek, Groq, HuggingFace with automatic fallback) to draft personalized outreach emails using your project context and sent message history
Lets you review and approve drafts — you stay in control
Auto-sends emails via Gmail when clients enter their active window, even while you sleep
Logs every action to Supabase with a real-time activity feed
Includes a chat assistant that knows your full client state and can answer questions like "Who should I reach out to first today?"

The core philosophy: AI handles the timing and the words. You handle the decisions. Human-in
-the-loop, by design.

Video Demo

adodanielnj.vercel.app

Show us the code

GitHub: https://github.com/acetennyson/global-freelancer-assistant

Live demo: global-freelancer-assistant.vercel.app

Tech stack:

Next.js 15 (App Router)
Notion SDK + MCP TypeScript SDK
Supabase (activity logs, draft history, sent history, Realtime)
Multi-provider AI: Gemini 2.5 Flash → Claude → DeepSeek → Groq → HuggingFace
Nodemailer (Gmail SMTP)
Vercel Cron (every 15 minutes)
Framer Motion + next-themes (light/dark/system)

How I Used Notion MCP

Notion is the single source of truth for everything client-related. The MCP server exposes
three tools that any MCP-compatible AI client (like Claude Desktop) can call:

get_client_local_times
Returns every active client's current local time, availability status, and whether they're
within their send window. Claude can call this to answer "who's available right now?"
without any manual timezone math.

generate_client_outreach
Takes a client_id, checks if the client is in their business hours window, reads their
project context from Notion (Project, Last_Update, Next_Action), generates a personalized
draft using Gemini, and writes it directly back to the AI_Draft column in Notion. The
freelancer sees the draft appear in their dashboard and can approve or edit before sending.

sync_and_draft
A combined tool that fetches the client from Supabase, checks their timezone window,
generates a context-aware draft, and writes it to Notion — all in one call. Designed for
batch workflows where you want to draft for all available clients at once.

What MCP unlocks:
Without MCP, this would be a closed app — useful only through the dashboard. With MCP, any
AI agent can become a timezone-aware outreach assistant. You can tell Claude Desktop: "Draft
updates for all clients who are currently in business hours" and it calls
get_client_local_times, identifies the available ones, then calls generate_client_outreach
for each — writing personalized drafts into Notion for you to review. The AI does the work.
You approve and send.

That's the human-in-the-loop system the challenge asked for.