Case Study: Building This Portal

Flude is built on a transparent, self-documenting "dogfooding" architecture: the engine compiles its own Python source files to generate a live API reference. This page details how that pipeline works.

INFO

Architecture note (2026-08-11): as of 2026-07-22, the self-documenting pipeline lives entirely inside the engine repository and deploys to its own, separately-hosted site — it is no longer nested inside this portal's own build. The sections below describe the current, single-repository architecture; there is no longer a user-docs/engine directory junction of any kind.

---

🐕 The Dogfooding Concept

To prove that Flude can withstand high-load enterprise pipelines, we use Flude to document Flude. The Python core engine's modules (such as ude.cli and ude.orchestrator) are processed by our own compiler as part of engine's own publish-api-ref.yml workflow.

This approach ensures:

• Constant Real-World Verification: Any parsing or rendering bugs in new commits are caught instantly during our own documentation build.
• Live Demos: Users can explore the live API Reference to see the exact visual output styles produced by the system.

---

📑 Self-Configuration Block Walkthrough

The self-documenting pipeline is controlled by engine/ude_self_doc_config.json — it lives inside engine itself (moved there 2026-07-22; it used to live in user-docs as ude_config_self.json, reached via a directory junction back into engine, before this repository split). Here is the file in full:

{
    "project_name": "Flude API Reference",
    "src_dir": ["engine/ude"],
    "static_pages_dir": "./",
    "output_dir": "hugo-site/content",
    "incremental": true,
    "collector": {"type": "doxygen", "language": "python", "doxyfile_template": "Doxyfile"},
    "parser": {"type": "doxygen_xml"},
    "renderer": {"type": "hugo_markdown"}
}

Let's inspect its key parameters:

1. Source Directory

"src_dir": ["engine/ude"]

Points Flude at engine's own Python source tree (ude, relative to the config file's own directory) — no junction or symlink needed now that the config lives alongside the source it documents.

2. Source Collector

"collector": {"type": "doxygen", "language": "python", "doxyfile_template": "Doxyfile"}

Selects the Doxygen-based collector, tells it to parse Python (language: "python"), and points it at a Doxyfile template used to drive the underlying Doxygen invocation.

3. Parser & Output

"parser": {"type": "doxygen_xml"}

paired with the top-level

"output_dir": "hugo-site/content"

The doxygen_xml parser reads the Doxygen-generated XML AST into Flude's intermediate representation. Because this config sets a standalone output_dir rather than an output_subdir/output_base_dir pair, that field alone determines where rendered output is written.

4. Selecting the Hugo Markdown Renderer

"renderer": {"type": "hugo_markdown"}

Selects the Hugo Markdown renderer using the generic dispatch token "hugo_markdown", generating a cross-linked API Reference catalog under the configured output directory. Unlike some example configs elsewhere in this repository that set renderer.type to a concrete renderer class name, this self-config uses the generic token the renderer dispatch logic actually matches against.

---

⚙️ Deployment: A Separate Site, Not a Build-Order Patch

Earlier versions of this architecture injected the compiled API reference directly into this portal's own VitePress build output (.vitepress/dist/api/), requiring a strict build-order patch so VitePress's own directory-wipe on compile wouldn't destroy it. That coupling no longer exists.

1. engine's own publish-api-ref.yml parses engine's Python source, renders it through Hugo, and deploys the result straight to its own Cloudflare Pages project — entirely within the engine repository, on every push to its main branch.
2. This portal (user-docs) is not involved in that build at all: its own deploy.yml compiles and deploys only the VitePress guides you are reading now, to a separate Cloudflare Pages project (user.flude.guide).
3. The two sites are linked only by the external hyperlink above — there is no shared build step, no injected output directory, and no ordering dependency between them.

See user-docs/docs/deployment/cicd-pipelines.md for the full cross-repository pipeline matrix.