DEV Community: John Afariogun

The Hidden Physics of AI on Your Own Machine: Inference Engineering, Local-First

John Afariogun — Fri, 17 Jul 2026 16:24:40 +0000

You close your laptop lid on a plane, open a chat window with no wifi bar in sight, and type a question anyway. A moment later, text starts appearing, not from a server farm somewhere over the ocean, but from the silicon six inches from your fingers. No round trip. No data leaving the device. Just your machine, quietly doing the work.

That experience is the promise of local-first AI. And getting there is not a matter of shrinking a cloud service down to fit, it's a completely different physical problem, governed by the same brutal constraints as data-center inference, but with almost none of the data center's luxuries.

For years, the AI industry's center of gravity was training: enormous clusters, oceans of data, model weights forged in facilities the size of small towns. Running the model afterward was treated as an afterthought, something a server rack in the cloud would handle. But a parallel movement has been building quietly, engineers determined to make inference happen entirely on the device in your hand, your bag, or your desk. This is inference engineering turned inward, and it forces you to relearn the discipline under a much stricter budget.

If cloud inference is a symphony performed by a full orchestra in a concert hall with unlimited musicians on call, local-first inference is a single performer playing every part themselves, on an instrument they carry with them, with no stagehands and no backup if a string breaks.

One Machine, No Safety Net

Explore local-first inference and you quickly notice that the tidy three-layer picture of cloud AI – runtime, infrastructure, and tooling – collapses into something much smaller and much more personal.

The Runtime is still there, and it still matters enormously: the code that meets the model where it touches the chip, whether that chip is an Apple silicon GPU, a Snapdragon NPU, or the integrated graphics inside a budget laptop. But the second layer, Infrastructure, effectively disappears. There is no cluster to scale horizontally, no load balancer routing traffic across regions, no fleet of machines standing by. There is exactly one device, with a fixed, unchangeable amount of memory and compute, and it must handle everything itself. If it runs out of headroom, there is no second server to fail over to the request simply doesn't complete.

What remains of the Tooling layer shrinks too, from dashboards monitoring thousands of requests per second down to a single process on a single machine but its job becomes more intimate: figuring out, in real time, exactly how much of this one device's limited resources it's safe to use before everything else the person is doing grinds to a halt.

This is the defining shift of local-first engineering: you're no longer designing for elastic scale. You're designing for a hard, physical ceiling that cannot be raised by throwing more hardware at the problem, because the hardware is whatever the person already owns.

The Economy of a Shared Device

Cloud inference engineers argue over milliseconds of Time to First Token or fractions of a cent per million tokens. Local-first engineers inherit those same trade-offs, but with a new constraint layered on top of all of them: the device isn't dedicated to the model. It's also running someone's browser tabs, their video call, their music.

This changes what "the right metric" even means. A cloud system can be tuned purely for throughput or purely for latency because it exists to do one job. A phone or laptop has to share. So local-first inference engineering adds a metric that barely exists in the data center: resource courtesy how much battery, memory, and thermal headroom the model is allowed to consume before it starts degrading everything else the person is trying to do. Push too hard for speed and the fan spins up, the battery drains in an hour, and the rest of the operating system starts stuttering. Optimize too conservatively and the response takes so long the feature feels unusable.

Getting this budget wrong is just as costly locally as it is in the cloud, arguably more so, because there's no ops team watching a dashboard to catch it. If a model is quantized down aggressively to fit in the memory a phone can spare, and that compression quietly damages its ability to reason or write code, there's no server-side rollback. The degraded model is just what the person has, until they close the app or update it. Evaluation has to happen before the model ever ships to the device, because once it's local, it's largely on its own.

What makes local-first inference worth the trouble, despite these tighter constraints, is what it buys back: no network dependency, no data ever leaving the machine, no bill that scales with usage, and a response that keeps coming even at thirty thousand feet with no signal at all. The physics is harder. The trade-off, for a growing number of engineers and users, is worth it.

Powering Local-First AI: Searching and Retrieving Context for Inference

John Afariogun — Fri, 10 Jul 2026 16:06:04 +0000

This week, I tackled the Search and Retrieval portion of our Local Context Store Github link. If capturing data cleanly is about keeping our memory system from turning into a messy Downloads folder, searching is about giving the AI the exact file it needs the moment it asks. My task was to build the retrieval layer, the critical bridge between our stored SQLite records and the prompt window of a Large Language Model (LLM).

The goal was simple but vital: when a user asks the AI a question, the system needs to seamlessly dive into its local memory, find the most relevant past context, and package it up so the LLM can reason with it.

Finding the Right Needles

To make this happen, I implemented a suite of search functions, such as search_context_items and search_context_by_type. Under the hood, these use SQLite's LIKE operator to perform case-insensitive keyword searches across both the title and content of our stored memory. This ensures that if the system is looking for "sqlite", it will reliably find records mentioning "SQLite" regardless of how it was capitalized, and whether the keyword is hiding in the headline or deep in the body text.

I also added the ability to filter these searches by strict context types. If the AI is trying to remember a technical choice, we can restrict the search solely to config_decision records, entirely ignoring irrelevant device_log or learning_record entries.

Ranking for the Context Window

Finding matching text is only half the battle. Because an LLM's context window is limited and valuable, we can't just feed the model a random assortment of keyword matches. We have to guarantee that the best information surfaces first.

I solved this by enforcing a strict hierarchy in the database queries: ORDER BY importance DESC, created_at DESC. This means high-priority memories are always fetched before trivial notes, and recent memories are prioritized over older ones. Furthermore, I pushed the LIMIT constraint directly down to the database level. Instead of fetching hundreds of rows into Python memory just to slice off the top five, the database does the heavy lifting, returning only the most critical handful of records.

Translating Data for the LLM

Once the database returns those top records, they are still just raw data dictionaries. To be useful, they have to be translated into a language the LLM understands natively: clean, structured text.

I built the prepare_context_for_inference function to transform those raw rows into a highly readable text block. Instead of dumping raw JSON into the prompt, the AI receives cleanly formatted blocks indicating the index, type, title, and content of each memory. This structural clarity helps the LLM easily parse the context boundaries so it doesn't confuse a past project note with the user's current question.

Proving Local Speed

Finally, because this is a local-first system, speed is non-negotiable. I integrated a lightweight timing mechanism to measure exactly how fast these database lookups happen. Seeing the context retrieved and formatted in just a few milliseconds proved that our local SQLite approach is blazing fast, meaning we can inject memories into prompts without introducing noticeable lag to the user experience.

This task proved to me that effective AI memory isn't just about storing data. It relies just as heavily on efficiently ranking, filtering, and structuring that data for inference. With this retrieval layer in place, our AI won't just passively store memories, it will actively know how to use them.

The Hidden Life of a Container: A Complete Lifecycle

John Afariogun — Thu, 21 May 2026 12:37:05 +0000

The anatomy of a container tells you what the walls are made of. This article tells you when they go up, what happens inside them, and what the kernel does the moment they come down.

In the previous article, we dissected a running container at a single moment in time: the namespaces building the illusion of isolation, the cgroups enforcing the resource constitution, OverlayFS merging layers into a coherent filesystem, the veth pair wiring the container into the network. A cross-section. A photograph.

But a photograph doesn't tell you how the subject got there, or what happens after the shutter closes.

That's what this piece is for. We'll follow a single container from before it exists to after it's gone — and at each transition, we'll look at what actually changes at the kernel level. The machinery is the same as before. Now we watch it move.

We'll also cover the three places where production systems quietly break in ways that monitoring won't catch until it's too late: signal handling, zombie processes, and the OOM killer.

Before the Container: The Image as a Promise

Before anything runs, the runtime needs something to run from. An image isn't a virtual machine disk or a binary blob — it's a stack of read-only filesystem layers, each one a delta on the last, stored under /var/lib/docker/overlay2/ and identified by SHA256 digest rather than name.

When you run docker pull, the daemon fetches a manifest first: a JSON document listing every layer by digest. It then checks which of those digests already exist locally and downloads only the missing ones. This is why pulling a new version of an image that shares a base layer with one you already have takes seconds — the common layers are already there. The registry protocol is content-addressed, which means layers are inherently deduplicated across every image on the host that uses them.

Each downloaded layer is verified against its digest before being committed to the store. A tampered or corrupted layer fails this check before it touches anything.

The image at rest is inert. It's a promise of what the container's filesystem will look like when it starts — nothing more. The OverlayFS that merges those layers into a live, writable filesystem doesn't exist yet. That comes with create.

Stage 1: `docker create` — Assembling the Environment

Here is something most engineers don't know: docker run is not a single operation. It is docker create followed immediately by docker start. Knowing this distinction is practically useful — but more importantly, it clarifies when each piece of kernel infrastructure comes into existence.

docker create builds the complete environment the container will inhabit. Nothing executes. No process runs. It is pure allocation.

The OverlayFS mount. The runtime creates a new upperdir — an empty, writable directory unique to this container instance. The image's read-only layers become the lowerdir. The OverlayFS is configured to present both as a single unified filesystem: reads fall through to the lower layers, writes land in the upper layer, and the container will see a seamless root filesystem when it starts. The layers you read about in the anatomy piece are present here. The writable layer that captures everything your container does is created here.

The namespace allocation. The six namespaces — PID, NET, MNT, IPC, UTS, USER — are prepared. At this point they're reserved but not yet active. There's nothing to isolate, so isolation hasn't started.

The cgroup hierarchy. A cgroup is created for this container under /sys/fs/cgroup/. The memory limit from --memory 512m and the CPU quota from --cpus 0.5 are written into the cgroup's control files right now. The cgroup exists. The limits are set. But with no processes inside it, it enforces nothing — a constitution with no citizens.

The network configuration. The veth pair is created: one end destined for the container's network namespace, one end connecting to the docker0 bridge on the host. An IP is assigned. NAT rules are written to iptables for port mappings. The virtual cable exists, but nothing is plugged in on the container end yet.

After docker create, the container is a complete kernel data structure — every wall built, every rule written, every wire run — with no tenant. Its state is "created". Nothing has been charged to the CPU. Nothing has touched the writable layer.

The practical implication: you can pre-warm containers during off-peak hours and start them in milliseconds when demand arrives. The expensive work of building the environment is already done.

Stage 2: `docker start` — Crossing the Threshold

This is the moment the environment becomes inhabited. Three components work in sequence: dockerd, containerd, and containerd-shim.

dockerd instructs containerd to start the container. containerd forks a containerd-shim — the small, dedicated supervisor we covered in the daemon article — which then calls runc.

runc is where the kernel call happens. It takes the container's prepared configuration and calls clone() with the namespace flags: CLONE_NEWPID, CLONE_NEWNET, CLONE_NEWNS, and the rest. The namespaces activate. The OverlayFS is mounted. The cgroup begins accounting. The veth pair connects. Then runc calls execve() with whatever you specified as ENTRYPOINT or CMD.

That process — your application — becomes PID 1 inside the container.

Once execve() returns, runc exits. It has done its job. The containerd-shim stays behind, holding the container's stdin/stdout file descriptors and watching PID 1. If dockerd crashes, the shim keeps the container alive — which is the architecture we walked through in detail previously.

The moment docker start completes, everything the anatomy article described is live and active: the isolated process tree, the private network stack, the merged filesystem, the cgroup enforcing limits. The photograph is now a film.

And this is the first place things go quietly wrong. PID 1 carries obligations that your application almost certainly doesn't know about. We'll come back to that shortly.

Stage 3: Running — What the Commands Actually Do

A running container looks opaque from the outside. Under the hood, every docker command in this state is a thin wrapper over kernel operations you already understand.

docker exec is the most commonly misunderstood. When you run docker exec -it myapp-prod /bin/sh, Docker doesn't create a new container. It calls setns() — a system call that lets a process join existing namespaces. Your shell enters the container's PID and network namespaces and sees the same environment the application sees. Nothing new is created. You're walking into an existing apartment, not building a new one.

docker logs reads from the file descriptors the containerd-shim has been holding since start. The shim inherited the container's stdout and stderr pipes and has been buffering them since the first byte was written. No daemon magic — the shim is just a persistent pipe holder.

docker stats reads cgroup control files directly: /sys/fs/cgroup/memory.current for RSS, CPU accounting files for usage. The numbers you see in the terminal are the same numbers the kernel is maintaining to enforce your limits.

docker pause is the most elegant operation in this set. It uses the cgroup freezer subsystem to send SIGSTOP to every process in the container simultaneously — not one at a time, but atomically, via the cgroup. They freeze mid-instruction with no opportunity to catch the signal or react. docker unpause sends SIGCONT through the same path and they resume exactly where they stopped. In-flight operations, open sockets, memory contents — all preserved.

Stage 4: `docker stop` — The Two-Phase Shutdown

This is where most production problems originate, and where the PID 1 decision made at start time comes due.

docker stop is a two-phase protocol. Phase one: SIGTERM is sent to PID 1. The application has a grace period — ten seconds by default, adjustable with -t — to finish what it's doing and exit cleanly. Close database connections. Drain in-flight requests. Flush logs. Phase two: if PID 1 is still alive when the timer expires, SIGKILL is sent. There is no negotiation with SIGKILL. The kernel terminates the process immediately and unconditionally.

The failure mode that bites teams most often: the shell wrapper.

Many containers are launched like this: CMD ["sh", "-c", "node server.js"]. The shell becomes PID 1. When Docker sends SIGTERM to PID 1, the shell receives it — and by default, shells do not forward signals to their children. Your Node.js process never sees SIGTERM. Ten seconds pass. SIGKILL arrives. The server dies mid-request, connections drop, and the exit code suggests a crash rather than a clean shutdown.

The fix is to make your application PID 1 directly. Use the exec form: CMD ["node", "server.js"]. Or, if you need a shell script for setup, end it with exec node server.js — the exec replaces the shell process rather than forking a child, so your application inherits PID 1.

Ten seconds is also almost always too short. An application with database connection pools to drain and requests to finish needs more. Set -t 30 as a floor. For services handling long-lived connections, -t 60 or higher is appropriate. The grace period is your only window for a clean shutdown — size it honestly.

After a successful stop, the container's state becomes "exited". Crucially, the writable OverlayFS layer is preserved — every file the application created or modified is still there. The container can be restarted with docker start and will resume from exactly the filesystem state it stopped in.

The First Danger Zone: Zombie Processes

On a normal Linux host, PID 1 is the init system. One of init's core responsibilities — one so fundamental it's baked into the kernel's design — is reaping dead child processes. When a process exits, it doesn't fully disappear. Its kernel entry stays open, holding its exit code, until its parent calls wait() to collect that code. Until then, it sits in state Z: a zombie. Dead, but not yet buried.

Init's job is to call wait() on every process that loses its parent, so the kernel slot gets freed. Without init doing this, zombie entries accumulate indefinitely.

In a container, your application is PID 1. And your application — a web server, an API, a worker — was written to serve requests, not to supervise processes. It almost certainly never calls wait().

The scenario: your web server forks a worker to handle a long request. The worker finishes and calls exit(). It waits for its parent to acknowledge the exit. The parent never does. The worker's kernel entry sits in Z state. Do this at scale, over days of production traffic, and the PID table fills. Eventually fork() fails — the container cannot spawn new processes — and the application breaks in a way that looks nothing like its actual cause.

docker stats will show the container as healthy throughout. CPU and memory are fine. The zombie count isn't surfaced by any standard metric.

The fix is a proper init process sitting in front of your application. tini is the canonical choice — purpose-built for containers, less than a thousand lines of C, does one thing: reap zombies and forward signals correctly.

RUN apt-get install -y tini
ENTRYPOINT ["/tini", "--", "/usr/local/bin/myapp"]

If you don't want to touch the image, docker run --init injects a bundled init binary automatically. Use one or the other on every production container, as a default, without exception.

To check for zombies in a running container:

docker exec myapp-prod ps aux | grep ' Z '

Any output means you have a problem. The fix is tini. The time to add it is before the deployment, not during the incident.

The Second Danger Zone: The OOM Killer

The cgroup memory limit — set at create time, written to memory.max in cgroup v2 — is not a suggestion. When a container's resident memory usage reaches that ceiling, the kernel's Out-Of-Memory killer activates.

The OOM killer scores every process in the cgroup by a "badness" calculation: how much memory the process uses relative to total system memory, adjusted by that process's oom_score_adj value. The highest scorer is sent SIGKILL. In a single-process container, there is exactly one candidate. PID 1 always loses.

The critical distinction from docker stop: the OOM killer sends no SIGTERM. There is no grace period. No warning, no chance to flush state, close connections, or write a final log line. The process simply stops existing. Docker records this as OOMKilled: true in the container's inspect output:

docker inspect myapp-prod --format '{{.State.OOMKilled}}'
true

The kernel also logs it to dmesg:

dmesg | grep -i "oom\|killed process"

Mitigation works at two levels. The first is setting a soft limit below the hard limit:

docker run --memory 512m --memory-reservation 400m myapp

--memory-reservation tells the kernel to apply gentle memory pressure — nudging the container's garbage collector, encouraging page reclamation — before the hard ceiling is reached. It's an early warning system rather than a wall. The container can still exceed the reservation temporarily; only --memory is the hard stop.

The second level is treating OOM kills as bugs, not tuning parameters. A container that is repeatedly OOM-killed has either a memory leak or limits set below its actual working set. Raising the limit is a short-term fix. Finding the leak is the real work.

Stage 5: `docker rm` — Dismantling the Environment

docker rm is the exact inverse of docker create. Every kernel structure that create allocated is released in reverse.

The OverlayFS upper layer is deleted. Every file your application created, modified, or deleted since the container started — the entire writable history — is gone. If your application wrote logs or state directly to the container filesystem, it's unrecoverable. This is the reason containerised applications should write persistent data to mounted volumes, not the container filesystem: docker rm treats the writable layer as ephemeral by design.

The veth pair is removed. The IP address returns to Docker's pool. The iptables NAT rules for port mappings are deleted. The network configuration from create is fully unwound.

The cgroup hierarchy is destroyed. The entries under /sys/fs/cgroup/ that tracked this container's memory and CPU are removed. The kernel stops accounting for this container entirely.

What survives: the image layers. The read-only lowerdir that formed the container's base filesystem is untouched — available immediately for the next container. And named volumes survive unless you pass --volumes to docker rm. Persistent data stored in volumes outlives the container that created it, which is the intended design.

The Full Picture

The anatomy article showed you the ingredients. This one showed you the recipe — the same namespaces, cgroups, OverlayFS, and veth pairs assembled in sequence, operated during a container's life, and dismantled at its end.

The mental model to carry forward:

Create is allocation, start is execution. Every kernel structure — namespaces, cgroups, OverlayFS, veth pairs — exists before your application runs a single instruction. This is why pre-warming works and why restart is fast.

PID 1 is a contract, not just a position. The kernel gives PID 1 responsibilities that init normally handles: signal forwarding and zombie reaping. If your application holds that position, it inherits those responsibilities. Use tini or --init by default.

SIGTERM is your only warning. The grace period between SIGTERM and SIGKILL is the only window you get for a clean shutdown. Your application must handle the signal, and the window must be sized for your actual workload. Ten seconds is almost always too short.

The OOM killer gives no warning at all. There is no SIGTERM, no grace period, no log line from your application. If OOMKilled: true appears in production, treat it as a bug — because it is one.

The writable layer is temporary. docker rm destroys it completely. Write persistent state to volumes. Treat the container filesystem as scratch space that disappears when the container does.

docker run looks like a single command. It is actually the sequential execution of eight distinct kernel operations, each with observable state and specific failure modes. The engineers who debug containers fastest aren't the ones who know the most flags — they're the ones who can trace a problem back to the operation where the kernel did something unexpected.

Now you can.

Part of an ongoing series on container internals. Previous: A Deep Dive into Docker: What Ticks Under the Hood?

The Middle Child Syndrome: Why Your Frontend might not be able to Talk to it's Docker Siblings

John Afariogun — Fri, 20 Feb 2026 15:58:08 +0000

Containerizing full-stack apps reveals a harsh reality—your React frontend is the awkward middle child that can't speak to its Docker siblings.

Containerizing a full-stack application is a rite of passage for every DevOps-leaning engineer. You successfully get your Node.js backend talking to PostgreSQL, your Python ML service crunching data, and Redis caching everything in between.

But then, the "Middle Child" enters the room: The Frontend.

Despite being part of the docker-compose.yml family, the frontend often feels isolated, unable to speak the same internal language as its Docker siblings. Here's why it happens and how to solve it.

The Family Reunion That Excluded Frontend

I recently orchestrated a multi-service e-commerce app with:

Backend (Node.js/Express)    ✅ Connected
ML Service (Python/Flask)    ✅ Connected  
PostgreSQL Database          ✅ Connected
Redis Cache                  ✅ Connected
React Frontend               ❌ Left outside in the cold

Inside the Docker bridge network, life was beautiful. My backend could reach the ML service simply by using the service name:

// Inside the backend container
const response = await fetch('http://ml-service:5000/recommendations/42');
// ✅ Works perfectly!

The Docker DNS handles the heavy lifting. Services on the same bridge network are family.

# docker-compose.yml - Happy family networking
services:
  backend:
    networks: [app-network]
  ml-service:
    networks: [app-network]
  postgres:
    networks: [app-network]
  redis:
    networks: [app-network]

networks:
  app-network:
    driver: bridge

Frontend Got Kicked Out (The Harsh Reality)

Then I tried the same thing from my React frontend:

// React frontend trying to join the family...
fetch('http://backend:8080/api/products')
  .then(res => res.json())
  .catch(err => console.error('Sibling rivalry:', err));

Browser Console:

net::ERR_NAME_NOT_RESOLVED

Why Did This Fail?

The "Middle Child Syndrome" stems from a fundamental misunderstanding of where the code actually runs:

Backend code runs inside the Docker container → uses Docker's internal DNS
Frontend code is delivered by Docker, but executes in the user's browser

The browser lives on your host machine (your device), not inside the Docker bridge network. Your device's DNS has no idea what http://backend is. The Docker network is a private club your browser doesn't have membership for.

Browser ←─── HTTP ───► ??? ──── Docker Network ───► Services
  │                              (backend, ml, db, redis)
  │
  └── Can't reach Docker DNS directly ❌

The Solutions: Pick Your Poison

1. Expose Everything (Security Nightmare ⚠️)

The quickest fix is to expose every service to your host machine:

services:
  backend:
    ports:
      - "8080:8080"  # Now public on localhost
  ml-service:
    ports:
      - "5000:5000"  # Exposed to internet

React calls http://localhost:8080, also calls http://localhost:5000 ✅ Works, but you've just exposed all your internal services to the entire internet. In production, this is a massive security "no-go."

2. Backend Proxy (Secure & Simple)

Route frontend requests through your backend, which can access Docker DNS:

services:
  backend:
    ports:
      - "8080:8080"  # Single exposed port
  ml-service:
    # No ports exposed - internal only

Backend proxies ML requests:

// backend/server.js
app.get('/api/ml/:path*', async (req, res) => {
  const mlUrl = `http://ml-service:5000/${req.params.path}`;
  const response = await fetch(mlUrl);
  res.json(await response.json());
});

React calls /api/ml/recommendations → Backend proxies to ml-service:5000 ✅ Secure + elegant.

3. Nginx Reverse Proxy (Production Ready)

This is the most architecturally sound approach. Put a "Gatekeeper" in front of your family:

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf

  frontend:
    # No ports exposed

  backend:
    # No ports exposed

  ml-service:
    # No ports exposed

nginx.conf:

server {
    listen 80;

    location /api/ {
        proxy_pass http://backend:8080/;
    }

    location /ml/ {
        proxy_pass http://ml-service:5000/;
    }

    location / {
        proxy_pass http://frontend:3000/;
    }
}

Now your frontend only talks to one place: the Nginx port. Nginx lives inside the Docker network and handles routing to all siblings.

Browser ←─── HTTP ───► Nginx (port 80) ──── Docker Network ───► Services ✅

The Root Cause: Network Architecture Mismatch

Docker bridge networks solve:

✅ Service-to-service communication
✅ Container DNS resolution
❌ Browser-to-container (without port mapping or proxy)

The fix requires understanding execution context:

Code Location	Runs Where?	Can Use Docker DNS?
`backend/server.js`	Inside container	✅ Yes
`ml-service/app.py`	Inside container	✅ Yes
`frontend/src/App.jsx`	In browser	❌ No

Lessons Learned (The Hard Way)

Execution Context is King - Always ask: "Where is this code actually running?" If it's a .jsx file, it runs in the browser, not Docker.
One Ingress Point - Avoid "Swiss Cheese" security. Expose one port (80/443) and route everything internally.
Environment Variables Save Lives:

   const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:8080';

CORS is Your Friend - Configure properly on all services that Nginx proxies:

   app.use(cors({ origin: process.env.ALLOWED_ORIGINS }));

Complete Working Example

version: '3.8'

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on: [frontend, backend]

  frontend:
    build: ./frontend
    # No ports - accessed via nginx

  backend:
    build: ./backend
    environment:
      DB_HOST: postgres
      REDIS_URL: redis://redis:6379
    # No ports - accessed via nginx

  ml-service:
    build: ./ml-service
    # Internal only

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: shopmicro

  redis:
    image: redis:alpine

networks:
  default:
    driver: bridge

The frontend middle child finally found its place - behind a proxy, secure, and talking to all its Docker siblings through proper networking architecture.

What's Next?

In my next post, I'll share how I took this ShopMicro architecture and scaled it into a Kubernetes cluster with Ingress controllers—where the networking gets even more "fun."

🔔 Notifycli: A Lightweight Go CLI for Firebase Push Notifications

John Afariogun — Fri, 05 Dec 2025 08:28:00 +0000

Need to send push notifications to your mobile or web clients — from the command line, a backend script, or a CI/CD pipeline — without building a full backend server?
Notifycli is a simple, Go-based CLI that does exactly that: use Firebase Cloud Messaging (FCM) credentials + a device token to send push notifications.

In this post, I unpack the code, show installation and usage, and highlight how it's built — so you can use or extend it for your own projects.

What is Notifycli?

According to the project README:

Notifycli is a “Go CLI for sending push notifications to mobile and web devices using Firebase Cloud Messaging.” (GitHub)
It supports sending to a single device (via FCM device token), and allows custom data payloads — e.g. a title, body, optional URL — which your app can use for deep linking or redirection. (GitHub)
It uses a clean project structure based on the popular CLI framework Cobra for subcommands and flag parsing. (GitHub)

Because it's a standalone binary (no heavy deps, no web server), it works well for automation: cron jobs, server scripts, deployment hooks, or any backend that just needs to “fire-and-forget” an FCM push.

Project Structure & Architecture

Here’s how the repo is structured: (GitHub)

Notifycli/
 ├── cmd/
 │    ├── root.go         # CLI root command definitions
 │    └── notify.go       # “notify” subcommand: sends a notification
 ├── internal/
 │    └── firebase/
 │         └── client.go  # Firebase FCM client wrapper
 ├── main.go              # Entry point
 ├── go.mod / go.sum      # Module definitions
 ├── test/                # (optional) tests
 └── README.md

Highlights:

cmd/: Uses Cobra to define commands and flags.
internal/firebase/client.go: Encapsulates FCM initialization, authentication using a Firebase service-account JSON key, and the logic to send notifications via FCM REST API. (GitHub)
Minimal external dependencies — this keeps the binary lightweight and portable.
Easy to integrate with scripts, cron jobs, CI/CD pipelines — you just call notifcli notify ....

How to Build & Use

1. Clone & Build

git clone https://github.com/johnafariogun/Notifycli.git
cd Notifycli
go build -o notifcli
# optionally:
go install

2. Provide Firebase Credentials

Go to your Firebase project → Project Settings → Service Accounts → Generate new private key.
Download the serviceAccount.json and place it in your project root (or anywhere you like, but pass its path with --creds). (GitHub)

3. Send a Notification via CLI

notifcli notify \
  --token <DEVICE_FCM_TOKEN> \
  --title "Deployment Successful" \
  --body "Your service is live." \
  --creds /path/to/serviceAccount.json

Optional flag: --url, to include a link in the data payload (useful for app deep links or redirect URLs). (GitHub)

That’s all — a simple, one-liner to trigger a push notification from anywhere.

Under the Hood: What’s Going On

The CLI parses flags (token, title, body, url, creds) via Cobra in cmd/notify.go. (GitHub)
The internal/firebase/client.go module: initializes a Firebase app using the provided service account, constructs the FCM message (with title/body, and optional data payload containing link), and sends the request to FCM via HTTPS. (GitHub)
Error handling covers cases like missing credentials, invalid FCM token, or network failures. The CLI prints descriptive error messages. (GitHub)
Because it's a native Go binary, it’s cross-platform (Linux, macOS, etc.) and doesn’t require runtime dependencies beyond Go’s standard library + net/http.

Why This Tool Matters

Simplicity & Speed: No need to build a full backend just to send notifications.
Automation-friendly: Great for deployment scripts, CI/CD, cron jobs, or server-side alerts.
Portable: Build once, deploy anywhere.
Extensible: You can extend internal/firebase/client.go to support more advanced FCM features — e.g. topic messages, batch sends, custom data payloads, image notifications. The architecture is clean and modular. (GitHub)

Wrap-up & Final Thoughts

Notifycli is a great example of how a small, focused tool can do one thing well — in this case: send FCM push notifications — and integrate easily into scripts, automation, or backend workflows.
Its clean Go + Cobra structure and minimal dependencies make it perfect for developers or DevOps workflows that don’t need a full backend server just for notifications.

If you need a lightweight, scriptable, cross-platform tool for mobile/web push notifications — especially useful for deployment alerts, status updates, or automation — give Notifycli a try.

A2A adventures

John Afariogun — Mon, 03 Nov 2025 17:43:20 +0000

Building a GitHub Issues Agent with FastAPI and A2A

This project demonstrates a small agent that receives A2A JSON-RPC messages and returns GitHub issues for a repository. It is intentionally minimal — focusing on clear message schemas, simple HTTP fetch logic, and deterministic behavior.

Motivation

I wanted an agent that can be called by other systems via an A2A JSON-RPC contract and that returns a small, well-formed payload containing issue metadata and a short textual summary.

Architecture

FastAPI for the HTTP server and lifecycle management
Pydantic models (in models/a2a.py) for the message contract
A single agent implementation (agents/github_issues_agent.py) that extracts the repository and calls a tool function utils.fetch_issues to get the data from GitHub

Implementation notes

agents/github_issues_agent.py extracts owner/repo strings from the message parts. It builds a TaskResult that includes a textual summary and an artifact containing the full issues payload.
utils/fetch_issues uses httpx and handles rate-limit behavior by allowing a GITHUB_TOKEN in the environment.

You can check it out at github.com/johnafariogun/github_app
— End

🐱 My HNG 13 Stage 0 Task — Building a Simple Cat Facts API with FastAPI

John Afariogun — Thu, 16 Oct 2025 10:45:06 +0000

After getting to the penultimate stage in HNG12 internship earlier this year, my perfectionist tendencies cropped up again and this time I want to get to the ultimate stage. First though I have to start from the scratch so stage 0 it is.

The goal for Stage 0 was straightforward:

👉 Build a small backend application that returns some personal info — and something extra (Cats facts).

🚀 Project Overview

This project, called Cat Facts API Integration, fetches random cat facts from the public Cat Facts API and combines them with basic user information.

It includes three simple endpoints:

/ → Root welcome route
/health → Health check
/me → My personal info + a random cat fact

All built with FastAPI, httpx, and a bit of structured logging.

🧩 Project Structure


HNG13_simple_rest_stage_0/
├── app.py
├── app.log
├── requirements.txt
└── README.md

The app includes:

FastAPI for routing and documentation
httpx for making async API requests
logging for monitoring
CORS middleware for flexible frontend integration if need be

🧭 Endpoints Documentation

Method	Endpoint	Description
`GET`	`/`	Root endpoint that returns a welcome message.
`GET`	`/health`	Confirms that the API is healthy and reachable.
`GET`	`/me`	Returns user info (email, name, stack) along with a random cat fact.

🧪 Example Response

GET /me

json { "status": "success", "user": { "email": "afariogun.john2002@gmail.com", "name": "John Afariogun", "stack": "Python/FastAPI" }, "timestamp": "2025-10-15T10:00:00Z", "fact": "Cats sleep for around 70% of their lives." }

🧰 Running the App Locally

To test this project on your system:

bash git clone https://github.com/johnafariogun/HNG13_simple_rest_stage_0 cd HNG13_simple_rest_stage_0 pip install -r requirements.txt

Then start the server:

bash python app.py

Visit these URLs in your browser:

http://127.0.0.1:8080
http://127.0.0.1:8080/me
http://127.0.0.1:8080/docs → to explore the auto-generated FastAPI documentation

You can checkout (mine)[https://hng13simplereststage0-production.up.railway.app/me]

📸 OpenAPI Documentation

FastAPI automatically provides Swagger UI for your routes:

🧭 Navigate to /docs
You’ll see your /, /health, and /me routes neatly documented — no extra setup needed!

🌍 Deployment

So I deployed this on Railway

You can check out how to deploy a fastapi app on railway at the official docs

💡 What I Learned

How to set up a simple FastAPI app
How to call external APIs asynchronously using httpx
How to implement logging and error handling
How to structure JSON responses neatly
The power of automatic documentation in FastAPI
How to deploy using Railway

🔚 Conclusion

Stage 0 may look simple, but it’s where the foundation for cleaner, production-ready APIs begins.

This project taught me how small things — like handling timeouts, errors, and logs — make a huge difference when building real backend systems.

Next step? Stage 1 of HNG 13, probably focusing on testing, deployment, and CI/CD 🚀

👨‍💻 Author: John Afariogun
Stack: Python / FastAPI
GitHub: @johnafariogun
Email: afariogun.john2002@gmail.com