DEV Community: Piotr Zielinski

Stop Hardcoding 301s: How I Built a Redirect Engine That Doesn't Break at 2 A.M.

Piotr Zielinski — Thu, 04 Jun 2026 09:57:43 +0000

Marketing wants an A/B landing page by Friday. Product wants to gracefully deprecate a legacy API without breaking old mobile clients. Growth wants ten thousand short links, and Ops does not want ten thousand Nginx edits.

At some point, a single return 301 in your CDN stops being a configuration problem and becomes a routing product. Someone has to answer, on every HTTP request: Given this host, path, query, and method—where does this visitor go, and with which status code?

I built that answer as a pipeline at LinkShift. Not a pile of special cases, but a fixed sequence of steps that runs the exact same way for real visitors and for the tools you use to test rules before rollout.

Here is how I designed a deterministic redirect engine, the pipeline that powers it, and the edge cases that kept me up at night so they don't have to keep you up.

Why "Usually Works" Is Not Enough

A redirect engine fails quietly. The browser follows a broken 302 and nobody files a ticket. The damage shows up days later in analytics: wrong campaign, wrong locale, or an infinite loop that only appears when two rules on the same host point at each other.

What I wanted early on was boring, bulletproof reliability:

Same inputs → same decision. Two engineers simulating the same request against the same rule set should get the same target URL.
Same resolution logic everywhere. Matching and destination resolution must not diverge between the "Test Rule" button in the dashboard and an actual click on a custom domain.
Guards before cleverness. Rate limits and access checks run before anyone evaluates a ternary conditional in a destination string.

Expressiveness is easy. Ordering is what saves you in production.

The Pipeline, Told as a Story

Picture a request hitting a hostname. Before the engine asks "which rule wins?", the request walks through a strict corridor of gates. Only then does it enter the rule loop.

Gate 1: The Host Has to Exist

If the hostname does not resolve to a domain or LinkShift subdomain in a domain group, the pipeline stops with a 404. There is no rule list to evaluate—the request never entered the tenant’s world.

Gate 2: Protection Runs First

Next comes the organization redirect rate limit. If the plan’s per-minute cap is exceeded, the engine returns 429 and does not redirect. Abuse and accidental traffic spikes should not become a DDoS against your customers’ destinations.

Then organization access runs: suspended accounts or plan limits yield a 402. This check also applies when you simulate rules from the API. A suspended org should not get useful routing previews that imply production would work.

Gate 3: The `robots.txt` Exception

This path is not a redirect rule. If the domain group serves a robots policy, it returns 200 with the configured body. Rate limiting and access checks already ran; crawlers see consistent policy without competing with marketing redirects.

Gate 4: The Rule Loop Begins

The engine loads redirect rules that are not deleted and not blocked, sorted in a strict order:

priority descending — Higher number wins the race to be considered first.
createdAt descending
id descending — A stable tie-breaker, not something you should design around.

For each rule, in that order, it asks a chain of questions. The first rule that produces a redirect target wins. The loop stops. Everyone else is ignored.

Here is the mental model your team has to internalize: First rule that produces a target wins—not "first rule whose path matched."

Does the HTTP method match? (e.g., GET, POST)
Does the source match? Plain paths respect pathMatch and queryMatch. Regex sources apply against the path or the full original URL. Wildcards (*) catch everything else.
Is this a link map or dynamic rule?
Link maps: Match a prefix (/go), extract a key, look up static HTTPS URL. Miss? Continue to next rule.
Dynamic rules: Resolve regex capture groups ($1), placeholders, and ternaries.
Is the target safe? Absolute URLs go through a destination blacklist. Blocked host → 403. Blacklist infrastructure failed? Fail closed → 503.
Redirect. Issue the status code (301, 302, 307, or 308) and the resolved target.

If no rule produces a target, the request ends in 404.

5 Edge Cases That Look Like Bugs (But Aren't)

These are the lessons I wish I had read before I debugged my first "impossible" redirect.

1. "Matched" is not the same as "Redirected"

A link map miss without a fallback skips to the next rule. A dynamic rule can match the path and method but still fail resolution in ways that yield no target. Design explicit catch-alls at lower priority instead of assuming "no match" and "match but no URL" behave identically.

2. Priority is part of your API contract

Never build business logic on database tie-breakers (createdAt). If two rules must never compete ambiguously, give them different priority values. Catch-alls (source: "*") belong at the bottom unless you enjoy explaining why a new experiment stopped all traffic.

3. `queryMatch` is where campaigns go to die

For a short-link prefix like /go, you almost always want queryMatch: ignore so /go/summer?utm=email still resolves the key summer.

But for a regex rewriting www to apex that must keep the query string, ignore can strip the very data you needed. The pipeline is deterministic; your configuration has to explicitly state what "match" means for query strings.

4. The destination string is a small program

Resolution order is fixed: $N substitution → placeholders → conditionals.

{
  "source": "*",
  "destination": "'{accept-language.primary:to_lower_case}' includes 'pl' ? /pl : /en",
  "queryMatch": "ignore",
  "priority": 20
}

This power buys you language-based routing or A/B testing without deploys. It also buys you footguns. If a conditional branch resolves to an empty string, the rule still wins. The engine does not fall through to the next rule. The client just gets a broken redirect.

5. Loops are multi-request, not single-hop

The engine returns exactly one redirect per request. If the target points to the same host with another matching path, the browser makes a new request and the full pipeline runs again. The engine will not detect that loop in a single hop. Multi-hop debugging belongs in trace tools, not in wishful thinking about the redirect service being psychic.

Link Maps vs. Dynamic Rules: Keep the Hot Path Dumb

Scale changes design. Ten thousand short links do not mean ten thousand redirect rules. They mean one prefix rule and a fast database table mapping keys to HTTPS URLs.

This split keeps the hot path predictable. The rule loop does something cheap (prefix match, key extract, map lookup). The heavy editorial work lives in the map. Mixing models—like trying to template map rows—would break the invariant that map lookups are static and instantly auditable.

Validate at Save, Guard at Runtime

I split safety across two phases:

At create/update: A validator rejects rules that cannot work. Regex $N without a regex source? Rejected. Conditional depth over the limit? Rejected. Destinational URLs are scanned for safety before they ever hit the database.
At request time: Rate limits and blacklist checks protect the platform. Blacklist infrastructure failure is fail-closed (no redirect).

Validation keeps bad logic out of the database. Runtime guards keep bad traffic from becoming someone else’s problem.

Simulate vs. Live: What Stays the Same?

The feature my customers rely on most is Simulate: sending sample requests against the current live rule set without counting as production traffic.

Simulate answers: "What URL would this request get right now?"
It does not answer: "Will we survive a traffic spike?"

Concern	Live Traffic	Simulate
Rule match & resolution	Yes	Yes
Organization access (`402`)	Yes	Yes
Redirect rate limit (`429`)	Yes	No
Destination blacklist	Yes	Optional

Simulate is for routing correctness; production guards are for survival. That distinction prevented a massive class of false confidence in LinkShift's CI/CD.

The Takeaway

If you are about to build this, sequence the pipeline on paper before you write the DSL. Decide sort order, decide what "winning" means, decide fail-open vs. fail-closed for safety dependencies. The ternary syntax and placeholders are the fun part; the corridor of gates and the rule loop semantics are what your users will actually rely on.

I run this pipeline every day at LinkShift to power programmable redirects on custom domains and managed subdomains. The same engine drives analytics, stored redirect tests, and batch simulations.

If you want the full step-by-step diagram and operator reference, the public docs walk through the live pipeline and edge cases in detail: Read the LinkShift Docs.

If you have war stories—empty ternary branches, query string surprises, redirect loops—I’d genuinely like to hear them in the comments. A predictable pipeline is only boring until one rule at priority 10 proves you wrong.

I build programmable redirects at LinkShift.app. If your team has outgrown static config files, come check it out.

One Markdown File, Two Worlds: How to Build Docs for Both Humans and AI Assistants

Piotr Zielinski — Wed, 03 Jun 2026 21:19:17 +0000

When building a modern SaaS product with an AI assistant ("Ask our docs"), you quickly hit a brutal realization about documentation design:

Humans want brevity, beautiful diagrams, clean UI, and zero noise.
LLMs want absolutely everything. Edge cases, exact dashboard click paths, API endpoint sequences, and hidden technical constraints.

The classic approach? Maintain two separate knowledge bases. One for humans (a beautiful public CMS) and one for AI (prompts, vector databases, or markdown files tailored for the bot).

The result? Both sources drift apart within exactly one week.

In our project, we took a different route. We write exactly one Markdown file, but our rendering pipeline processes it differently depending on whether it’s being read by a human in a browser or ingested by an AI agent into our RAG (Retrieval-Augmented Generation) context.

Here is how we built the simplest possible Single Source of Truth (SSoT) for both humans and AI.

💡 The Context: Why We Needed This

We are building LinkShift.app — a programmable redirect platform. Think of it as a smart layer on the edge where you define traffic routing using rules, dynamic link maps, and regex, instead of hard-coding messy redirects in your app or CDN.

For a developer tool like this, documentation isn't just an afterthought; it's a core feature. Our users build complex routing logic, so the UI needs to be crystal clear. At the same time, our AI assistant must understand the deep mechanics behind our rules engine, batch simulations, and fallback scenarios. We simply couldn't afford a knowledge gap between what the developer reads and what our AI knows.

🛠️ The Architecture: One File, Two Views

Our MarkdownRendererComponent (built with Angular and the marked parser) is not just a dumb Markdown-to-HTML translator. Before the text ever hits the screen, it goes through a lightweight pre-processing pass.

The entire process is controlled using simple, custom block directives (:::block-name).

Here is how the roles are split depending on who the audience is:

Document Element	Human Reader (Docs UI)	AI Assistant (RAG Context)
Standard Markdown	✅ Yes (Rendered to HTML)	✅ Yes (Raw text)
Infoboxes (`:::info`)	✅ Yes (Styled callouts)	✅ Yes (Textual context)
Mermaid Diagrams	✅ Yes (Graphical render)	✅ Yes (Raw text flow syntax)
Hidden from Humans (`:::ai-only`)	❌ Hidden (CSS `display: none`)	✅ Yes (Full text for LLM)
Author Scratchpad (`:::hidden-on-purpose`)	❌ Stripped entirely	❌ Stripped entirely

📝 How It Looks in Practice (Syntax)

For the technical writer or developer, it’s still just a standard .md file in the Git repository. However, they get to use a few "superpowers."

1. AI-Only Blocks (`:::ai-only`)

This is the secret sauce. This is where we drop extra context that would feel repetitive or bloated to a human engineer, but is absolute gold for an LLM.

### API Integration

To import domains, you need to hit the POST `/domains` endpoint.

:::ai-only
⚠️ Context for the bot: Remember to instruct the user that before calling 
POST `/domains`, they MUST first generate an organization token via 
`/auth/org-token`, otherwise they will receive a 403. Humans have this covered 
in the "Quickstart" section, but remind them in the chat if they ask about 403 errors.
:::

How it works:

For Humans: The pre-processor wraps this in a <div class="docs-ai-hidden" aria-hidden="true">. A simple CSS rule applies display: none. The text is physically there in the DOM (so if someone opens DevTools, they can see it—this is not for security!), but it doesn't ruin the page's readability.
For the AI: The backend loader reads the raw Markdown file directly into the vector store or prompt context, completely ignoring the CSS layer. The bot sees the instructions loud and clear.

2. Mermaid Diagrams for Everyone

Instead of uploading static images (which LLMs cannot read out of the box in a standard text-based RAG pipeline), we stick to Mermaid code blocks.

Note: We use standard Markdown code fences specifying mermaid as the language to draw flowcharts. (Dev.to’s parser currently struggles with rendering nested Mermaid blocks within examples, so I'm omitting the exact snippet here to keep this post readable!).

When our pipeline reads that Mermaid block:

In the browser: mermaid.run() executes on hydration, rendering a gorgeous visual chart for the human reader.
For the AI: The agent receives the raw text-based Mermaid code. Because modern LLMs are fantastic at understanding graph-based text syntax, they can flawlessly explain the flowchart to a user in chat or even generate an updated version of the chart in their response.

3. The Author Scratchpad (`:::hidden-on-purpose`)

Sometimes, documentation writers need to leave notes for themselves or the team (e.g., "TODO: update this after the v2.4 release").

:::hidden-on-purpose
Leaving this here because we are changing the edge engine logic in June 
and this entire paragraph will need a rewrite. ~Mark
:::

A utility function called stripHiddenOnPurposeMarkdown() runs a regex pass that nukes these blocks both before rendering the UI and before sending data to the bot. It is a private playground that stays strictly in the codebase.

🧠 Why This Boosts Developer Experience (DX)

Zero Knowledge Fragmentation: Everything related to a feature (the user-facing copy, the diagrams, and the hyper-technical AI hints) lives in one single file. A code change requires exactly one documentation update.
Git as the Source of Truth: Version control, Pull Requests, peer reviews—the entire documentation workflow follows your standard development pipeline.
Dead Simple Deployment: A single sync script (npm run docs:sync) builds the frontend bundle and simultaneously refreshes the AI bot's knowledge base in our backend.

⚠️ Lessons from Production: What to Watch Out For

This is NOT a security boundary: The ai-only blocks are hidden via client-side CSS. Do not put API keys, passwords, or highly sensitive internal business strategies there. For truly confidential data (like internal infrastructure runbooks), we use a completely separate, private directory that never gets bundled into the public documentation repo.
Keep Your Parsers in Sync: The text stripping utilities must behave identically on both the frontend and the backend. We highly recommend keeping these parser utilities in a shared workspace folder (e.g., shared/utils/), so a regex adjustment in one place doesn't accidentally break formatting in the other.

Conclusion

You don't need to adopt heavy, complex headless CMS platforms or enterprise-grade documentation frameworks just to survive the AI era. Sometimes, all it takes is taking good old Markdown, writing a dozen lines of pre-processing code, and elegantly decoupling your data layer from your presentation layer.

By doing this, our users get a clean, minimalist reading experience, while our AI assistant handles highly specific technical edge cases like an absolute expert. Everybody wins.

Try It Out!

Curious to see how this dual-view system looks in production? Head over to the LinkShift Documentation and try asking the AI agent a technical question about our programmable redirects. See if you can spot the difference between the visual docs and the bot's deep context! 😉

If you are dealing with similar RAG vs. UI documentation challenges, let me know in the comments how you solved them!

How to Cheat LLM Context: A Lightweight AI Doc Assistant Architecture

Piotr Zielinski — Tue, 02 Jun 2026 19:48:40 +0000

Dropping your entire Markdown documentation folder into an LLM prompt sounds easy - until you see the API bill. Large contexts mean large costs, especially when users ask repetitive or highly specific questions.

When building the documentation assistant for my project, LinkShift.app (a programmable redirect and link-mapping platform running on the edge), I knew the learning curve would be steep for users dealing with Regex, Liquid templates, and edge routing rules. Instead of taking the easy route and watching my API budget melt, I designed a multi-tier, ultra-low-cost AI agent architecture.

Here is how I solved token bloat and kept response times blazing fast.

The Tiered Architecture at a Glance

Instead of throwing a massive model at the full chat history and documentation for every single query, the system filters the request through three distinct phases:

User Request -> [1. Receptionist (gpt-5.4-nano)] -> Intent Filtering & File Routing
                                                                  |
                                                                  v
User Response <- [3. Response Gen (gpt-5.4-mini)] <- [2. Inject Relevant Files (Usually 3-6)]

Step 1: Smart Data Ingestion (Preprocessing)

Feeding raw Markdown files dynamically to an LLM is incredibly inefficient.

All 28 Markdown files of my documentation were pre-processed and summarized beforehand using a tiny gpt-5.4-nano model.
For the OpenAPI/API Reference, I split the main schema by tags (endpoints). Each section got its own highly compressed summary.

Step 2: The "AI Receptionist" Guardrail

When a user asks a question, it doesn't touch the main, more expensive LLM right away. The first line of defense is a gpt-5.4-nano model acting as a "receptionist." It handles two critical tasks:

Intent Validation: It verifies if the query is actually relevant to LinkShift. This ensures no one is using my API budget to do their computer science homework.
File Routing: It scans the pre-made lightweight summaries and pinpoints the exact documentation files needed to answer the question. I set a safe upper limit of 10 files, but the model usually dynamically selects just 3-6 highly relevant ones.

The result? We only pass a fraction of the total documentation into the next stage.

Step 3: Precise Generation & The "Low-Token Context Hack"

Only now does the slightly heavier model, gpt-5.4-mini, enter the scene. It ingests the user's query and only the specific files isolated by the receptionist to compile a high-quality, hallucination-free answer.

The Chat History Hack:
Keeping full chat logs in memory quickly bloats the context window. To bypass this, every time gpt-5.4-mini responds, it also generates a single-sentence micro-summary of the conversation so far. On the next turn, I inject only this micro-summary instead of the entire chat history.

This keeps the context perfectly intact, answers lightning-fast, and the API bill down to literally pennies.

The Over-Engineering Syndrome

The best part about this whole setup? I spent days obsessing over this architecture, refining prompts, and stress-testing edge cases - despite currently having exactly zero users (free or paid).

It’s the classic indie hacker / software engineer trap: building a hyper-optimized, infinitely scalable infrastructure for massive traffic before making a single dollar.

On the bright side, the system is bulletproof, safe from wallet-draining exploits, and ready for whatever comes next.

If you want to test it out, try to break the receptionist guardrail, or just see how it handles technical queries, feel free to play with it here: linkshift.app/docs.

How do you handle context costs in your own LLM projects? Do you use a similar routing system, or do you prefer standard vector databases (RAG)? Let’s discuss in the comments!