Forem: nicolas.vbgh

Your Pre-Production Server Is on the Public Internet. Here's How to Fix That

nicolas.vbgh — Wed, 18 Mar 2026 20:23:08 +0000

You just deployed your pre-production environment. It works. You're proud.

Then someone asks: "Can I access it from home?" And you think, sure, I'll just... expose it to the internet?

No. Absolutely not. Your dev and pre-production servers are full of half-finished features, debug endpoints, test data, and admin panels whose password is "admin." Putting them on the public internet is like leaving your house keys under the mat and tweeting the address.

You need a solution. One that works for your whole team — not just the engineers.

The Problems Nobody Warns You About

Here's the situation. You have a server somewhere — a Kubernetes cluster, a VPS, a rack in the basement that everyone pretends is temporary. Inside, you run multiple environments: development, pre-production, monitoring dashboards, error tracking. Internal stuff. The kind of services your team needs daily but the outside world should never touch.

The obvious move: give each service a public URL, slap on authentication, call it a day.

Four problems with that approach.

Attack surface. Every public endpoint is one. Security teams hate it. They're right. You can argue with them, but you won't win. You shouldn't.

Authentication overhead. You now need login pages on every internal tool. Your monitoring dashboard, your error tracker, your dev and pre-production environments, your reverse proxy dashboard. SSO exists, but it's complex to set up and maintain. You wanted to ship a feature, not become an identity provider. For tools five people use.

Search engine indexing. Google indexes your pre-production site. Now your half-finished app shows up in search results right next to your real product. You're explaining to a client that no, that's not the real product, and yes that error message is normal. Great first impression.

Bot traffic. Security scanners and bots crawl the internet constantly. A public endpoint gets found — not if, when. They probe it, hammer it, try default credentials. Your pre-production API — the one with debug mode on and no rate limiting — is now getting brute-forced by strangers. Not because you were targeted. Because you were visible. That's all it takes.

The real answer: make these services invisible. Not hidden behind a login page. Actually unreachable. If you're not authorized, they don't exist.

How? That's where it gets interesting.

What We Actually Need

Before diving into tools, let's be clear about the requirements.

We need a way for authorized devices to reach internal services, and for everyone else to not even know they exist. Not "protected by a login page." Actually invisible. No DNS resolution, no open port, nothing to find.

That points toward a private network — a tunnel between your device and the server that only exists for people who are allowed in. In networking terms, that's called a VPN: Virtual Private Network. Think of it as a secret hallway. Once you're in, you can access everything inside. From the outside, the hallway doesn't exist.

OK, so a VPN. But not all VPNs are created equal. Here's what matters for a real team:

It has to work on phones. Your tester needs to check the app on their iPhone. Your product owner demos from their iPad. A VPN that only works on Linux is a VPN for one person.
Non-technical people must be able to connect. No config files, no terminal commands, no certificates to import. An app, a button, done.
Services need permanent, human-readable names. Not IP addresses. Real URLs that don't change when you redeploy. Your frontend needs to know where the API lives. Your backend sends emails with links pointing to the app. Configuration has to be simple — one URL per environment, stable across deploys, the same for everyone on the team.
No open ports. The whole point is to hide services from the internet. The VPN itself shouldn't require poking holes in your firewall.

With that list in mind, let's look at the options.

The Options

OpenVPN. The grandparent of VPNs. Battle-tested, runs on everything. Also feels like it was designed when "user-friendly" meant "has a man page." Setting it up means generating certificates, managing a PKI infrastructure, writing config files. Apps exist for phones, but you need to export a .ovpn profile and import it on each device. Your product owner will stare at that file, then stare at you, then ask if there's another way. There is.

SSH tunnels. If you've ever worked on a remote server, you've used SSH — Secure Shell. It gives you a terminal on a distant machine, encrypted. SSH tunnels are a trick on top of that: you tell SSH "take this port on my laptop and connect it to that port on the server." Suddenly your local browser can reach a service running on the other side of the world, through a hidden encrypted tunnel.

The developer's duct tape. Quick, works in a pinch. But it's one tunnel per service. Need seven services? Seven tunnels. Close your laptop? All seven die. And it doesn't work on phones at all — so for anyone outside your engineering team, it's a non-starter.

WireGuard (raw). The modern answer to OpenVPN. It's a protocol — just the tunnel part — and it's excellent. Fast, simple, built into the Linux kernel. But "simple" is relative. You still generate key pairs for every device, copy public keys between machines, edit config files, manage IP assignments. Every new team member means SSH-ing into the server. Every lost phone means re-keying. For two engineers who enjoy networking on a Friday night, it's fine. For a mixed team? Non-starter.

Here's the thing though: WireGuard as a protocol won. Almost every modern VPN tool uses it under the hood. The question isn't which tunnel — it's what you build around it.

Tailscale. This is where it gets interesting. Tailscale wraps WireGuard in a layer that actually works for humans. You install an app — on Mac, Windows, Linux, iOS, Android — tap "connect," and you're on the network. No config files, no keys to manage, no ports to open. It handles NAT traversal, so it works from hotel Wi-Fi and mobile hotspots without any firewall configuration. It has built-in DNS, so services get real names instead of IP addresses.

Your product owner can do it. Your tester can do it from their iPhone. It checks every box on the list.

The catch: Tailscale has two parts. The tunnel — peer-to-peer, encrypted, WireGuard, great. And the control plane — the thing that decides who connects, hands out keys, manages DNS. That control plane lives on Tailscale's servers. They don't see your traffic, but the coordination goes through them. For a side project, fine. For a client project where someone asks "where does our VPN metadata go?" — enjoy that meeting.

Also, free tier has limits. Paid plans charge per user. The bill grows with the team.

ZeroTier, Twingate, and others. Similar category. Each has tradeoffs in pricing, features, and how much control you give up. The fundamental question is the same: do you want someone else running your control plane?

Headscale. This is the one I picked.

The One Where You Keep Your Keys

Headscale is an open-source implementation of the Tailscale control server. Read that sentence again, because it's doing a lot of work.

Same Tailscale clients on every device. Same WireGuard tunnels. Same user experience. But the control plane — who's allowed on the network, what names resolve to what — lives on your server. Your rules, your data, your problem. The good kind of problem.

Your product owner downloads Tailscale on their Mac. Changes one URL in the settings. Connected. Your tester opens the Tailscale app on their Android phone. Same URL. Connected. Your colleague on Linux installs a package and runs one command. Connected.

Everyone's on the same private network. Phones, laptops, tablets. No config files passed around. No VPN profiles to import. No "which certificate do I use?" questions. And the coordination stays on your infrastructure.

Three things sealed the deal.

The clients already exist. Tailscale has polished, well-maintained apps on every platform. By using Headscale, I get all of those for free. My tester doesn't know or care that the server is self-hosted. They see the Tailscale app. It works. That's all they need. I didn't write a single line of client code. My favorite kind of code.

No firewall configuration. NAT traversal handles everything. Devices find each other through the coordination server, then establish direct encrypted connections. Works from coffee shops, airport Wi-Fi, phone hotspots. Nothing to open, nothing to forward. Your network admin can keep sleeping.

Permanent, human-readable names. This is the one that surprised me.

When you put a service behind a VPN, you need a way to reach it. IP addresses work, but 10.43.98.210 means nothing to anyone. You'll forget it. Your team will definitely forget it. Everyone ends up maintaining a bookmark list that drifts out of sync within a week.

Headscale has MagicDNS. You define DNS records, and they resolve automatically for anyone connected to the VPN. Not through some external DNS provider. Not through hosts file hacks. Through the VPN itself.

So my team types https://monitoring.vpn.myproject.dev in their browser. It resolves. It loads. Green padlock, real TLS certificate. Every time.

The names don't change when I redeploy. They don't change when I move the cluster. They don't change when a service restarts and gets a new internal IP. The DNS record points to the reverse proxy, and the proxy routes to wherever the service lives today.

Stable URLs for unstable environments. That's the whole trick.

The Architecture: Building Blocks

So how does this actually come together? Four pieces. Each one does one job. You probably already have opinions about some of them.

Piece 1: Headscale. The coordination server. It runs as a single lightweight process, manages device registrations, hands out keys, and serves MagicDNS records. It needs a domain name so clients can reach it — this is the only part that's publicly exposed, and it only speaks the Tailscale coordination protocol. No web admin panel, no open dashboard. Just a control plane endpoint. Boring by design.

Piece 2: The subnet router. A small container running the Tailscale client inside your cluster. Its job: tell the VPN "hey, the internal network 10.43.0.0/16 is reachable through me." When someone on the VPN wants to reach an internal service, their traffic goes through an encrypted tunnel to this container, and from there into the cluster's network. One container, one role. It doesn't even know what services exist — it just bridges two networks.

Piece 3: A reverse proxy. This is where the URL routing happens. You need something that listens for incoming requests, looks at the hostname (monitoring.vpn.myproject.dev vs api-dev.vpn.myproject.dev), and sends the request to the right service. Traefik, Caddy, nginx — any of them work. I use Traefik because it integrates well with Kubernetes and handles TLS certificates automatically. Caddy would work just as well and has an even simpler config. Nginx if you're already married to it — no judgment, we all have that one tool.

The proxy also handles TLS certificates. Since these services aren't reachable from the public internet, you can't use the standard HTTP challenge for Let's Encrypt. Instead, you use a DNS challenge — prove you own the domain by creating a DNS record, and Let's Encrypt issues a wildcard certificate for *.vpn.myproject.dev. Your proxy automates this. Real certificates, no browser warnings, no self-signed hacks.

Piece 4: An IP allowlist. One middleware rule on the reverse proxy: only accept connections from the Tailscale IP range (100.64.0.0/10). Even if someone somehow discovers the internal URLs, they can't reach the services without being on the VPN. Belt and suspenders. Paranoia as a feature.

That's it. Four components. Headscale coordinates, the subnet router bridges networks, the proxy routes and encrypts, the allowlist enforces access.

Less Is More

Now look at the four problems from the beginning again. Attack surface, authentication overhead, search engine indexing, bot traffic. Four problems. Four different symptoms.

Same root cause: your services were visible.

You didn't solve four problems. You removed the one thing that caused all of them. No attack surface because there's no surface. No authentication overhead because there's nothing to authenticate — if you can reach it, you're already authorized. No indexing because Google can't find what doesn't exist on the public internet. No bot traffic because there's no port to scan.

The best security isn't adding layers. It's removing the need for them.

What Your Team Actually Sees

This is the part that matters. Because the architecture is an infra problem. The experience is what they live with.

Your product owner opens the Tailscale app on their Mac. It connects. They type https://app-ppd.vpn.myproject.dev in their browser. The pre-production app loads. They test. They find a bug. They file a ticket with the URL in it. The URL works for everyone on the team because it's the same for everyone.

Your tester opens Tailscale on their Android phone. Same URL, same app, same behavior. They test the mobile experience on a real device, on a real pre-production environment, from their couch. As it should be.

When they disconnect from the VPN, those URLs stop resolving. The services become invisible. Not "protected by a login page" invisible. Actually invisible. DNS doesn't resolve. There's nothing to attack because there's nothing to find.

No one on the team needs to understand WireGuard, port forwarding, SSH, or certificates. They install an app, connect, and use URLs. That's the bar. Everything below it is someone else's problem — mine.

Making It Work on Kubernetes

This setup runs on any Kubernetes cluster. Here's the implementation shape, without the YAML walls.

Headscale deploys as a single-replica Deployment with a small PostgreSQL database (or SQLite if you want to keep it minimal). It needs an Ingress with a public domain for the coordination endpoint. One container, persistent storage, a ConfigMap for its settings. It'll run on the cheapest node you have and still be bored.

The subnet router is another Deployment running the official Tailscale container image. It authenticates to Headscale with a pre-auth key, advertises the cluster's service CIDR as a subnet route, and needs NET_ADMIN capability to manage network interfaces. Once it's registered and the route is approved, traffic flows.

The reverse proxy — Traefik in my case — gets a DNS-01 certificate resolver configured with your DNS provider's API credentials. It issues wildcard certs for *.vpn.myproject.dev automatically. Each internal service gets an Ingress resource with the VPN hostname.

The IP allowlist is a single middleware definition: allow 100.64.0.0/10, deny everything else. Attach it to every VPN Ingress. Three lines of config, applied everywhere.

The whole stack adds maybe 200MB of memory to your cluster. Headscale is tiny. The subnet router is tiny. The proxy you probably already have.

New internal service? Add a DNS record in Headscale's config, create an Ingress, redeploy. Five minutes.

The Point

The question was never "which VPN protocol is best." WireGuard won that argument years ago. The question is: who manages the control plane, and can non-technical people actually use it?

Tailscale solved the hard part — making WireGuard usable by normal humans. Headscale lets you self-host that solution. Same clients, same experience, your infrastructure.

For my use case — internal dev and pre-production environments that need stable, permanent URLs accessible to a mixed team of developers, testers, and product owners, from laptops and phones, in under a minute — Headscale was the obvious pick. Not because it's the most powerful option. Because it's the one that disappears. You set it up once, your team installs an app, and then everyone just uses https://monitoring.vpn.myproject.dev like it's always been there.

The best infrastructure is the kind nobody notices.

That's the deal.

Who's That Pokémon?

nicolas.vbgh — Fri, 20 Feb 2026 19:52:45 +0000

How I built a real Pokédex with Postgres, linear algebra, and mass nostalgia*

You know the one. Enormous. Blocks the road. Eats all day and sleeps the rest. You can see it perfectly in your head — the round belly, the closed eyes, the absolute commitment to doing nothing. You just can't remember if it's called Snorlax or Munchlax or Relaxo or something else entirely.

This isn't Alzheimer's. This is being 30 and having played Pokémon Red at age 8. You remember everything about these creatures except the one thing a search engine needs: the exact name.

So you type "big sleepy eater" into the search bar.

Zero results.

The database has "An enormous, rotund Pokémon that spends most of its life eating and sleeping" — which is exactly what you meant — but the search engine doesn't know that. It compares letters. It doesn't read.

This is a stupid problem. It's also completely unsolvable with traditional tools. And I spent a week fixing it with linear algebra, graph theory, and a Postgres extension. For 151 Pokémon.

Worth it? Absolutely not. Did I learn something genuinely useful? Actually, yes.

Search Engines Don't Read

Here's something that sounds obvious once you hear it but that most people — including most developers — never think about.

Every search engine works the same way at its core: you type words, it finds those exact words (or close variations) in the data. If the words match, you get results. If they don't, you get nothing. That's it. There's no understanding involved.

This fails constantly:

You search for "comfy shoes for long days" — zero results, because the product is listed as "ergonomic footwear with memory foam"
You search for "legendary thunder bird" — zero results, even though Zapdos is right there, literally tagged as legendary, literally Electric/Flying type
You search for "psychic genetic clone laboratory" — zero results, even though Mewtwo's description says "created from Mew through horrific genetic experiments"

The meanings are identical. The words are different. The search engine shrugs.

This isn't just a Pokémon problem. This is every e-commerce site where users describe what they want instead of knowing what it's called. You just never notice because people silently give up and blame themselves.

The Trick: GPS for Meaning

Here's the idea that makes everything work. And I promise it's simpler than it sounds.

There's a family of AI models — called embedding models — that have been trained on enormous amounts of text (basically the internet) and have learned something remarkable: how to convert any sentence into a set of coordinates.

Think of it like GPS, but for meaning instead of geography.

When you feed "fire lizard with a flame on its tail" into the model, it returns 384 numbers — coordinates in meaning-space. When you feed "Charmander" into the same model, it returns a different set of 384 numbers — but they're remarkably close to the first set. Because the model understands that these two phrases describe the same thing.

Meanwhile, "ghost haunting shadows" produces coordinates that are, mathematically speaking, on a different continent from "friendly goldfish".

The key principle: similar meanings → nearby coordinates. Different meanings → distant coordinates.

That's it. That's the whole trick. Once you have coordinates for meaning, search becomes a geometry problem:

Pre-compute coordinates for everything in your database.
When someone searches, compute coordinates for their query.
Return the entries with the nearest coordinates.

No keyword matching. No synonym dictionaries. The model already understands that "big sleepy eater" and "enormous rotund Pokémon that spends its life eating and sleeping" are the same idea — because it has read the internet.

Wait, That's All?

Here's the part that surprised me.

You don't need a new database. You don't need a subscription to some AI platform. You don't need a PhD. You need Postgres (the database most companies already run) with one extension called pgvector.

Here's the entire setup. If you're not a developer, don't worry about the syntax — just notice how little there is:

One new column on your existing table:

ALTER TABLE pokemon ADD COLUMN embedding vector(384);

One index to make searches fast:

CREATE INDEX ON pokemon
USING hnsw (embedding vector_cosine_ops);

The search query:

SELECT name FROM pokemon
ORDER BY embedding <=> :query_vector  -- the user's search, converted to coordinates
LIMIT 5;

That <=> symbol measures how close two sets of coordinates are. Postgres sorts by closeness and returns the top 5 matches. That's natural language search in four lines of SQL.

No new service to operate. No API key. No machine learning pipeline. You add a column to your existing database, and it suddenly understands what people mean, not just what they type.

So Does It Work?

I built a proper benchmark to find out. 151 Gen 1 Pokémon, each encoded with its name, category, types, and description. Then 16 search queries designed to be deliberately tricky — none of the query words appear in the target Pokémon's description. If this works, it's purely because the model understands meaning.

Here's what happened:

What I typed	What I wanted	What the database says	Found?
big heavy sleepy gluttonous lazy	Snorlax	"enormous, rotund, eating and sleeping"	#1
legendary thunder lightning bird	Zapdos	legendary, Electric/Flying type	#1
ethereal gaseous invisible ghost haunting	Gastly	"toxic gas, eerie purple haze"	#1
bone skull dead ghost bony	Cubone	"wears skull of deceased mother"	#1
mysterious ancestor pink psychic origins	Mew	"rarest, contains genetic code of every Pokémon"	#1
fire lizard tail flame starter	Charmander	"small orange lizard with flame on tail"	#1
psychic genetic clone laboratory	Mewtwo	"created through genetic experiments"	#1
giant furious blue sea serpent	Gyarados	"fearsome sea serpent, violent temperament"	top 5

15 out of 16: correct answer as the very first result. The last one (Gyarados) lands in the top 5. Zero word overlap between queries and data.

And the search doesn't just find the right Pokémon — it understands families:

query: 'ethereal gaseous invisible ghost haunting'

  1. 0.842  Gastly   [Ghost/Poison]
  2. 0.821  Haunter  [Ghost/Poison]
  3. 0.809  Gengar   [Ghost/Poison]

Gastly, Haunter, Gengar — the ghost evolution line, ranked in order. In 2 milliseconds. From a regular Postgres database.

What the Numbers Actually Mean

I threw a lot of numbers at this benchmark. Here's how to read them without a statistics degree.

The scorecard

Hit@1 — "Was the correct answer the very first result?" This is the metric that matters most. When you search for something, you look at the first result. If it's wrong, the search feels broken, even if the right answer is hiding at position 3.

Hit@5 — "Was the correct answer somewhere in the top 5?" More forgiving. Most people scan a short list. This tells you whether the answer is findable, even if it's not immediately obvious.

MRR@5 (Mean Reciprocal Rank) — a single number that captures where the right answer typically lands. Always #1? MRR is 100%. Always #2? MRR is 50%. Always #5? MRR is 20%. Think of it as "how many results does the user need to scan before finding what they want?"

Recall@10 — this one is different. It doesn't measure search quality at all. It measures whether the index (the thing that makes searches fast) is giving you honest results. 100% means the index isn't cutting corners. Less than 100% means the index is secretly hiding some results from you. More on that shortly.

Four models, two surprises

I tested four AI models. Here are the results:

Model	Brain size	MRR@5	Hit@1	Hit@5
MPNet-base	109M params	90.6%	81%	100%
BGE-small-en	33M params	90.6%	88%	94%
BGE-small (ONNX)	same brain, lighter runtime	90.6%	88%	94%
MiniLM-L6	23M params	82.8%	69%	100%

Surprise #1: bigger isn't always better. MPNet is 3× larger than BGE-small, but BGE-small actually gets the right answer first more often (88% vs 81%). The trade-off: MPNet never loses the right answer entirely — it always shows up somewhere in the top 5. BGE-small misses one query completely (Mewtwo).

So: the small model is more precise, the big model is more reliable. Both are excellent. "Just use the biggest model" isn't the right advice.

Surprise #2: MiniLM is the unreliable genius. 100% Hit@5 (it always finds the right answer) but only 69% Hit@1 (it often buries it behind other results). It's the student who knows the material but writes messy exams. Cheap to run, but you'll need to show more than one result.

The query that stumped everyone

The hardest query: "psychic genetic clone laboratory" → Mewtwo.

Mewtwo's actual description: "The most powerful Pokémon in existence, created from Mew through horrific genetic experiments."

The words "clone" and "laboratory" never appear. The model has to reason: "genetic experiments" implies a laboratory. The output of genetic experiments is a clone. That's not word matching — that's understanding implications.

The largest model (MPNet) nails it: first result. The smaller models struggle. This is where brain size actually matters — not on easy queries like "fire lizard" → Charmander, but on queries that require connecting dots the text doesn't explicitly draw.

The Index That Lies to You

This is the most important section if you're actually going to build this.

pgvector (the Postgres extension) ships two ways to index your data. One of them has a default setting that silently destroys your search quality. No error message. No warning. Just wrong results.

IVFFlat splits your data into groups (say, 50 groups). When you search, it only looks at the closest group. With 50 groups and 151 Pokémon, each group has about 3 Pokémon. You're searching 3 out of 151 — 2% of your data.

The query is fast. Because it's barely doing anything.

The benchmark makes the damage obvious:

Index	Recall	Speed	Search quality (MRR@5)
No index (scan everything)	100%	4.0 ms	90.6%
IVFFlat (default settings)	30%	3.9 ms	56.2%
HNSW (recommended)	100%	2.0 ms	90.6%

That middle row: 30% recall means 70% of the correct results are hidden. The search quality drops from 90.6% to 56.2%. And it's not even faster — 3.9ms vs 4.0ms without any index.

HNSW (the other index): 100% recall, identical quality to exhaustive search, and it's actually the fastest of the three at 2.0ms. It builds a navigable graph that connects similar entries, and walks that graph at query time. No configuration needed.

The nasty thing about IVFFlat: your queries still return results. They look normal. There are no errors. You just quietly get the wrong Pokémon, your users think the search is bad, and nobody figures out it's the index configuration.

Use HNSW. Always.

Choosing a Model

The model converts text to coordinates. It's the only piece that runs outside Postgres. Two practical choices:

Option A — Maximum quality: all-mpnet-base-v2

from sentence_transformers import SentenceTransformer
model = SentenceTransformer("all-mpnet-base-v2")
vector = model.encode(["legendary thunder bird"])

109M parameters, 768 dimensions. Requires PyTorch (~1.5 GB install). Loads in 3–4 seconds. 100% Hit@5 in every single test. Best choice for a server that stays running.

Option B — Lightweight: BAAI/bge-small-en-v1.5 via FastEmbed

from fastembed import TextEmbedding
model = TextEmbedding("BAAI/bge-small-en-v1.5")
vector = list(model.embed(["legendary thunder bird"]))

33M parameters, 384 dimensions. No PyTorch — runs on ONNX (~100 MB install). Loads in under a second. Slightly weaker on the hardest queries. Best choice for serverless, containers, or anything where startup time matters.

Both output a list of numbers. Both go into the same Postgres column. Both use the same SQL query. The choice is about your deployment, not your architecture.

What It Costs

Nothing is free. Here's what you're actually paying for.

Storage. Each row gains 1.5 KB (at 384 dimensions) or 3 KB (at 768). One million rows: 1.5–3 GB extra. Non-trivial, but manageable by modern Postgres standards.

Ingestion speed. Encoding 151 Pokémon takes 2–12 seconds depending on the model. It scales linearly. For a million items, plan for a background job and a coffee break.

Memory. The AI model lives in RAM while it's running. PyTorch models: 200–400 MB. FastEmbed: much less. If you're running serverless, this is your cold-start bottleneck.

Query overhead. Every search converts the user's text to coordinates before asking Postgres. A few milliseconds on a warm server. On a cold start, add the model load time.

None of these are dealbreakers. But they're not zero, and you should know what you're signing up for.

When to Outgrow This

This approach works beautifully for thousands to a few million entries. Beyond that:

Tens of millions of entries with strict latency requirements → look at dedicated vector databases (Qdrant, Weaviate)
If vector search becomes the primary workload, not a feature → dedicated infrastructure starts to make sense

But those are scaling problems. For most applications — product search, knowledge bases, recommendation engines, and yes, Pokédexes — pgvector inside Postgres is more than enough. Start simple.

Fine Print (Before You Get Too Excited)

A few things I conveniently glossed over while showing you impressive results:

151 is not a lot. This benchmark runs on 151 Pokémon. Your product catalog has 2 million SKUs. Will it scale? Probably. Will the results be as clean? Honestly, I don't know. 151 entries is a demo, not a stress test.

English only. Every model tested here is English. If your users search in French, Japanese, or a mix of both, you need multilingual models — and those are a different conversation with different trade-offs.

Pokémon are easy to search. Think about it: a fire-breathing dragon, an electric mouse, a ghost made of toxic gas. These are absurdly distinctive creatures with exaggerated, unmistakable characteristics. Real-world data — beige office chairs, slightly different insurance policies, 47 variations of the same running shoe — is much harder to distinguish. Don't expect 88% Hit@1 on your SaaS knowledge base.

And the most important thing: it's Postgres. Vector search is a nice trick. But you're still inside a full relational database. You can combine <=> with WHERE type = 'Fire', AND legendary = true, OR generation = 'Gen I'. Filter by category, join with your user table, add a LIMIT based on user preferences — all in the same query. That's not a limitation. That's the whole point. You don't choose between smart search and structured queries. You get both. Because it's a database, baby.

Now Imagine What Else You Could Do

This was 151 Pokémon. A toy. But the technique is the same whether you're searching fictional creatures or anything else. And "anything else" is where it gets interesting.

Let customers describe what they need, not what it's called. A customer walks into a hardware store's website and types "something to hang a heavy mirror on a plaster wall". The product is listed as "toggle bolt M5 zinc-plated 10-pack". No keyword search connects those. Embeddings will. Same story for every retailer where customers describe a problem instead of naming a product.

Find the right section in documentation. You have 2,000 pages of internal docs. A new hire asks "how do I request access to the staging environment?" — the answer is buried in a paragraph titled "Infrastructure Onboarding Procedures, Section 4.2.b". No keyword search will connect those. Embeddings will.

Search scientific conferences by topic. Thousands of posters and abstracts from a medical conference. A researcher is looking for "immune response in patients with liver transplants" — the relevant poster is titled "Hepatic Allograft Tolerance and T-Cell Mediated Immunity". Same idea, completely different vocabulary. Coordinates don't care about jargon.

Detect near-duplicate entries. Customer support tickets, bug reports, patient records — anywhere humans describe the same thing in different words. Encode everything, find entries whose coordinates are suspiciously close, flag them for review. Deduplication without writing a single regex.

Search across images and text. Multimodal embedding models (like CLIP) encode both images and text into the same coordinate space. Upload a photo, find similar products. Describe what you see, find matching images. The principle is identical — coordinates for meaning — just applied to pixels as well as words.

Go multilingual. Multilingual models encode "chien", "dog", and "Hund" to nearly the same coordinates. One column. One index. Every language at once.

The point is: what works for Pokémon will work for your domain, with your data, in your language. Maybe not with the same model or the same parameters — what's perfect for short product names might underperform on long medical reports. The models are different. The data is different. The right tuning is different.

That's not a problem. That's an invitation.

Clone the repo. Swap the dataset. Swap the model. Run the benchmark. See what works for your data. The whole setup is a few files and a Docker image — you can have results in an afternoon.

What I Actually Learned

I set out to build a stupid toy project. I ended up understanding something real.

The gap between "search for words" and "search for meaning" was genuinely unsolvable for decades. Synonym lists helped a little. Fancy text analysis helped a little more. But the core problem — that "big sleepy eater" and "enormous rotund Pokémon that spends its life eating and sleeping" mean the same thing — that required a breakthrough.

That breakthrough: convert text to coordinates, store them in a column, sort by distance.

The language understanding? Done by researchers who trained models on the internet. The fast vector search? Done by the pgvector team. The storage, indexing, and querying? Done by Postgres, which has been quietly excellent at this since 1996.

If you want to try it yourself, the full code — benchmark, dataset, search demo — is open source: gitlab.com/nicolas.vbgh/python-pg-embeddings.

The bottom line:

Use HNSW (not IVFFlat)
all-mpnet-base-v2 if you want the best quality
BAAI/bge-small-en-v1.5 via FastEmbed if you want the lightest setup with still a good quality
Pack as much meaning as possible into the text you encode
It's one column. One index.

All of this to help someone remember that the big sleepy one is called Snorlax.

I regret nothing.

Performance Tests: Fast Enough?

nicolas.vbgh — Tue, 17 Feb 2026 19:33:32 +0000

E2E tests prove it works end-to-end. The full flow succeeds. But users complain it's slow.

Performance regressions are invisible. No test fails. No error appears. Just gradually slower response times until someone notices. By then, you don't know which commit caused it. Was it the ORM change? The new middleware? That "harmless" refactor?

Measure on every merge request. Catch regressions before they ship.

k6: Load Testing

Single-request tests pass. But under load? Connection pool exhausted. Memory leak. Database locks up. That N+1 query that takes 50ms with 10 rows takes 5 seconds with 10,000.

k6 simulates multiple users hitting your API simultaneously.

// tests/performance/smoke-test.js
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  vus: 5,           // 5 virtual users
  duration: '30s',  // 30 seconds

  thresholds: {
    http_req_duration: ['p(95)<500'],  // 95th percentile under 500ms
    http_req_failed: ['rate<0.01'],    // Less than 1% errors
  },
};

export default function () {
  const res = http.get(`${__ENV.API_URL}/health`);

  check(res, {
    'status is 200': (r) => r.status === 200,
    'response time OK': (r) => r.timings.duration < 200,
  });

  sleep(1);
}

p(95)<500 is the constraint that matters. Not average—95th percentile. Averages lie. One fast request hides ten slow ones. p95 tells the truth: "95% of your users get this experience."

✗ http_req_duration: p(95)<500
   ↳ 97% — ✗ 612ms (threshold exceeded)

Endpoint got slow. Developer investigates before merge. Problem found before production. Before the angry email from the client.

The Ramp Pattern: Finding the Breaking Point

Smoke tests check "does it work under light load." Ramp tests find "where does it break."

// tests/performance/stress-test.js
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '1m', target: 10 },   // Warm up
    { duration: '2m', target: 50 },   // Push it
    { duration: '2m', target: 100 },  // Stress it
    { duration: '1m', target: 0 },    // Cool down
  ],
  thresholds: {
    http_req_duration: ['p(99)<2000'],  // Even p99 under 2s
    http_req_failed: ['rate<0.1'],
  },
};

export default function () {
  const res = http.get(`${__ENV.API_URL}/api/items`);

  check(res, {
    'status is 200': (r) => r.status === 200,
  });

  sleep(0.5);
}

The ramp reveals:

Where response times spike — "50 users is fine, 75 users and latency triples"
Connection pool limits — "At 80 concurrent, we start timing out on DB connections"
Memory leaks — "Memory grows linearly with users, never releases"

Run this weekly, not on every MR. It's slow. But it finds the ceiling before production hits it.

Realistic Scenarios: Test the Actual User Journey

A health check endpoint under load means nothing. Test what users actually do.

// tests/performance/user-flow.js
import http from 'k6/http';
import { check, group, sleep } from 'k6';
import { SharedArray } from 'k6/data';

// Pre-generated test users (created in setup)
const users = new SharedArray('users', function () {
  return JSON.parse(open('./test-users.json'));
});

export const options = {
  stages: [
    { duration: '30s', target: 10 },
    { duration: '1m', target: 10 },
    { duration: '30s', target: 0 },
  ],
  thresholds: {
    'group_duration{group:::auth}': ['p(95)<1000'],
    'group_duration{group:::browse}': ['p(95)<500'],
    'group_duration{group:::create}': ['p(95)<2000'],
  },
};

export default function () {
  const user = users[Math.floor(Math.random() * users.length)];

  group('auth', () => {
    const login = http.post(`${__ENV.API_URL}/auth/login`,
      JSON.stringify({ email: user.email, password: user.password }),
      { headers: { 'Content-Type': 'application/json' } }
    );

    check(login, { 'logged in': (r) => r.status === 200 });

    if (login.status !== 200) return;

    const token = JSON.parse(login.body).access_token;
    const auth = { headers: { Authorization: `Bearer ${token}` } };

    group('browse', () => {
      const items = http.get(`${__ENV.API_URL}/api/items`, auth);
      check(items, { 'items loaded': (r) => r.status === 200 });

      const item = http.get(`${__ENV.API_URL}/api/items/1`, auth);
      check(item, { 'item loaded': (r) => r.status === 200 });
    });

    group('create', () => {
      const newItem = http.post(`${__ENV.API_URL}/api/items`,
        JSON.stringify({ title: `Test ${Date.now()}`, description: 'Load test' }),
        { ...auth, headers: { ...auth.headers, 'Content-Type': 'application/json' } }
      );
      check(newItem, { 'item created': (r) => r.status === 201 });
    });
  });

  sleep(1);
}

The group_duration thresholds are per-operation. Auth can be slower (token generation is expensive). Browsing should be fast (it's cached, right?). Creating can be slowest (writes are expensive).

Different thresholds for different operations. Because "the API is slow" is useless. "Item creation is slow" is actionable.

Lighthouse: Frontend Performance

Bundle size creeps up. Images aren't optimized. JavaScript blocks rendering. Lighthouse score drops from 90 to 60. Users bounce before the page loads.

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      url: ['http://localhost:4173'],
      numberOfRuns: 3,  // Average of 3 runs, reduces variance
      settings: {
        preset: 'desktop',  // or 'mobile' for mobile-first
      },
    },
    assert: {
      assertions: {
        'categories:performance': ['warn', { minScore: 0.8 }],
        'categories:accessibility': ['error', { minScore: 0.9 }],  // A11y is not optional
        'categories:best-practices': ['warn', { minScore: 0.9 }],

        // Core Web Vitals - the metrics Google cares about
        'first-contentful-paint': ['warn', { maxNumericValue: 2000 }],
        'largest-contentful-paint': ['warn', { maxNumericValue: 2500 }],
        'cumulative-layout-shift': ['warn', { maxNumericValue: 0.1 }],
        'total-blocking-time': ['warn', { maxNumericValue: 300 }],

        // Bundle size matters
        'total-byte-weight': ['warn', { maxNumericValue: 500000 }],  // 500KB max
      },
    },
    upload: {
      target: 'temporary-public-storage',  // Free, public reports
    },
  },
};

categories:accessibility is error, not warn. Accessibility bugs are bugs. They block merges.

total-byte-weight at 500KB is aggressive. But every KB is a user on slow 3G waiting longer. If your marketing page is 2MB, users leave before they see it.

The Graph That Saves You

Lighthouse CI can track scores over time. But even without that, trends matter.

// In your CI, after Lighthouse runs
const fs = require('fs');
const report = JSON.parse(fs.readFileSync('.lighthouseci/lhr-*.json'));

const metrics = {
  timestamp: new Date().toISOString(),
  commit: process.env.CI_COMMIT_SHA,
  performance: report.categories.performance.score,
  lcp: report.audits['largest-contentful-paint'].numericValue,
  cls: report.audits['cumulative-layout-shift'].numericValue,
  bundleSize: report.audits['total-byte-weight'].numericValue,
};

// Append to a metrics file in your repo (or send to a dashboard)
console.log(JSON.stringify(metrics));

Plot these over time. "Performance dropped 10 points in March" becomes visible. "Which commit?" becomes answerable.

The Gate

Two jobs. Backend load test with k6. Frontend audit with Lighthouse.

perf:k6:
  stage: performance
  image: grafana/k6:latest
  services:
    - name: postgres:16
      alias: db
  variables:
    DATABASE_URL: postgresql+asyncpg://postgres:postgres@db:5432/test
    POSTGRES_HOST_AUTH_METHOD: trust
    API_URL: http://localhost:8000
  before_script:
    - apk add --no-cache python3 py3-pip
    - pip3 install uv --break-system-packages
    - cd backend
    - uv sync --frozen
    - uv run alembic upgrade head
    - uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 &
    - sleep 5
    # Verify backend is up
    - wget -q --spider http://localhost:8000/health || exit 1
  script:
    - k6 run --out json=results.json tests/performance/smoke-test.js
  artifacts:
    when: always
    paths:
      - results.json
    expire_in: 1 week
  allow_failure: false
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

perf:lighthouse:
  stage: performance
  image: node:lts-slim
  variables:
    CHROME_PATH: /usr/bin/chromium
    LHCI_BUILD_CONTEXT__COMMIT_MESSAGE: $CI_COMMIT_MESSAGE
  before_script:
    - apt-get update && apt-get install -y chromium --no-install-recommends
    - cd frontend
    - npm ci
    - npm run build
    - npm run preview -- --port 4173 &
    - npx wait-on http://localhost:4173 --timeout 30000
  script:
    - npx @lhci/cli autorun
  artifacts:
    when: always
    paths:
      - frontend/.lighthouseci/
    expire_in: 1 week
  allow_failure: true  # Warn, don't block
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

--out json=results.json on k6 saves raw metrics. Parse them later. Trend them over time. Find the slow creep before it becomes a slow crisis.

allow_failure: true on Lighthouse means it warns but doesn't block. Start there. When you're confident in your thresholds, switch to false.

Copy, paste, adapt. It works.

The Point

Functional tests prove correctness. Performance tests prove speed. Both matter.

A correct but slow endpoint is a broken endpoint. Users don't wait. They leave. They tweet about it. They use your competitor.

Amazon found that every 100ms of latency cost them 1% of sales. Google found that an extra 0.5 seconds in search page load dropped traffic by 20%. Your app isn't Amazon. But your users are just as impatient.

k6 catches backend slowdowns before they ship. Lighthouse catches frontend bloat before it accumulates. Automated measurement finds what humans miss.

Track trends. Catch regressions. Ship fast code.

That's the deal.

E2E Tests: The Full Stack Check

nicolas.vbgh — Wed, 11 Feb 2026 20:55:31 +0000

Backend tests pass. Frontend tests pass. The contract is validated. Production breaks.

The API works. The components work. Types match. But the login flow? The cookie doesn't persist. CORS blocks the request. The redirect fails. Nobody tested the pieces together.

E2E tests run a real browser against a real backend with a real database. No mocks. No fakes. What users experience.

Why E2E After Unit Tests

Unit tests: fast, isolated, hundreds of them. They check pieces.

E2E tests: slow, integrated, dozens of them. They check flows.

E2E catches what unit tests miss:

CORS configuration errors
Cookie and session handling (SameSite, Secure, HttpOnly flags)
Real database constraints (foreign keys, unique violations, cascade deletes)
Browser-specific quirks (Safari's third-party cookie blocking)
Multi-step user journeys with actual state persistence

Don't replace unit tests with E2E. Add E2E for the critical paths—login, registration, checkout. The flows that cost money when they break.

Playwright

Playwright drives real browsers. Chrome, Firefox, Safari. Same test, multiple engines. Not headless browser simulations—actual browser binaries.

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,  // No .only() in CI
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,

  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:5173',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',  // The debugging killer feature
  },

  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    // Add these when you're serious about cross-browser
    // { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    // { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],

  // Wait for both backend and frontend
  webServer: [
    {
      command: 'cd ../backend && uv run uvicorn app.main:app --port 8000',
      url: 'http://localhost:8000/health',
      reuseExistingServer: !process.env.CI,
    },
    {
      command: 'npm run dev',
      url: 'http://localhost:5173',
      reuseExistingServer: !process.env.CI,
    },
  ],
});

trace: 'on-first-retry' is the debugging multiplier. When a test fails, you get a timeline: every network request, every DOM change, every click. Click through it. See exactly what happened. No more "works on my machine."

video: 'retain-on-failure' is the evidence. The test says "button not found." The video shows the button was there but covered by a modal. Mystery solved.

Test Structure: User Stories, Not Unit Tests

Test user flows, not isolated actions. E2E tests are expensive. Make them count.

import { test, expect } from '@playwright/test';

test('complete auth flow: register, logout, login, forgot password', async ({ page, context }) => {
  const email = `test-${Date.now()}@example.com`;

  // === Registration ===
  await page.goto('/register');
  await page.getByLabel('Email').fill(email);
  await page.getByLabel('Password').fill('SecurePass123!');
  await page.getByRole('button', { name: /register/i }).click();

  // Should land on dashboard with session
  await expect(page).toHaveURL('/dashboard');
  await expect(page.getByText(email)).toBeVisible();

  // Check cookie was set correctly
  const cookies = await context.cookies();
  const sessionCookie = cookies.find(c => c.name === 'session');
  expect(sessionCookie).toBeDefined();
  expect(sessionCookie!.httpOnly).toBe(true);  // Security check

  // === Logout ===
  await page.getByTestId('user-menu').click();
  await page.getByRole('menuitem', { name: /logout/i }).click();
  await expect(page).toHaveURL('/');

  // Session cookie should be gone
  const postLogoutCookies = await context.cookies();
  expect(postLogoutCookies.find(c => c.name === 'session')).toBeUndefined();

  // === Login ===
  await page.goto('/login');
  await page.getByLabel('Email').fill(email);
  await page.getByLabel('Password').fill('SecurePass123!');
  await page.getByRole('button', { name: /login/i }).click();

  await expect(page).toHaveURL('/dashboard');
});

That's three tests in one. But they're the same user journey. Testing them separately means more setup, more teardown, more flakiness. Test the flow, not the steps.

The cookie assertions? Security in the tests. If someone accidentally removes httpOnly, the test fails. Not "we'll catch it in code review." The test fails.

Fixtures: Don't Repeat Setup

Every test creates a user. That's slow and noisy. Fixtures do it once.

// e2e/fixtures.ts
import { test as base } from '@playwright/test';

type TestFixtures = {
  authenticatedPage: Page;
  testUser: { email: string; password: string };
};

export const test = base.extend<TestFixtures>({
  testUser: async ({}, use) => {
    const email = `test-${Date.now()}@example.com`;
    const password = 'TestPass123!';

    // Create user via API (faster than UI)
    await fetch('http://localhost:8000/api/auth/register', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password }),
    });

    await use({ email, password });

    // Cleanup after test (optional but nice)
    // await deleteUser(email);
  },

  authenticatedPage: async ({ page, testUser }, use) => {
    // Login via API, set cookie
    const response = await page.request.post('/api/auth/login', {
      data: testUser,
    });
    const { token } = await response.json();

    await page.context().addCookies([{
      name: 'session',
      value: token,
      domain: 'localhost',
      path: '/',
    }]);

    await use(page);
  },
});

Now tests start already logged in:

import { test } from './fixtures';

test('user can create item', async ({ authenticatedPage }) => {
  await authenticatedPage.goto('/items/new');
  // Already logged in, no setup needed
});

API setup is 10x faster than clicking through UI. Save E2E for testing UI, not for creating test data.

The Flakiness Problem

E2E tests are flaky. Network delays. Animations. Race conditions. Accept it and build defenses.

test('handles slow network gracefully', async ({ page }) => {
  // Simulate 3G connection
  await page.route('**/api/**', async route => {
    await new Promise(r => setTimeout(r, 2000));  // 2s delay
    await route.continue();
  });

  await page.goto('/dashboard');

  // Loading state should appear
  await expect(page.getByTestId('loading-spinner')).toBeVisible();

  // Then data loads
  await expect(page.getByText('Welcome')).toBeVisible({ timeout: 10000 });
});

That test catches "loading state never shows" and "loading state never disappears" bugs. Both happen. Both are invisible in fast network tests.

// Wait for network to be idle before asserting
await page.waitForLoadState('networkidle');

// Or wait for specific request
await Promise.all([
  page.waitForResponse(resp => resp.url().includes('/api/items') && resp.status() === 200),
  page.getByRole('button', { name: /save/i }).click(),
]);

waitForResponse is better than waitForTimeout. It waits for the right thing, not "hopefully long enough."

Error Paths: The Tests Everyone Skips

Happy paths are easy. Error paths reveal bugs.

test('shows helpful error when backend is down', async ({ page }) => {
  await page.route('**/api/**', route => route.abort('connectionfailed'));

  await page.goto('/dashboard');

  await expect(page.getByText(/unable to connect/i)).toBeVisible();
  await expect(page.getByRole('button', { name: /retry/i })).toBeVisible();
});

test('handles session expiry gracefully', async ({ page, context }) => {
  // Start logged in
  await context.addCookies([{
    name: 'session',
    value: 'expired-token',
    domain: 'localhost',
    path: '/',
  }]);

  // API returns 401
  await page.route('**/api/users/me', route =>
    route.fulfill({ status: 401, json: { detail: 'Session expired' } })
  );

  await page.goto('/dashboard');

  // Should redirect to login with message
  await expect(page).toHaveURL('/login');
  await expect(page.getByText(/session expired/i)).toBeVisible();
});

Session expiry is a user experience. Test it. "Redirect to login" isn't enough. "Redirect to login with a helpful message" is.

The Gate

e2e:
  stage: e2e
  image: mcr.microsoft.com/playwright:v1.48.0-jammy
  services:
    - name: postgres:16
      alias: db
  variables:
    DATABASE_URL: postgresql+asyncpg://postgres:postgres@db:5432/test
    POSTGRES_HOST_AUTH_METHOD: trust
    BASE_URL: http://localhost:5173
    BACKEND_URL: http://localhost:8000
  before_script:
    - pip install uv
    # Start backend
    - cd backend
    - uv sync --frozen
    - uv run alembic upgrade head
    - uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 &
    - cd ..
    # Start frontend
    - cd frontend
    - npm ci
    - npm run dev -- --host &
    # Wait for services
    - npx wait-on http://localhost:8000/health http://localhost:5173 --timeout 60000
  script:
    - cd frontend
    - npx playwright test
  artifacts:
    when: always
    paths:
      - frontend/playwright-report/
      - frontend/test-results/
    expire_in: 1 week
  allow_failure: false
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

wait-on instead of sleep. It polls until the services respond. No more "is 30 seconds enough?" questions. It waits exactly as long as needed.

when: always on artifacts is non-negotiable. Failed tests need their traces, screenshots, and videos. That's where the debugging happens. Don't lose them.

Copy, paste, adapt. It works.

The Point

Unit tests verify pieces. E2E tests verify the system. Both pass? The code works. One fails? You know where.

E2E tests are slow. Run them on critical paths only. Login. Registration. Checkout. Password reset. The flows that cost money when they break.

The trace is the superpower. A test fails in CI. You download the trace. You click through every step. You see exactly what the browser saw. You fix the bug in minutes instead of hours.

Playwright handles the browser. CI handles the infrastructure. You handle the test logic. Everything else is automated.

That's the deal.

The Python–TypeScript Contract

nicolas.vbgh — Tue, 10 Feb 2026 12:12:00 +0000

The uncomfortable situation

Backend tests pass. Frontend tests pass. Each side works in isolation. But do they work together?

Backend changes API. Frontend breaks. Nobody notices until production.

You rename a field from userName to username. Backend tests pass. Frontend tests pass—they mock the API anyway. Everything is green. You deploy. Production breaks because frontend expects userName but backend sends username.

This happens more often than anyone wants to admit.

The Problem With Mocks

Frontend tests mock the API. They have to—you can't run the real backend in every test. But mocks lie. They return what you told them to return, not what the backend actually returns.

Backend changes. Mocks don't. Tests pass. Production fails.

The solution: a single source of truth that both sides must follow.

OpenAPI as the Contract

FastAPI generates OpenAPI specs automatically from your type hints:

@router.post("/users", response_model=UserResponse)
async def create_user(user: UserCreate) -> User:
    ...

No extra work. Your types become the spec. The spec becomes the contract.

{
  "paths": {
    "/users": {
      "post": {
        "requestBody": { "$ref": "#/components/schemas/UserCreate" },
        "responses": {
          "200": { "$ref": "#/components/schemas/UserResponse" }
        }
      }
    }
  }
}

This file lives in the repo. Both sides must match it.

Orval: Generated TypeScript Client

Orval reads the OpenAPI spec and generates TypeScript. Not just types—full API clients with the HTTP layer baked in.

Configuration lives in orval.config.ts:

export default defineConfig({
  api: {
    input: '../shared/openapi.json',
    output: {
      target: './src/api/generated/endpoints.ts',
      schemas: './src/api/generated/models',
      client: 'react-query',
      mode: 'tags-split',
    },
  },
});

Run npx orval and you get:

// Generated - don't edit
export const useCreateUser = (
  options?: UseMutationOptions<UserResponse, Error, UserCreate>
) => {
  return useMutation({
    mutationFn: (userCreate: UserCreate) => createUser(userCreate),
    ...options,
  });
};

export const createUser = (userCreate: UserCreate): Promise<UserResponse> => {
  return customFetch<UserResponse>({
    url: '/users',
    method: 'POST',
    data: userCreate,
  });
};

React Query hooks out of the box. Mutations, queries, cache invalidation patterns. All typed.

You can also generate:

Axios clients — client: 'axios'
Fetch clients — client: 'fetch'
SWR hooks — client: 'swr'
Zod schemas — for runtime validation on top of compile-time types

The mode: 'tags-split' option generates one file per API tag. Clean separation. users.ts, products.ts, orders.ts. Import only what you need.

No manual API client. No type drift. The types always match the spec because they're generated from it.

Backend renames userName to username? The generated types change. TypeScript screams at every place in the frontend that still uses the old name. You fix it before it ships.

The Workflow

Backend changes the API
OpenAPI spec updates (FastAPI does this automatically)
Run npm run codegen in frontend
Generated types update
TypeScript catches breaking changes
Fix the frontend
CI validates everything matches

No coordination meetings. No "hey did you update the frontend?" The types enforce the contract.

The Gate

Two checks. Backend spec must match reality. Frontend types must match spec.

validate:openapi:
  stage: contract
  image: python:3.12-slim
  services:
    - name: postgres:16
      alias: db
  variables:
    DATABASE_URL: postgresql://postgres:postgres@db:5432/test
  before_script:
    - pip install uv && cd backend && uv sync --frozen
  script:
    - cd backend && uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 &
    - sleep 5
    - curl -s http://localhost:8000/openapi.json > /tmp/live-spec.json
    - diff shared/openapi.json /tmp/live-spec.json
  allow_failure: false

validate:codegen:
  stage: contract
  image: node:lts-slim
  before_script:
    - cd frontend && npm ci --prefer-offline
  script:
    - npm run codegen
    - git diff --exit-code src/api/generated
  allow_failure: false

validate:openapi — Starts the backend, fetches the live spec, compares to committed spec. Different? CI fails. Someone changed the API without updating the spec.

validate:codegen — Regenerates the TypeScript client, checks if it differs from what's committed. Different? CI fails. Someone updated the spec without regenerating the client.

Copy, paste, adapt. It works.

The Point

Backend and frontend speak different languages. Python here, TypeScript there. Without a contract, they drift apart. Small changes accumulate. Production breaks.

OpenAPI is the contract. Orval generates the types. CI validates the match.

Breaking changes are impossible to miss. Not "unlikely." Impossible. The pipeline catches them before they ship.

That's the deal.

Frontend Tests

nicolas.vbgh — Sun, 08 Feb 2026 19:22:09 +0000

The UI Gate

Backend tested. API returns correct data. But the button that calls it? The form that submits? That's frontend territory.

Vitest Over Jest

Jest is slow. Vitest runs natively in Vite. Same config, instant startup.

// vitest.config.ts
export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    setupFiles: ['./src/test/setup.ts'],
    globals: true,
  },
});

MSW: Fake the Network

Tests that hit real APIs are flaky. MSW intercepts at the network layer. Your code doesn't know it's being lied to.

// src/test/mocks/handlers.ts
export const handlers = [
  http.get('/api/users/me', () => {
    return HttpResponse.json({ id: 1, email: 'test@example.com' });
  }),
];

// src/test/setup.ts
export const server = setupServer(...handlers);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

Testing Library

Don't test implementation. Test behavior.

test('displays user email after load', async () => {
  render(<UserProfile />);
  expect(screen.getByText(/loading/i)).toBeInTheDocument();

  await waitFor(() => {
    expect(screen.getByText('test@example.com')).toBeInTheDocument();
  });
});

Use queries in order: getByRole > getByLabelText > getByText > getByTestId. If you need getByTestId, your UI might not be accessible.

What to Test

Interactions:

test('submits form and shows success', async () => {
  const user = userEvent.setup();
  render(<ContactForm />);

  await user.type(screen.getByLabelText('Email'), 'user@example.com');
  await user.click(screen.getByRole('button', { name: /send/i }));

  expect(screen.getByRole('button')).toBeDisabled();  // Loading state

  await waitFor(() => {
    expect(screen.getByText('Message sent')).toBeInTheDocument();
  });
});

The disabled check catches double-submit bugs.

Error states:

test('shows error on failure', async () => {
  server.use(
    http.post('/api/contact', () =>
      HttpResponse.json({ detail: 'Server error' }, { status: 500 })
    )
  );

  // ... submit form, see error message
});

Override the default handler. Test that the UI shows the error.

The Gate

test:frontend:
  stage: test
  image: node:lts-slim
  before_script:
    - cd frontend && npm ci
  script:
    - npm test -- --run --coverage
  allow_failure: false

--run makes Vitest exit after tests. Without it, CI hangs forever.

Copy, paste, adapt. It works.

The Point

Backend tests prove the API is correct. Frontend tests prove the UI is correct. Neither replaces the other.

A button that calls a working API but doesn't show the result? Backend tests pass. Users see nothing. Frontend tests catch it.

That's the deal.

Backend Tests

nicolas.vbgh — Thu, 05 Feb 2026 20:23:04 +0000

The Behavior Gate

Quality gates catch syntax. Tests catch behavior. A function that type-checks but returns garbage is worse than one that fails to compile.

The Async Trap

FastAPI is async. Get testing wrong and tests hang or miss real bugs.

# conftest.py
import asyncio
import pytest

@pytest.fixture(scope="session")
def event_loop():
    loop = asyncio.new_event_loop()
    loop.set_debug(True)  # Catches blocking calls
    yield loop
    loop.close()

set_debug(True) catches time.sleep() instead of asyncio.sleep(), synchronous I/O, libraries that claim async but aren't. One line, whole category of bugs.

Test Client

@pytest.fixture
async def client(session: AsyncSession) -> AsyncGenerator[AsyncClient, None]:
    app.dependency_overrides[get_session] = lambda: session
    async with AsyncClient(app=app, base_url="http://test") as client:
        yield client
    app.dependency_overrides.clear()

Endpoint code doesn't know it's being tested. Runs exactly like production.

What to Test

Service layer:

async def test_create_user(session: AsyncSession):
    user = await create_user(session, email="test@example.com", password="secret")
    assert user.password != "secret"  # Should be hashed

Error cases:

async def test_register_duplicate(client: AsyncClient, session: AsyncSession):
    await create_user(session, email="taken@example.com", password="secret")
    await session.commit()

    response = await client.post("/auth/register", json={
        "email": "taken@example.com", "password": "different"
    })
    assert response.status_code == 409  # Not 500

409 Conflict means you caught it intentionally. 500 means you caught it in a crash.

The Gate

test:backend:
  stage: test
  image: python:3.12-slim
  services:
    - postgres:16
  variables:
    DATABASE_URL: postgresql+asyncpg://postgres:postgres@db:5432/test
  before_script:
    - pip install uv && cd backend && uv sync --frozen
    - uv run alembic upgrade head
  script:
    - uv run pytest -v --cov=app --cov-report=term-missing --cov-report=html
  allow_failure: false

Copy, paste, adapt. It works.

The Point

Tests are the safety net. Refactor with confidence. Ship knowing the code works.

That's the deal.

CI-Embedded Security

nicolas.vbgh — Wed, 04 Feb 2026 20:01:19 +0000

Check before you wreck

Linters catch your mistakes. Type checkers catch your assumptions. But what about security? That's a different beast entirely.

Three attack surfaces. Three different problems.

Dependencies — Other people's code. You install a package. It works. Six months later, someone discovers a critical vulnerability. It's been in your production code the whole time. You had no idea.

Your code — The stuff you write. SQL injection. Hardcoded secrets. Unsafe regex. The classics. AI generates these patterns constantly. So do humans. Nobody's immune.

Secrets — API keys. Passwords. Tokens. One accidental commit and it's in your git history forever. Scrubbing it is a nightmare.

You can't manually track thousands of CVEs. You can't manually review every line for security anti-patterns. You can't grep every commit for leaked credentials.

So I let robots do all three.

Trivy: The Customs Officer

Every merge request gets scanned. Every dependency gets checked. HIGH and CRITICAL vulnerabilities block the merge. No exceptions.

trivy:backend:
  stage: security
  image: aquasec/trivy:latest
  script:
    - trivy fs --severity HIGH,CRITICAL --ignore-unfixed --scanners vuln backend/
  allow_failure: false

trivy:frontend:
  stage: security
  image: aquasec/trivy:latest
  script:
    - trivy fs --severity HIGH,CRITICAL --ignore-unfixed --scanners vuln frontend/
  allow_failure: false

Two jobs. Backend and frontend. Both must pass.

The flags that matter:

--severity HIGH,CRITICAL — LOW and MEDIUM vulnerabilities create noise. Hundreds of alerts, most theoretical. Focus on what's actually exploitable.

--ignore-unfixed — Some vulnerabilities have no patch yet. You can't fix what doesn't have a fix. Don't block on the impossible.

--scanners vuln — Trivy can scan for misconfigurations, secrets, licenses. Too much at once is overwhelming. Start with vulnerabilities.

When it catches something:

backend/requirements.txt
========================
Total: 1 (HIGH: 1, CRITICAL: 0)

┌─────────────┬────────────────┬──────────┬─────────────────────┐
│   Library   │ Vulnerability  │ Severity │   Fixed Version     │
├─────────────┼────────────────┼──────────┼─────────────────────┤
│ cryptography│ CVE-2023-XXXXX │ HIGH     │ 41.0.0              │
└─────────────┴────────────────┴──────────┴─────────────────────┘

CI fails. You see exactly which package, which CVE, which version fixes it. Update the package. CI passes. Done.

Bandit: The Python Inspector

Trivy watches the door. Bandit watches the Python code.

Static analysis for security issues. SQL injection. Hardcoded passwords. Dangerous function calls. Shell injection. The stuff that ends careers.

bandit:backend:
  stage: security
  image: python:3.11-slim
  before_script:
    - pip install bandit
  script:
    - bandit -r backend/app -ll -ii
  allow_failure: false

The flags that matter:

-r backend/app — Recursive scan of the source directory.

-ll — Only medium and high severity. Low severity is too noisy.

-ii — Only medium and high confidence. Bandit guesses sometimes. Filter the guesses.

Run it locally first:

bandit -r backend/app -ll -ii

What it catches:

>> Issue: [B608:hardcoded_sql_expressions] Possible SQL injection
   Severity: Medium   Confidence: Medium
   Location: backend/app/api/routes/users.py:45
   More Info: https://bandit.readthedocs.io/en/latest/...

44      query = f"SELECT * FROM users WHERE id = {user_id}"
45      cursor.execute(query)

Classic string interpolation in SQL. Use parameterized queries instead.

eslint-plugin-security: The Frontend Inspector

Same idea for TypeScript. Security-focused ESLint rules.

npm install -D eslint-plugin-security

Add to your eslint.config.js:

import security from 'eslint-plugin-security';

export default [
  // ... other configs
  security.configs.recommended,
  {
    rules: {
      // Too noisy for frontend
      'security/detect-object-injection': 'off',
      'security/detect-possible-timing-attacks': 'off',
    },
  },
];

Why disable those rules?

detect-object-injection — Flags every arr[i] and obj[key]. Thousands of false positives.

detect-possible-timing-attacks — Flags password comparisons. Frontend form validation isn't a timing attack vector. That's a server-side concern.

What it keeps:

detect-unsafe-regex — ReDoS protection
detect-eval-with-expression — eval() abuse
detect-child-process — Shell injection
detect-non-literal-require — Dynamic requires

Now npm run lint catches security issues. CI already runs lint. No extra job needed.

Gitleaks: The Secret Hunter

The other scanners check code quality. Gitleaks checks for accidents.

API keys. Database passwords. JWT secrets. One commit and they're in your history forever.

gitleaks:
  stage: security
  image:
    name: zricethezav/gitleaks:latest
    entrypoint: [""]
  script:
    - gitleaks detect --source . --verbose
  allow_failure: false

It scans the entire git history. Every commit. Every branch. Every file that ever existed.

When it catches something:

Finding:     POSTGRES_PASSWORD: SuperSecretPassword123
Secret:      SuperSecretPassword123
RuleID:      generic-api-key
File:        docker-compose.yml
Line:        9
Commit:      abc123...

Game over. You committed a secret.

The noise problem:

Gitleaks is paranoid. It will flag example passwords in docs. Test JWT tokens. Template files with placeholder values.

Solution: .gitleaks.toml at the root:

[extend]
useDefault = true

[allowlist]
  description = "Allowlisted files and patterns"

  paths = [
    '''infra/\.env\..*\.template''',
    '''docs/.*\.md''',
    '''docker-compose\.yml''',
  ]

Template files. Documentation. Local dev config. Not production secrets.

The Gate

Five jobs. One stage. All must pass.

stages:
  - security

trivy:backend:
  stage: security
  image: aquasec/trivy:latest
  script:
    - trivy fs --severity HIGH,CRITICAL --ignore-unfixed --scanners vuln backend/
  allow_failure: false

trivy:frontend:
  stage: security
  image: aquasec/trivy:latest
  script:
    - trivy fs --severity HIGH,CRITICAL --ignore-unfixed --scanners vuln frontend/
  allow_failure: false

bandit:backend:
  stage: security
  image: python:3.11-slim
  before_script:
    - pip install bandit
  script:
    - bandit -r backend/app -ll -ii
  allow_failure: false

gitleaks:
  stage: security
  image:
    name: zricethezav/gitleaks:latest
    entrypoint: [""]
  script:
    - gitleaks detect --source . --verbose
  allow_failure: false

Plus eslint-plugin-security runs with the lint job. No extra CI config.

Copy, paste, adapt. It works.

SCA vs SAST vs Secrets

Three acronyms. Three different things.

SCA (Software Composition Analysis) — Trivy. Scans dependencies. "Is this library vulnerable?"

SAST (Static Application Security Testing) — Bandit, eslint-plugin-security. Scans your code. "Did you write something dangerous?"

Secrets Detection — Gitleaks. Scans git history. "Did you commit something you shouldn't have?"

You need all three. A secure library won't save you from SQL injection. Clean code won't save you from a leaked API key. Secret scanning won't save you from a vulnerable dependency.

Belt, suspenders, and a backup belt.

The Point

I don't track CVEs manually. I don't read security newsletters. I don't grep commits for passwords.

The scanners run on every merge request. Vulnerable dependencies can't reach main. Dangerous code patterns can't reach main. Leaked secrets can't reach main.

Security I don't have to think about.

That's the deal.

TypeScript or Tears

nicolas.vbgh — Tue, 03 Feb 2026 20:00:25 +0000

Frontend Quality Gates

Backend linters catch async footguns. Type checkers prevent runtime explosions. Now the frontend's turn.

JavaScript fails silently. That's the whole problem in one sentence.

You call a function with the wrong arguments. It runs. You access a property that doesn't exist. It runs. You forget to handle null. It runs. Everything runs. Nothing works. Users complain. You have no idea why.

This is fine. Everything is fine.

Just kidding. This is chaos. And like the backend, none of this is even testing yet. We're just checking that the code isn't obviously broken before we bother running actual tests.

The bar is still on the floor. Let's at least step over it.

TypeScript: Because JavaScript Trusts You Too Much

JavaScript has no types. This was a design decision. It was wrong.

function processUser(user) {
  return user.name.toUpperCase();
}

What is user? An object? A string? A promise? JavaScript doesn't know. JavaScript doesn't care. JavaScript believes anything is possible.

JavaScript is an optimist. You shouldn't be.

TypeScript strict mode forces you to say what things are:

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

Now the compiler yells at you:

// TypeScript rejects this
function processUser(user) {  // Error: implicit 'any'
  return user.name.toUpperCase();
}

// TypeScript accepts this
function processUser(user: User): string {
  return user.name.toUpperCase();
}

Is it annoying? Yes. Does it catch bugs before users do? Also yes. That's the trade.

I use strict: true and noUncheckedIndexedAccess. The second one is particularly annoying. It assumes array access might return undefined. Because it might. And you should handle that.

ESLint: The Nitpicker You Need

TypeScript catches type errors. ESLint catches everything else.

Unused variables. Inconsistent formatting. Dangerous patterns. That console.log you left in production code. ESLint notices. ESLint judges.

I use the Airbnb style guide. It's opinionated, strict, and battle-tested. Thousands of engineers have argued about these rules so I don't have to.

// eslint.config.js
import { configs, extensions, plugins } from 'eslint-config-airbnb-extended';

export default [
  plugins.stylistic,
  plugins.importX,
  plugins.react,
  plugins.reactA11y,
  plugins.reactHooks,
  plugins.typescriptEslint,

  ...extensions.base.typescript,
  ...extensions.react.typescript,

  ...configs.react.recommended,
  ...configs.react.typescript,
];

One import. Hundreds of rules. TypeScript support, React hooks, accessibility, import ordering. All preconfigured.

no-explicit-any is the important one. It closes the escape hatch. You can't just type any and pretend you have type safety. You either type things properly or the build fails.

Some people find this restrictive. Those people debug production issues at 2 AM. I watch Netflix at 2 AM. Different choices.

Storybook: Because Components Lie

Here's a fun game: refactor a component, run the app, click around, ship it. Three months later, discover you broke the loading state on a page nobody visits often.

Components have many states. Happy path, error state, loading state, empty state, edge cases. You can't manually test all of them every time. You won't. I won't. Nobody will.

Storybook documents every state:

// Button.stories.tsx
export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Click me',
  },
};

export const Loading: Story = {
  args: {
    isLoading: true,
    children: 'Loading...',
  },
};

export const Disabled: Story = {
  args: {
    disabled: true,
    children: 'Nope',
  },
};

Run build-storybook in CI. If any component can't render in any state, the build fails. You broke something. Fix it before it ships.

Bonus: AI can read these stories. It understands what states exist. It generates code that handles them. Documentation that actually gets used.

The Gate

One job per check. When something fails, you know exactly what.

.frontend-quality:
  stage: quality
  image: node:lts-slim
  cache:
    key: npm-frontend-${CI_COMMIT_REF_SLUG}
    paths:
      - frontend/node_modules
      - ~/.npm
  before_script:
    - cd frontend
    - npm ci --prefer-offline
  allow_failure: false
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

eslint:
  extends: .frontend-quality
  script:
    - npm run lint

typecheck:
  extends: .frontend-quality
  script:
    - npm run typecheck

storybook:build:
  extends: .frontend-quality
  script:
    - npm run build-storybook --quiet
  artifacts:
    paths:
      - frontend/storybook-static
    expire_in: 1 week
    when: always

Three jobs. Same stage. Run in parallel.

The hidden job — .frontend-quality starts with a dot. GitLab won't run it directly. It's a template.

npm ci — Not npm install. ci is faster, stricter, and uses the lockfile exactly. No surprises.

--prefer-offline — Use cached packages when possible. Network is slow. Cache is fast.

Parallel execution — All three jobs run at the same time. ESLint fails? You see it immediately. TypeScript fails too? You see both. Fix them together.

Storybook artifacts — Keep the built Storybook around. when: always saves it even if the build fails. Useful for debugging why that one component broke.

When one job fails, you see exactly which one in the pipeline view. No scrolling through logs. No guessing.

eslint failed → style issues or dangerous patterns
typecheck failed → type errors
storybook:build failed → component can't render

None of this verifies that the code does what it should. That's what tests are for. This just verifies it's not obviously broken.

The bar is low. But you'd be surprised how many projects can't clear it.

Here's the full picture:

stages:
  - quality

.frontend-quality:
  stage: quality
  image: node:lts-slim
  cache:
    key: npm-frontend-${CI_COMMIT_REF_SLUG}
    paths:
      - frontend/node_modules
      - ~/.npm
  before_script:
    - cd frontend
    - npm ci --prefer-offline
  allow_failure: false
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

eslint:
  extends: .frontend-quality
  script:
    - npm run lint

typecheck:
  extends: .frontend-quality
  script:
    - npm run typecheck

storybook:build:
  extends: .frontend-quality
  script:
    - npm run build-storybook --quiet
  artifacts:
    paths:
      - frontend/storybook-static
    expire_in: 1 week
    when: always

Copy, paste, adapt. It works.

The Point

Frontend code fails in creative ways. Silent failures. Runtime errors. "It works on my machine" but not in Safari. Components that render fine until you pass them unexpected props.

I can't catch all of this manually. My attention span isn't that good. Nobody's is.

So I automate the obvious stuff:

Types must be explicit
Code must follow consistent patterns
Components must render without crashing

The machines catch what I miss. The pipeline blocks what I'd regret.

Same deal as the backend. Write the rules once. Enforce them forever.

The Linter That Yells

nicolas.vbgh — Wed, 28 Jan 2026 20:19:44 +0000

Backend Quality Gates

We picked the boring stack. Python. FastAPI. The technologies AI understands. Now we make sure AI doesn't write garbage.

Code reviews are a beautiful fantasy we tell ourselves. "Someone will catch my mistakes." No they won't. They're checking Slack. They're thinking about lunch. They're wondering if that meeting could've been an email.

Meanwhile, your time.sleep() sits there in async code, waiting to murder production at 3 AM on a Saturday. Nobody will catch it. Nobody ever does.

So I stopped pretending humans review code. I let robots do it. Robots don't get hungry. Robots don't have feelings. Robots are perfect for this job.

And here's the kicker: none of this is even testing. Not a single test runs. This is just linting. Glorified spell-check for code. We haven't even started verifying that the code does what it's supposed to do. We're just making sure it's not obviously broken before we bother checking if it works.

The bar is on the floor. And most codebases still trip over it.

Ruff: Because Life Is Too Short for Slow Linters

Remember pylint? You'd run it, go make coffee, come back, still running. So everyone disabled it. Problem solved. Also: problems not solved at all.

Ruff is written in Rust. It runs in milliseconds. You can't even alt-tab fast enough to avoid it.

[tool.ruff.lint]
select = [
    "E",      # pycodestyle errors
    "W",      # pycodestyle warnings
    "F",      # pyflakes (undefined names, unused imports)
    "I",      # isort (import ordering)
    "B",      # flake8-bugbear (common bugs)
    "C4",     # flake8-comprehensions
    "UP",     # pyupgrade (modern syntax)
    "ASYNC",  # flake8-async (async safety)
]

That ASYNC rule at the bottom? That's the one that saves your weekends.

The Async Footgun

Here's how to tank your server in one line:

async def fetch_data():
    time.sleep(1)  # Looks innocent. Isn't.
    return await get_data()

This blocks the entire event loop. Every user. Every request. Everything stops while your code takes a little nap. No error. No warning. Just... silence. And then your phone rings at 3 AM.

"The site is slow."

No kidding. You put time.sleep() in async code.

Ruff catches this:

ASYNC100: blocking call `time.sleep` in async function

The fix takes two seconds:

async def fetch_data():
    await asyncio.sleep(1)  # Look ma, no blocking
    return await get_data()

I make this mistake weekly. Sometimes daily. My brain refuses to learn. Fortunately, Ruff doesn't care about my brain. Ruff just yells. That's the relationship.

MyPy: Because "It Works" Is Not a Type

Python is dynamically typed. This means you can write this:

def process(data):
    return data.upper()

What is data? Could be a string. Could be a list. Could be your hopes and dreams. Python doesn't care. Python will try to call .upper() on anything. Python believes in you.

Python is wrong to believe in you.

MyPy strict mode fixes this by being incredibly annoying:

[tool.mypy]
strict = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
warn_return_any = true

Now you have to actually say what things are:

def process(data: str) -> str:
    return data.upper()

Is this more typing? Yes. Is this tedious? Also yes. Will this save you from a 4-hour debugging session because you passed a dict to a function expecting a string? Absolutely yes.

The AI also loves types. Give it typed code and it knows exactly what to generate. Give it untyped code and it hallucinates confidently. Your choice.

The Runtime Safety Net

Linters catch a lot. But not everything. Third-party libraries do weird things. Someone's "async" wrapper is actually sync. Life is full of disappointments.

So I run tests with the event loop in paranoid mode:

@pytest.fixture
def event_loop():
    loop = asyncio.new_event_loop()
    loop.set_debug(True)
    loop.slow_callback_duration = 0.1  # 100ms = you're blocking
    yield loop

Anything takes longer than 100ms? Test fails. Loudly. Rudely. Exactly as it should.

Belt and suspenders. Because I've seen things. Things that work perfectly locally and explode in production. Things that pass every test and still somehow break. Plan accordingly.

The Gate

One job per check. When something fails, you know exactly what.

.backend-quality:
  stage: quality
  image: python:3.12-slim
  variables:
    UV_CACHE_DIR: .uv-cache
  cache:
    key: uv-backend-${CI_COMMIT_REF_SLUG}
    paths:
      - .uv-cache
  before_script:
    - pip install uv
    - uv sync --frozen --no-install-project
  allow_failure: false
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

ruff:check:
  extends: .backend-quality
  script:
    - uv run ruff check .

ruff:format:
  extends: .backend-quality
  script:
    - uv run ruff format --check .

mypy:
  extends: .backend-quality
  script:
    - uv run mypy .

Three jobs. Same stage. Run in parallel. When one fails, you see exactly which one in the pipeline view. No scrolling through logs to find the error.

The hidden job — .backend-quality starts with a dot. GitLab won't run it directly. It's a template. DRY without the copy-paste.

extends — Each job inherits the template. Same image, same cache, same rules. Only the script changes.

Parallel execution — All three jobs run at the same time. Faster feedback. If ruff and mypy both fail, you see both failures immediately. Fix them together instead of playing whack-a-mole.

allow_failure: false — On every job. This isn't a suggestion. Your MR sits there, rejected, until all three pass.

The pipeline doesn't care that it's Friday at 5 PM. The pipeline doesn't care that "it works on my machine." The pipeline is the most reliable colleague you'll ever have.

Here's the full picture:

stages:
  - quality

.backend-quality:
  stage: quality
  image: python:3.12-slim
  variables:
    UV_CACHE_DIR: .uv-cache
  cache:
    key: uv-backend-${CI_COMMIT_REF_SLUG}
    paths:
      - .uv-cache
  before_script:
    - pip install uv
    - uv sync --frozen --no-install-project
  allow_failure: false
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

ruff:check:
  extends: .backend-quality
  script:
    - uv run ruff check .

ruff:format:
  extends: .backend-quality
  script:
    - uv run ruff format --check .

mypy:
  extends: .backend-quality
  script:
    - uv run mypy .

Copy, paste, adapt. It works.

The Point

I could review code carefully. I could remember all the async gotchas. I could check every type hint manually.

I could also juggle chainsaws. Both are technically possible. Neither is a good idea.

The reality is: humans forget things. That's not a character flaw—that's human nature. The trick isn't to fight it. The trick is to build systems that work despite it.

I write the rules once. The machines enforce them forever. They never get tired. They never get distracted. They never think "eh, it's probably fine."

The linter catches what I forget. The type checker verifies what I assume. The pipeline blocks what I'd regret.

That's the deal.

Boring Is a Feature

nicolas.vbgh — Wed, 28 Jan 2026 19:55:13 +0000

Why I Let AI Choose My Technologies

The philosophy is clear: programming by coercion. Make the machine enforce quality. But which machine? Which stack?

Here's a confession: I didn't pick this stack because it's the best. I picked it because AI knows it by heart.

Python. FastAPI. TypeScript. React. PostgreSQL. Nothing exciting. Nothing cutting-edge. Nothing that will impress anyone at a conference.

That's the point.

The Training Data Advantage

AI generates code based on training data. More examples = better output. Simple as that.

You can use that fancy new Rust framework with 200 GitHub stars. AI will hallucinate half the API. You'll spend your evening fixing AI mistakes instead of watching your show.

Or you can use technologies with millions of examples in the training data. AI gets it right the first time. You ship faster.

I chose option two. My ego will recover.

Server Side

Python

Every AI coding benchmark uses Python. HumanEval, MBPP, SWE-bench—all Python. Coincidence? No. AI understands Python better than any other language.

async def get_user(user_id: int, db: AsyncSession) -> User | None:
    stmt = select(User).where(User.id == user_id)
    result = await db.execute(stmt)
    return result.scalar_one_or_none()

AI generates this correctly every time. Try the same in Scala, Go or Rust. Good luck.

FastAPI

Flask is fine. Django is fine. But FastAPI has something they don't: types everywhere and OpenAPI out of the box.

@router.post("/users", response_model=UserResponse)
async def create_user(
    user: UserCreate,
    db: AsyncSession = Depends(get_db),
) -> User:
    ...

AI reads this signature and knows exactly what to generate. Input types, output types, dependency injection—all explicit. No guessing.

SQLAlchemy + PostgreSQL

"Just write raw SQL, it's simpler."

Sure. And AI will generate SQL injection vulnerabilities, wrong column names, and type mismatches. I've seen it. Multiple times. In one afternoon.

SQLAlchemy gives AI structure:

stmt = select(User).where(User.id == user_id)

AI can't accidentally concatenate user input. The ORM pattern is type-safe by design.

I naturally chose relational databases—they enforce typing by design.

PostgreSQL because it's the industry standard: mature, stable, perfect migrations, unbelievable backward compatibility.

MySQL/MariaDB could work, but I prefer real open source without Oracle's shadow. And I'm still unable to rename a database without voodoo file manipulation—am I the only one shocked by this?

NoSQL with MongoDB or Neo4j looks cool, but I'll stick with boring PostgreSQL for type enforcement. AI has seen millions of examples. I'm guaranteed to run it seamlessly for years.

uv

This one's not about AI. It's about sanity.

uv sync    # 2 seconds instead of 45
uv run pytest

10-100x faster than pip. Deterministic builds. I'm not interested in watching never-ending package installations, even with Netflix on. I switched and never looked back.

Async

With 10 sync workers, a 200 ms request caps you at ~50 RPS (25 RPS at 400 ms) because each worker naps while Postgres thinks.
With async, the same setup can handle ~500 RPS (250 RPS at 400 ms) by multitasking instead of staring at the wall.

Python async used to be a footgun. AI would forget await constantly.

Now we have Ruff with async rules. AI still forgets await. The linter catches it. Problem solved.

# AI writes this (wrong)
result = db.execute(stmt)

# Ruff screams, AI fixes it
result = await db.execute(stmt)

This is programming by coercion in action.

The Frontend That Just Works

TypeScript (Strict Mode)

JavaScript has no types. AI doesn't know what functions expect. Refactoring is prayer-based.

TypeScript strict mode forces AI to be explicit:

function processUser(user: User): string {
  return user.name.toUpperCase();
}

AI knows the input. AI knows the output. AI generates correct code.

I use strict: true and noUncheckedIndexedAccess. Yes, it's annoying sometimes. That's the point.

React

Vue is great. Svelte is great. But AI has seen more React code than everything else combined.

const [user, setUser] = useState<User | null>(null);
const { data, isLoading } = useQuery(['user', id], fetchUser);

Standard patterns. Predictable hooks. AI generates this in its sleep.

The Infrastructure Rock

Docker

"Works on my machine" is not a deployment strategy.

Docker makes environments reproducible. AI knows Dockerfile patterns. Everyone wins.

CI/CD: The Rule of Power

YAML-based pipelines. Well-documented. AI generates correct CI configs.

More importantly: this is where the coercion happens. Every check, every gate, every "you cannot merge this". One file to rule them all.

Monorepo: One Home for Everything

/
├── backend/       # FastAPI
├── frontend/      # React
├── infra/         # Helm, k8s
└── .gitlab-ci.yml # The gatekeeper

Backend, frontend, infra—same repo. One clone. One branch. One PR.

"But separate repos are cleaner!" Sure. And now AI needs to:

Clone three repos
Keep them in sync
Make coordinated changes across repos
Hope the CI in repo A passes before repo B deploys

Good luck with that.

With a monorepo, AI sees everything. Change the API schema? AI updates the backend endpoint, the frontend types, and the OpenAPI spec. One commit. One pipeline. All checks run together.

The pipeline enforces consistency. Frontend types don't match backend? CI fails. Database migration missing? CI fails. Contract broken? CI fails. You can't ship half a feature.

Separate repos can't do this. You'd need cross-repo CI triggers, version pinning, deployment coordination. Complexity for complexity's sake.

AI works in one context. The pipeline validates one state. Ship with confidence.

The Humble Conclusion

I could have picked Rust—efficient memory management, blazing fast, amazing type system, solid async.

But AI struggles with Rust. Fewer examples, different patterns, even syntax errors.

So I use Python. And FastAPI. And all the boring stuff.

My side projects ship. My evenings are free. The stack is unremarkable.

That's the whole point.

Programming by Coercion

nicolas.vbgh — Wed, 28 Jan 2026 19:36:00 +0000

A Developer's Guide to High Quality Code

I build side projects in my spare time. The AI writes the code. I focus on design and architecture.

This sounds reckless. But here's the thing: my code works. Tests pass. Types check. No security vulnerabilities. CI is green.

Not because I'm careful. Because I literally cannot merge broken code. Not by choice. By design. My past self didn't trust my future self. He was right.

The Elegant Metaprogramming Disaster

Last week, I asked AI to fix a bug. It didn't work. I gave it the full traceback. Same error. Third attempt: it rewrote half the module. Fourth: it discovered metaprogramming. On a config file. The worst part? It was elegant. Beautiful useless code that solves no problem. Still the same error.

I was fixing a typo.

That's when I realized: AI doesn't lack power. It lacks a target. It's a workhorse without reins—give it a destination, it'll get there. Give it "go somewhere nice," and it'll run in circles until exhausted. Somewhere, but nowhere useful.

The Simple Fix

So now I write tests first. Because a test is a finish line. Green means done. Red means keep going. AI understands that.

Let me paint the picture. I tell Claude to add a feature. But this time, I write the test first. AI implements. Tests fail. AI tries again. Tests pass. Done.

Did I review those 200 lines one by one? No. I focus on what matters: the design, method signatures, architecture decisions. The tests. The stuff that shapes the codebase long-term. The linter catches the missing await. The type checker catches the wrong return type. That's their job, not mine.

This is programming by coercion. I don't fully trust AI-generated code. So I built a system where the only possible outcome is working code.

The Coercion principle

I don't trust:

AI's understanding of my codebase
Anyone's manual review of 500 lines
"I'll add tests later."

Manual review doesn't scale. Automated checks do.

So I set up the stack and the coercion pipe:

The Unremarkable Stack

Python. FastAPI. TypeScript. React. PostgreSQL.

Not because they're exciting. Because AI knows them cold. Millions of training examples. Fewer hallucinations. Better suggestions.

→ Why This Stack — Boring is a feature.

The Coercion Pipeline Saga

Here's what keeps the whole thing from falling apart:

The Pipeline — Each CI stage, what it catches, why it matters

Quality: Backend — Ruff, MyPy, async footguns
Quality: Frontend — ESLint, TypeScript strict, Storybook
Security — CI-Embedded Security - Check before you wreck
Tests: Backend — The Behavior Gate
Tests: Frontend — Vitest, MSW, testing without flakiness
The Python–TypeScript Contract — OpenAPI + Orval, the most important stage
E2E — Playwright, because unit tests lie
Performance — k6, Lighthouse, catching slowdowns early

The result: a pipeline where bad code physically cannot reach main. Not "shouldn't." Cannot.

The Uncomfortable Truth

AI is here. It's not going away. It writes code faster than you. That's a fact.

It also hallucinates, forgets context, and confidently breaks things. That's also a fact.

You can fight it, ignore it, or learn to work with it. I chose option three.

I define what success looks like. AI figures out how to get there. I bring the intent, AI brings the execution. AI has the horsepower. The pipeline keeps it on the road, channeling all that power in the right direction.

You can review every line the AI writes. Or you can build a system where it doesn't matter if you miss something.

I built the system. Now I spend my time where it matters.