DEV Community: Flude team

The Phantom That Wasn't There: How Unreliable grep Made Us Chase Ghosts

Flude team — Fri, 18 Sep 2026 04:58:58 +0000

One of the hardest stages in developing a documentation generator is alignment with legacy tools. When you migrate from an old, decades-proven proprietary generator to your own custom pipeline, you are obligated to prove that you haven't lost a single class.

We wrote an automated system that compared thousands of entities generated by the old tool with what our new Flude-based pipeline found. And one day, we stumbled upon a terrifying anomaly.

Anomaly in the Matrix

The alignment script happily reported: Flude found and generated documentation for a struct named GraphicsAsset and its smart pointer GraphicsAssetPtr.

The problem was that in the old, reference documentation, these entities didn't exist. At all.

According to our logic, if the legacy generator didn't find the class, it's highly likely this class simply doesn't exist, and our parser made a mistake somewhere, "gluing" someone else's names together. We had to check the source code.

Zero Results

We did what any engineer would do—we opened a terminal and ran a quick global text search (grep / ripgrep) across the entire multi-gigabyte codebase of our enterprise C++ product:

rg "GraphicsAsset" ./sdk_sources/

Result: 0 matches. Absolute emptiness.

We checked with case-insensitivity, we searched for the smart pointer. Nothing.

Panic: The Hallucinating Parser

It was a moment of genuine horror. The codebase didn't contain the string GraphicsAsset. But somehow, our parser hadn't just found this name; it had built a beautiful HTML page for it, complete with a list of methods, properties, and inheritance!

The conclusion seemed obvious: our parser had gone insane. It had started fabricating C++ classes out of thin air. Perhaps the logic for expanding complex macros had broken, or Doxygen's cache had become so corrupted that it started stitching pieces of different files into a single "Frankenstein".

We were already preparing to open the debugger and rewrite the token-linking logic in the core.

Autopsy of the Cache

Fortunately, before tearing apart the core codebase, we decided to look at the raw intermediate data. We went to the directory where Doxygen dumped its low-level XML, and searched there.

Suddenly, sitting quietly on the disk, was a file named struct_graphics_asset.xml. We opened it.

Inside was perfectly formed XML. It didn't look like a hallucination. Moreover, in the <location> tag, the parser pedantically pointed out exactly where it got this class:
Core/Include/Graphics/MaterialConfig.h:3006-3061

The Phantom Takes Flesh

We opened the MaterialConfig.h file and scrolled down to line 3006.

And there, in the very heart of a massive legacy header, hid a completely real, living struct:

struct CORE_ABSTRACT GRAPHICS_EXPORT GraphicsAsset {
    // ... dozens of lines of valid C++ code
};

It had always been there. The legacy generator simply couldn't parse it because of complex macros, but our Flude could.

So why did the global rg yield zero matches? In enterprise monoliths, there are always plenty of reasons. Perhaps the Core/Include path was listed in a tricky .gitignore, and the smart ripgrep ignored it. Perhaps the file had an exotic Windows encoding that broke the search. Perhaps it was a mounted submodule.

Conclusion

A global text search offered an absence of evidence as evidence of absence.

This case taught us a crucial rule: a text search is not a C++ parser. Trying to analyze the structure of a C++ monolith with regular expressions or grep is a path to disaster and false conclusions.

If you doubt your parser, never use text search as the arbiter. Trust only the raw dumps of the compiler itself or the Abstract Syntax Tree (AST). And most importantly: do not try to "fix" a bug in the core until you prove its existence in the actual source of truth.

But parsing and cache problems paled in comparison to our infrastructural challenges. From day one, our project was built as an ecosystem of several independent repositories. How this architecture turned into Git traps and nearly broke our Continuous Integration—read about it in the next episode.

Originally published on our blog: https://blog.flude.guide/blog/the-phantom-bug-grep

Also read us:

The Leak That Won't Die: How We Broke Python's tempfile

Flude team — Tue, 15 Sep 2026 03:52:53 +0000

Production crashes always happen suddenly. This time, the alarm was raised by the core C++ SDK developers. Their scheduled nightly build failed on the CI runner with a classic diagnosis: No space left on device.

We ran out of disk space. A quick post-mortem revealed that the /tmp folder was bursting with thousands of temporary directories. Their names all started the same way: ude_xml_. It was our code.

The Architecture of the Crash

As we've mentioned before, our engine handles Doxygen in a tricky way. We feed it source code, it spits out a massive XML dump, and we parse that dump. For every run, the engine created a temporary folder using tempfile.mkdtemp(). A dynamically generated Doxyfile was placed there, and Doxygen would dump hundreds of megabytes of XML into it.

The plan was simple: at the very end of the pipeline, a cleanup() function would run, executing an honest shutil.rmtree() on that folder. But the plan had a flaw. If the parsing failed with an exception, the pipeline aborted, cleanup() was never called, and a folder filled with megabytes of garbage was left stranded in /tmp forever.

Complaints started pouring in from teams building massive projects. The error was flaky. We tried wrapping the call in a try/finally block, but the engine's logic was smeared across dozens of classes. The leak persisted.

A False Sense of Security: Trusting the GC

How do you solve the problem of forgotten resource cleanup in Python? "Delegate the cleanup to the Garbage Collector (GC)!" we thought.

Instead of mkdtemp, we rewrote the logic to use the tempfile.TemporaryDirectory object. Its main advantage is that when the object is deleted from memory, its finalizer (__del__) automatically triggers the folder's deletion on disk.

To ensure the folder lived exactly as long as the engine needed it, we saved a reference to the object in a global list inside the manager class:

temp_dir_obj = tempfile.TemporaryDirectory(prefix="ude_xml_")
self._active_temp_dirs.append(temp_dir_obj)

It seemed like elegant, "pythonic" code. The object lives in the manager's memory and is automatically deleted when the script finishes.

The Fatal Mistake

We rolled out this "fix" to production. For a few days, the complaints stopped. We patted ourselves on the back and closed the issue. And then the CI runners started crashing again.

We missed one "tiny" detail. Hoping that objects are always deleted, and that the Garbage Collector works immediately, is a ticking time bomb.

In the case of giant C++ projects like Flude, the engine parsed dozens of modules sequentially. A new directory was created for each module. Because of a complex web of circular references in our parsers (e.g., an AST node referenced its parent class, and the class held a list of its children), the engine's objects weren't deleted immediately. They hung in memory, waiting for a full garbage collection cycle. And, of course, _active_temp_dirs stayed in memory too.

TemporaryDirectory objects piled up in RAM by the hundreds. But the worst part was this: when the GC finally got to them and called cleanup(), it triggered a massive synchronous deletion of files from the disk, blocking the main execution thread for several minutes. Because of this, other services on the server began failing due to timeouts.

The Real Fix

The conclusion of our investigation was grim: using finalizers to free heavy system resources is an anti-pattern. We couldn't control when the GC would trigger, which meant we couldn't control the disk I/O load.

we had to rewrite the pipeline's architecture so that the lifecycle of temporary folders was managed by strict with context managers, not the GC.

We introduced a strict rule: creating the folder and calling cleanup() must happen in the same place. If any part of the engine needs these files, it accesses them inside a with block, guaranteeing that upon exiting the block (even via an exception), the folder is deleted immediately.

To protect against regressions, we also added a "janitor"—a mechanism that forcibly checks /tmp before a build starts and cleans up any orphaned garbage.

logger.warning(
    f"Orphaned temporary directory found: {td.name}. "
    "Caller failed to invoke cleanup(). Force-cleaning now."
)

Conclusion

We learned a harsh lesson. Shifting the responsibility for system resources to Python's garbage collector is a direct path to disaster.

But our victory over the garbage was just the beginning. While we were wrestling with Python, the real enemy was lurking in the very heart of our infrastructure. We thought we had tamed Doxygen, but it soon took its revenge, forcing us to rewrite the entire parser from scratch. How a simple C++ construct drove the documentation generator insane—read about it in the next episode.

Originally published on our blog: https://blog.flude.guide/blog/the-leak-that-wont-die

Also read us:

The Illusion of Speed: A Two-Level Cache Can't Speed Up What Doxygen Can't Skip

Flude team — Thu, 10 Sep 2026 17:17:18 +0000

Every single full documentation rebuild ruthlessly executed doxygen.exe and parsed its massive XML output. The tool simply didn't care if you fixed a single typo in the comments or rewrote half the SDK. On real projects this translated into minutes of agonizing waiting after every push, even though the vast majority of the work could have been safely skipped.

Two Fingerprints for Cache Control

We built the caching scheme around two independent fingerprints to strictly divide responsibilities. The xml_fingerprint determines whether the Doxygen run can be skipped entirely. We compute it as a content hash spanning the binary, the effective Doxyfile, and the source tree. Modification time checks were thrown out immediately to prevent fresh CI checkouts from falsely invalidating the cache. The OUTPUT_DIRECTORY parameter also had to be excluded from the hash to avoid a circular dependency between the fingerprint and the generated files.

The second fingerprint, ir_fingerprint, decides the fate of parsing the generated XML into a ProjectCatalog structure. It incorporates the first hash but adds parser configuration like exclude_swig_internals and the logic hash. Any minor tweak to the parsing rules instantly invalidates the saved internal representation (IR). We managed to catch a potential state desync bug before writing any code thanks to a couple of independent AI review sessions.

Boundaries of Compute Optimization

The compute time cache abruptly stops at the IR boundary. The actual transformation of the ProjectCatalog object into final Markdown is calculated from scratch every time. Observant readers might spot a BuildCacheManager class in storage.py that handles a rendering cache. It operates purely on file I/O to protect local Hugo livereload from triggering falsely.

We dropped the idea of caching the render computation for very pragmatic reasons. Rendering a single page is heavily tied to global state, such as the sidebar.toml navigation tree and cross-links. Altering the taxonomy structure breaks the layout of dozens of files simultaneously, making invalidation tracking incredibly complex. Furthermore, Doxygen processing takes long minutes, while traversing the ready IR tree takes mere seconds.

Why the Speed Remains an Illusion

Our two-level cache only knows how to do one thing—completely skip a build step when fingerprints match. Doxygen physically lacks an incremental parsing mode and cannot run any faster. Any altered character in the sources forces us to endure a full parser run. True incrementality, where only the modified file gets recomputed, is fundamentally incompatible with a monolithic XML dump.

In the architectural plans for the next major version we have already documented dropping Doxygen in favor of direct AST construction via libclang or tree-sitter—the choice between the two hasn't been made yet; the requirements treat them as equal candidates of the same technical direction. Incrementality becomes a natural property of the tool there, instead of something bolted on top with fingerprints—but that same shift will force us to throw away and rewrite the existing caching logic entirely. For now, we had to face the harsh limits of the free GitHub Actions cloud, which pushed us to build our own self-hosted runner. In the next episode we cover how we escaped to our own hardware.

Originally published on our blog: https://blog.flude.guide/blog/illusion-of-speed-caching

Also read us:

Flude.guide: The Name We Had to Find Between Udemy, a Debugger, and nude.com

Flude team — Tue, 08 Sep 2026 03:38:44 +0000

When the time finally arrived to launch this blog, an uncomfortable reality surfaced. The internal working title "UDE" was completely dead on arrival. We faced problems far beyond simple domain availability. Someone else already owned ude.com and ude.io, but the fatal blow came from trademark law. The abbreviation is already a registered ® trademark—Universal Debug Engine, a well-known microcontroller debugging tool from Germany's PLS. Launching another developer tool under the exact same name guarantees a swift cease-and-desist letter. We preferred shipping software over arguing with corporate lawyers.

Three filters running in parallel

We started hunting for a four- or five-letter replacement built around the "ude" substring. The evaluation process was brutal—and immediate. Sound, SEO potential, and legal safety were checked simultaneously. Any candidate could trip an alarm on any axis. One strike instantly eliminated the word from contention.

Candidates like "nude", "dude", and "jude" crashed out on the sound check right away. Several variants barely registered as real English words. The archaic Scots term "blude" would confuse anyone outside of Edinburgh. Common words like "nude" or "dude" carry bizarre baggage that a strict technical reference manual desperately wants to avoid.

The word "Etude" survived slightly longer. It sounds pleasant and bypasses direct trademark violations. The fatal flaw hides in its marketability. A massive global cosmetics brand already dominates search results for that term. Trying to build a presence under that banner means fighting through endless irrelevant noise. The original "UDE" title suffered from a similar chronic condition. Even ignoring the legal threat, the abbreviation looks far too much like the Udemy course platform.

We eventually landed on "Flude". It possessed no magical qualities or overwhelming strengths. It simply stood as the first candidate that survived all three filters without breaking apart.

Claiming the right zone

With the name locked in, we needed a home on the internet. Premium extensions usually sit trapped in squatter portfolios. Buying a catchy short domain for thousands of dollars makes zero sense for a young project. We refused to negotiate with domain brokers.

A quick search showed availability in the .dev space at standard registrar pricing. It sounds reasonable, except that suffix heavily implies writing code and libraries. We needed a space dedicated to final technical documentation. The .guide extension sat wide open, cost barely anything, and literally described our product. The choice made itself. We secured a flawless match between our brand name and its actual function.

Maturing alongside the infrastructure

We locked down the domain while the brand was still baking internally. The new identity eventually cemented itself deep inside our infrastructure. We purged the outdated "ude-" prefix from all Cloudflare Pages projects. A massive single-day rename swept through both the user documentation and the engine repository.

Next time, we will dive into the illusion of speed. We will demonstrate why a clever two-layer cache of XML and syntax trees completely fails to accelerate a bottleneck baked deep inside Doxygen itself.

Originally published on our blog: https://blog.flude.guide/blog/flude-guide

Also read us:

Breaking Down Our Pipeline: From a Symlink Hack to Five Independent Deployments

Flude team — Fri, 04 Sep 2026 08:01:20 +0000

Flude's documentation pipeline survived for years the same way most internal tooling does. It just worked. Nobody in their right mind wanted to touch it. The engine package generated its API reference using a clunky symlink hack we mentioned in the escape-to-GitHub-Actions episode. Platform constraints forced our hand here. Free GitHub Pages limits site publishing to public repositories only. The engine's source code absolutely had to stay private. We bypassed this by running ln -s ../engine ./user-docs/engine during the CI build. The public user-docs repo quietly built a site out of someone else's code. Flude processed those files on the fly to push the final static result out the door.

That duct-tape setup actually got the job done. It also created a concrete wall of architectural coupling. Publishing a single line of API documentation required the private engine to leak its source into a public neighbor. The user-docs project got stuck carrying the weight of an external build process. We couldn't build or test the engine's docs in isolation. The entire toolchain only triggered from inside the documentation repo. Every single run pulled down megabytes of fresh code. The design-docs project suffered from the exact same disease on a smaller scale. Its GitHub Pages deployment ran centrally out of the giant Pipeline umbrella repo. It relied on an SSH deploy key to punch through into a completely different repository.

Finding a host that asks fewer questions

We weighed two escape routes for the engine. One option involved shipping the parsed intermediate representation as a versioned artifact like a wheel or GitHub Release. Downstream projects could grab that package and render the docs locally. That sounds clean on paper. In reality, it introduces a nightmare of schema versioning we desperately wanted to avoid. The brute-force approach won out in the end. The engine now parses, renders, and deploys its own reference from its own CI pipeline. Zero intermediate contracts. Zero artifact publishing rituals.

We still had to bypass the old GitHub Pages restriction. The platform demanded a public repo—so we ditched the platform. Cloudflare Pages offers a free tier that deploys finished build artifacts while completely ignoring repository visibility. The engine finally publishes its own reference while staying hidden from the world. The actual migration required nothing more than copying Doxyfile, hugo-site, and sidebar.toml directly into the engine repository. The generated content/ and public/ directories went straight into .gitignore. They no longer haunt our commit history as static fixtures.

We rolled this exact logic down the rest of the chain. Both design-docs and user-docs migrated to Cloudflare Pages. Each project received a dedicated deploy.yml workflow. GitHub Actions provides native read access to the runner's repository, making deploy keys obsolete. The old cloudflare/pages-action@v1 had already been archived by the community. We skipped the legacy tooling and moved all five repositories straight to the supported wrangler-action.

One token to rule them all

Our perfectly clean plan slammed into a brick wall of reality right about here. Every deployment requires a CF_API_TOKEN. The textbook reaction is generating a narrowly scoped token with least privilege for each repository. Cloudflare violently disagrees with this approach. You cannot scope an API token to a single Pages project. They grant permissions across the entire account—or nothing at all. Any "narrow" token we issued would instantly gain full access to our entire infrastructure. Worse yet, Cloudflare displays the token value exactly once during creation. If you miss it, you have to roll the credential entirely.

The rollout process turned into a timed sprint. We roll the token once. Then we distribute the new string across five repositories within a few frantic minutes. Everything happens through an interactive prompt. Secrets never touch a script, a file on disk, or a Slack message. Five independent repositories now share a single token—and a single rotation window.

Auditing the dead code

Once the deployments turned green, we had to ask ourselves a tough question. How much of this machinery was actually doing anything useful? The audit unearthed a pile of historical garbage. A repository_dispatch trigger from every submodule used to restart integration tests in the umbrella repo. It fired before the gitlink even bumped. The CI was aggressively testing a state that hadn't changed. We gutted that nonsense and replaced it with a simple six-hour schedule on the bump job itself. We lost absolutely nothing in speed because those PRs never auto-merged anyway.

The language test matrix in the umbrella repo turned out to be a carbon copy of the engine's internal CI. The original version even enforced a stricter coverage threshold. A job designed to verify the built site was quietly testing an architecture that died months ago. It merged Hugo's output with a VitePress tree to check cross-links. We had long since split them into separate Cloudflare Pages projects on different domains. The only connection left is a standard external link. You never spot these ghosts reading a clean architecture diagram. They only surface when you dig through the raw runner logs.

Severing the final tie

One tiny cross-repository hook remained. The failure-alert step in every workflow dynamically pulled a shared Telegram notifier from Pipeline at runtime. That single step required another authentication token. A supposedly independent repository was still reaching back to daddy for help. We copy-pasted that action file into every single project. Maintaining five copies instead of one shared source is the real cost of independence.

You are reading this blog on a site built with the exact same pattern. It uses self-deployment with zero external deploy keys. It runs its own copy of the notifier. It lives on that exact same Cloudflare architecture.

Next time, we'll explain how we hunted down a public name for this documentation. The original working title turned out to be locked behind corporate lawyers, sending us down a rabbit hole of weird domain names.

Originally published on our blog: https://blog.flude.guide/blog/decomposing-the-pipeline-monorepo

Also read us:

The 'if not 0:' Easter Egg: How Our AI Audit Found Dead Code in the Orchestrator

Flude team — Tue, 01 Sep 2026 05:12:56 +0000

We keep exposing the internals of our project without embellishment. Recently, we launched an autonomous AI audit across the entire engine core. The agent was tasked with cleaning up type hints, fixing docstrings, and deleting dead code. Living humans rarely get around to this kind of mundane technical hygiene.

The Find

The agent systematically combed through the files and stumbled inside ude/orchestrator.py. Inside the load_sidebar_toml function, it unearthed a fascinating piece of logic. We stared at the screen and couldn't quite believe our eyes.

toml_path = doc_dir / "sidebar.toml"
if not 0:
    if not toml_path.exists():
        raise UdeException(
            f"Required sidebar.toml not found in {doc_dir}. "
            "Every document directory must contain a sidebar.toml file."
        )

Zero in Python is interpreted as falsy. The expression not 0 always evaluates to true. The outer condition simply forced an extra indentation level and was guaranteed to execute every single time. It was a useless wrapper that stole a line in the stack trace from anyone trying to debug the application.

How It Got There

A quick git blame revealed the author and the creation time. The line sneaked in via PR #56 ("Feature/section 2.1 orchestrator library api"), part of a massive orchestrator refactoring. The developer temporarily disabled the block using if 0: for a quick local debugging session. They flipped the logic back with a negation, committed the changes, and forgot to remove the wrapper before the merge. The test suite happily passed. The behavior of the code remained completely unchanged.

This construct didn't break any functionality or open security vulnerabilities. It simply added pure cognitive noise. Everyone reading this file would freeze for a second, trying to decipher the sacred meaning behind the check. That extra second of confusion accumulates into hours of wasted time across thousands of lines of code.

The Fix

toml_path = doc_dir / "sidebar.toml"
if not toml_path.exists():
    raise UdeException(
        f"Required sidebar.toml not found in {doc_dir}. "
        "Every document directory must contain a sidebar.toml file."
    )

We deleted the wrapper and shifted the code to the left. The full test suite ran clean—731 passed, 0 failed, coverage holding at 98.12%. The system's behavior hasn't shifted a millimeter. Regular automated auditing pays off exactly through these tiny cleanups. It sweeps out harmless garbage in bulk while you focus on complex challenges. Speaking of complex challenges. Next time, we'll break down exactly how we sliced our massive pipeline monorepo into five fully independent deployments.

Originally published on our blog: https://blog.flude.guide/blog/stale-conditional-easter-egg

Also read us:

Typed Models: How we stopped silently losing data

Flude team — Fri, 28 Aug 2026 04:41:52 +0000

The first version of Flude's intermediate representation was built quick and dirty. We shoved classes, interfaces, enumerations, and variables into a single bottomless template. This universal model had a basic text field. It simply dictated what the object was pretending to be at any given moment.

The leak nobody knew about

Class fields were stored as a flat list of strings. We lost types, documentation, and access specifiers, keeping only the bare variable names. The parsers honestly extracted all this rich information from the source code. Our supermodel grabbed the name and trashed the rest. There were no exceptions and absolutely zero warnings in the logs. The renderer downstream physically couldn't show the type in the documentation. It received a string and manipulated a string.

Generation ran successfully, and files were created. Developers read the reference and tried to guess the data types. Silent degradation is the worst possible scenario when building developer tools. The system lies to your face, pretending everything is completely fine.

Strict models

We trashed the old code. Separate structures emerged for classes, methods, enumerations, and parameters. A class field became a fully typed object that guaranteed the presence of its name, specific type, and documentation. The transition hurt. Any legacy code that habitually accessed fields as text crashed immediately. The system finally started screaming about mismatches. We scrubbed out old string-based access patterns and rewrote the generation templates. In return, we got a solid guarantee: if the parser finds a complex type, it will absolutely make it to the final page intact.

Typing kills an entire layer of silent bugs. Strict contracts force you to write predictable code and free up mental space since you stop memorizing custom formats. Speaking of cleaning up technical debt. In the next post, we'll show how our AI audit dug into the orchestrator code and found an absolute masterpiece—a stale if not 0: condition left over from a local debugging session.

Originally published on our blog: https://blog.flude.guide/blog/typed-entity-models

Also read us:

Developer Guides: We didn't abandon the guides, just Flude—and then changed our minds

Flude team — Tue, 25 Aug 2026 05:44:46 +0000

We promised to cover the integration of Developer Guides in the previous article. We changed our approach to building these guides twice. We initially moved them completely outside the Flude generator. Harsh reality eventually forced us to reconsider that decision.

The first attempt: monolithic HTML generator

A single clunky tool built both the API reference and the guides on the old HTML stack. The guides covered standard scenarios like quick starts and custom project development. They also included collections of articles detailing SDK-specific features. These topics relate to working with the platform as a whole and require dedicated text descriptions.

We blindly carried this monolithic integration over into the first version of Flude. The old workflow seemed perfectly fine. The subject matter of the guides remained exactly the same, so nobody thought about decoupling the processes.

The second attempt: the illusion of plain Markdown

We decided to remove the guides from Flude's jurisdiction during the transition to a static site generator. The logic felt rock-solid. We wanted our parser to handle the complex API extraction. Handwritten guides are just standard Markdown text that the static generator can assemble on its own. The initial translation from HTML required minimal automation.

The guides moved into a separate directory—the SSG picked them up directly without any preprocessing. Flude dropped out of this build step entirely. The separation looked great on paper since two independent content sources only met on the final page.

Returning to a unified process

We eventually noticed a massive navigation problem. The guides knew absolutely nothing about the API reference pages. The reference had no idea the guides existed. Links to classes or methods led nowhere if the target page hadn't generated yet. They also died quietly when paths changed during a rebuild. Neither process could see the other to flag the broken connection.

We brought Developer Guides back under Flude's control using a different approach. The engine no longer renders them directly. It now validates the file formatting and tracks the integrity of cross-references. The SSG still handles the final portal assembly. Flude integrates into this pipeline as a dedicated validation step. Both systems operate within a unified workflow that catches broken links before publication.

Clean architectural separation often crashes against real-world requirements. Splitting systems apart inevitably requires building reliable bridges between them. The next article explores the Typed Models that helped us organize scattered data into a predictable structure.

Originally published on our blog: https://blog.flude.guide/blog/developer-guides-return

Also read us:

Regression Testing: Proving Your Code Doesn't Lose Data

Flude team — Thu, 20 Aug 2026 13:53:02 +0000

Building a working prototype for yourself is fairly easy. Pushing that rogue software into the official processes of a massive corporation is much harder. We finished developing the core logic and had to defend the project in front of management. People were used to the old generator. It spent hours building documentation while remaining predictable and providing strict control over code coverage.

The Wall of Distrust

Our engine relied on a completely different architecture. We dreamed of writing our own lightweight parsers. Tight deadlines forced us to grab Doxygen instead. It runs slowly and barely caches anything, but it consistently produces stable XML. Our code ingests this format, processes it into a custom data model, and renders clean Markdown.

Management looked at this layered setup with deep skepticism. They asked us directly for guarantees that the third-party parser wouldn't skip half the classes in our complex C++ codebase. Promises were useless. We needed hard numbers.

The Head-to-Head Collision

We wrote a regression testing script to directly compare the old corporate standard against our new Flude generator. We ran these tests across 36 combinations of SDKs and programming languages, including C++, C#, and Python.

The approach involved extracting the exact count of classes, methods, and enumerations from the legacy documentation. We then cross-checked those numbers against the output of our engine. All the data flowed into a single dashboard. We monitored the baseline metrics, our findings, and the final match percentage. The dashboard also listed missing entities and accidentally included garbage.

Battling the Discrepancies

The initial runs produced tons of inconsistencies. Doxygen choked on complex C++ template constructs and generated empty files instead of actual code. Internal autogenerator classes leaked out in the C# and Python wrappers—classes which the old tool had silently hidden.

We started the tedious grind of writing on-the-fly preprocessors. We stripped out problematic code blocks before parsing even started. We invented merge rules for anonymous enumerations and scrubbed utility trails. Every tweak plugged another hole in the metrics. We methodically adjusted the results until the match percentage reached 99.9-100% across all 36 combinations.

The final numbers proved that the Flude and Doxygen combination found the exact same tens of thousands of entities as the old standard. Nobody gave us the green light immediately. We simply validated the concept for ourselves. Our documentation includes detailed Developer Guides alongside the API references. The next article covers how we integrated those guides into the new generator.

Originally published on our blog: https://blog.flude.guide/blog/regression-testing

Also read us:

Guerrilla DevOps: How We Escaped to GitHub Actions

Flude team — Mon, 17 Aug 2026 17:05:56 +0000

In large companies, processes eventually take on a life of their own and start calling the shots. For us, the stumbling block was documentation publishing. Previously, technical writers would spend the entire month agonizingly collecting edits, only to push a single manual release out the door. That routine drove me up the wall. I wanted a proper CI/CD setup where everything builds itself after every push. But simply wanting it wasn't enough—I had to clearly prove to my colleagues that automation actually works in practice.

Transitioning to Static Site Generators (SSGs) required a Markdown parser. Our old internal tool could only spit out XML. Worse, on large codebases, it would grind to a complete halt for hours. Fortunately, while suffering through that, we had already put together a working Python ➡️ HTML pipeline (which I talked about in the previous part). All we had to do was hack it into Python ➡️ Markdown and start generating documentation for Flude itself. After all, the engine was also written in Python.

Next, infrastructure became the bottleneck. And that's when the corporate gears started grinding. Our Infrastructure Lead (the very guy who pitched the SSG idea) was buried under a mountain of tasks and then went on vacation. Sit and wait for his return just to fight for resources on the internal server? That meant putting the project on ice for at least a couple of months. So, I decided to go rogue.

The Escape Plan

If the internal network is off-limits, we take the experiment outside. GitHub fit the bill perfectly. I hid the engine's source code and the requirements list in private repositories. But the User Docs and the API Reference portals were quietly deployed in the cloud. At the end of the day, this was the open-source Flude. We weren't exposing a single line of proprietary corporate code.

Since we were building the project from scratch and for ourselves, we decided to experiment a bit. We picked completely different SSG frameworks for different portals. This complicated things slightly, but it was a great way to cut our teeth on configuring a diverse tech stack.

The pipeline architecture turned out exceptionally elegant. The User Docs portal automatically pulled fresh code from the closed repository. Then Flude woke up and parsed the source into Markdown on the fly. The SSG picked up the ready markup, built a static site out of it, and immediately pushed it to hosting (GitHub can serve HTML pages from public repos for free).

The Blind Architect

In theory, I understood the mechanics of CI/CD perfectly. The problem was purely practical: I didn't know the first thing about YAML syntax and had never configured GitHub Actions in my life. Just like when I started with Python, I was flying blind as an architect once again.

My AI teammate took over all the grunt work. I just described in plain English what should happen at each step. In return, the neural network spit out ready-made files for the .github/workflows folder. Sometimes it even slapped my wrist and forced me to implement best practices (like setting up dependency caching or splitting monolithic tasks into separate jobs). We pushed configs, stared at the red logs of failed builds, swore, fixed bugs, and ran it all over again.

The Moment of Truth

After a few evenings of non-stop tinkering, I made another push. GitHub Actions kicked into gear. The repository downloaded. Dependencies installed. Flude ran through the code, spitting out Markdown. The SSG instantly compiled the HTML. Deployment passed.

A green checkmark finally lit up on the screen. I clicked the site's URL and saw fresh documentation. It had updated itself, completely without my involvement.

At that moment, I screamed "Yes! Yes! Yes! It works!" so loudly that I scared my family, the budgies, and a couple of neighbors. It's an amazing feeling. Your concept just came to life right on the monitor. A routine monthly release just shrank down to a two-minute automated process.

We elegantly bypassed the corporate infrastructure, and the guerrilla pipeline was running like a well-oiled machine. But the final boss was looming ahead—legalizing the tool inside the company. We had to prove to the security department and management that our homegrown generator was just as good as the old standard. How do you run regression testing on closed data and make management believe in our parser? We'll cover that in the next episode.

Originally published on our blog: https://blog.flude.guide/blog/devops-on-github

Also read us:

The Markdown Singularity: Why Generating HTML is a Dead End

Flude team — Thu, 13 Aug 2026 14:27:54 +0000

At the end of the previous part, we were sitting on a perfectly working, fully tested pipeline. Our converter successfully chewed through Doxygen XML and generated custom HTML pages for our API documentation. The team was already getting ready to pop the champagne and push everything to production when the Infrastructure Lead walked over. He asked one simple, yet absolutely devastating question: "Why are you still messing around with HTML generation when off-the-shelf tools like Hugo, Docusaurus, or VitePress exist?"

The Pure HTML Trap

It took us exactly a minute to realize the sheer scale of our mistake. Generating pure HTML sounds great right up until you try to build a modern developer portal around it. It turned out we were about to reinvent the wheel for practically every standard web feature. Global search would require writing our own indexer. For navigation, we'd have to manually maintain a consistent sidebar across hundreds of generated pages, and synchronizing our styles with the corporate CSS threatened to turn into an endless chore. Instead of a documentation system, we had somehow started writing our own web framework.

The SSG Awakening

Static Site Generators (SSGs) like Hugo or Docusaurus solve all these problems out of the box. They come with built-in search, routing, and plugin systems. The only catch was that they strictly eat Markdown as input. We had to make a sharp pivot and re-engineer our pipeline from Doxygen XML ➡️ HTML to Doxygen XML ➡️ Markdown.

Rewriting the output layer was surprisingly painless. Even during the HTML generation phase, we had strictly separated the parsing and rendering logic, introducing an intermediate data layer we called the Intermediate Representation (or simply IR). This guaranteed the parser's stability while we ripped out the HTML generator and bolted on Markdown instead. And the practice of TDD definitely played its part—thanks to our tests, the Markdown generator was written quickly and confidently. As we worked on the new exporter, the puzzle pieces suddenly clicked together.

The Engine Singularity

Our architecture now consisted of two isolated phases. First, the Parser reads the source code and builds an abstract tree (that same IR), and then the Renderer takes the finished tree and translates it into Markdown. That’s when it hit us: the renderer absolutely does not care where this data came from.

We recalled the situation from the second article, when the AI tried to throw out Doxygen and started parsing the Python code directly via tree-sitter. Back then, we panicked about losing control and rolled back to parsing XML (even though the AI offered a working solution). Now, with a strict TDD contract and the intermediate IR layer in place, there was nothing to fear. We could safely ditch Doxygen and pull data directly from the source code.

Using an IR also came with the bonus of caching and faster generation times. If we fully build the tree in memory on the first run, there is no reason to rebuild it entirely on the next pass. We can simply use incremental parsing and update only the chunks that actually changed. And if we can read Python directly, nothing stops us from reading our main C++ SDK and our other languages. Or maybe even—dare I say it—languages that aren't ours.

This was the exact moment our highly specialized script mutated into a full-fledged Universal Documentation Engine (UDE). We did have to lengthen the name a bit due to an existing trademark for a German debugger called Universal Debug Engine. We tacked on the characteristics Fast and Layered, and thus Flude was born. Now we can plug any parser into the frontend, and the pipeline's backend will assemble beautiful Markdown for our SSG (complete with unified search and a proper design).

From a Local Task to a Massive Project

A tiny local utility for a couple of Python modules suddenly gave us the chance to design a scalable architecture from scratch. Building a product like this meant we could no longer rely on manual builds or running scripts locally on our laptops. We needed a fully automated CI/CD process.

I didn't have to figure this out by myself—my AI teammate took on the lion's share of the setup work. In the next episode, I'll explain why we decided to build our pipelines specifically on GitHub Actions.

Originally published on our blog: https://blog.flude.guide/blog/the-markdown-singularity

Also read us:

TDD as a Leash for AI: Writing Tests Without Knowing the Language

Flude team — Mon, 10 Aug 2026 14:23:43 +0000

At the end of the previous article, our project hit a dead end. The neural network had quietly plugged in the abstract syntax tree parser tree-sitter, turning the codebase into an absolutely unreadable "black box" for me.

We tried to force it to roll back the changes, but bugs started crawling through the generated code. Dependencies broke, and the script stopped running. Assessing the scale of the disaster, I came to a simple but harsh conclusion: it is much easier to write everything from scratch than to try to fix the AI's architectural glitches, especially given my complete lack of Python knowledge.

So our second prototype went into the trash can. We needed a new approach that wouldn't allow the neural network to act on its own. This tight leash became an uncompromising combination: a detailed formulation of requirements and total automated testing.

The New Contract with AI

The problem with previous iterations was that we set tasks like "parse this file and make it pretty". This gave the AI too much freedom.

To bring the architecture under control, we completely changed our workflow. Before writing a single line of code, we now established a strict "contract" with the neural network. Here is how it looked: first, we fixed strict requirements detailing permitted and forbidden libraries. Then, the AI generated a step-by-step plan for my approval. And most importantly, not a single function was written without a pre-created automated test.

How to Write Tests If You Can't Code?

A logical question arises here: how can a system architect who has never written a single line of Python in his life implement Test-Driven Development (TDD)? The answer is simple — the AI writes the tests too.

I didn't need to invent complex verification logic. I would take the original XML generated by Doxygen and find the required fragment there (for example, the description of a single class). Then I would take the beautiful, formatted HTML code that was supposed to be the final output (the exact one developers were used to in the old system).

I would feed both pieces into the chat and set the task: "Here is the input XML. Here is the final HTML that should be output. Write a test that takes this XML, runs it through our parser, and verifies that the output strings match this HTML character by character".

The neural network obediently wrote the test using pytest. Naturally, upon the first run, it failed with an error (since the parser itself didn't exist yet).

Red. Green. Refactor

We took the classic TDD cycle and adapted it slightly for working with AI. When the test failed (Red), the neural network caught the error in the console itself and immediately started debugging. Then came the Green stage: the AI silently fixed the code, re-ran the check, and the test passed. We got a working piece of code doing exactly what was requested. Finally, if the neural network suddenly decided that the algorithm wasn't elegant enough and tried to rewrite it using regular expressions (Refactor), I no longer panicked. We simply ran the tests again. If they were green — let it optimize as much as it wants, but at the slightest hint of red, we immediately rolled back the changes.

The Magic of Isolation

This approach worked flawlessly. The AI found itself strictly limited by our requirements and tests. It could no longer hallucinate non-existent parameters or quietly change the architecture, because any misstep caused the tests comparing the output HTML with the reference to fail.

Development proceeded incredibly fast. We covered all scenarios with tests (classes, methods, enumerations, parameters). The AI wrote the code, ran the checks itself, and we steadily moved on. In the end, we had a perfectly working engine in our hands that took bulky XML from Doxygen and flawlessly turned it into stunningly beautiful HTML pages. The project could be safely deployed to production, if not for one overlooked detail.

The next day, the Infrastructure Lead came to us and was genuinely surprised: "Why are you still fussing around with HTML when there are SSGs, from the beautiful Docusaurus to the super-powerful Hugo?".

I will talk about how this single sentence forced us to rebuild half the project all over again in the next part.

Originally published on our blog: https://blog.flude.guide/blog/tdd-as-a-leash

Also read us: