High-Level Business Requirements

The core high-level business requirements form the traceability baseline for the system. Each REQ-BUS-* is linked to its functional and non-functional breakdown, and to its delivery status, from the Requirements Catalog.

:::note Structure changed 2026-08-14

These requirements were previously a flat bullet list, which meant none of the fourteen had a working anchor — nothing could link to an individual REQ-BUS-*. Each is now its own heading, holding the bare id so the generated slug is predictable (`REQ-BUS-01` → #req-bus-01), matching the convention used throughout requirements/. No id, title, or requirement text changed in that conversion; the one substantive edit is the legacy.py → oda.py correction in REQ-BUS-02 (the renderer module was renamed in v2.0 — ODA is a target-format variant, not a deprecated predecessor).

:::

REQ-BUS-01

Extensible Multi-Language Input

The engine must support multi-language parsing (with C++, C#, Java, and Python as the initial base set) utilizing a decoupled frontend architecture.

REQ-BUS-02

Multi-Format Rendering Engine

The engine must support rendering its language-agnostic Intermediate Representation (IR) into multiple configurable target formats including, but not limited to, HTML, Markdown (generic and optimized for SSGs like Hugo or VitePress), RAG JSON, and structured XML to fulfill diverse publishing requirements. HTML and Hugo Markdown rendering are implemented (static_html.py, oda.py, hugo_markdown.py); [UNIMPLEMENTED] the RAG JSON (see REQ-BUS-04) and structured XML output formats are not present in the codebase.

REQ-BUS-03

Git Integrity & Storage Optimization

Automated API Reference generation must run "on-the-fly" in CI/CD without polluting Git repositories with compiled Markdown/HTML, except for necessary inputs like translation caches and manual override database files. To minimize repository size, storage footprint, and git network bandwidth, all intermediate data and cache files stored in Git (such as translation caches and Intermediate Representation databases) must be persisted in a compressed file format (specifically Gzip-compressed JSON .json.gz), transparently handled by the engine.

REQ-BUS-04

RAG Hierarchical Export

The engine must support exporting structured, metadata-rich hierarchical JSON files (containing entity types, full names, line ranges, signature hashes, and dependency relations) optimized to feed enterprise AI semantic search engines and developer chat-bots.

REQ-BUS-05

AI-Powered Enrichment & Push-Gate Control

The engine must support identifying undocumented or sparsely documented public API elements during code ingestion (excluding elements marked with ignore tags like \cond or DOC-IGNORE). The base language for all docstrings and primary documentation is strictly English. It must run on a secure server-side gate (CI/CD check or server hook) and support four configurable execution modes, strictly separating read-only gate-validation from write-enabled code modification:

• Reject Mode (reject-undocumented): The core orchestrator runs in read-only mode, performs a documentation coverage audit against the defined gate threshold, and strictly blocks the push/merge of undocumented code (exiting with an error code) without invoking live LLM APIs.
• Allow/Warn Mode (allow-undocumented): The core orchestrator generates detailed warnings and coverage audits in English but permits the push/merge.
• Auto-Document Mode (auto-document): [UNIMPLEMENTED] If undocumented code is detected, the pipeline triggers an independent, write-enabled enrichment tool (ude-enrich or subcommand ude document). This tool requests English docstrings from the secure LLM and writes them back to the source codebase in a hands-free manner. No enrichment tool or write-enabled subcommand exists in the codebase.
• Verify-Document Mode (verify-document): [UNIMPLEMENTED] If undocumented code is detected, the pipeline triggers the ude-enrich tool to generate draft AI docstrings in English and inject them as non-blocking proposals (e.g., Pull Request Suggestions or dedicated draft branches), blocking merge completion until a developer reviews and approves them. No enrichment tool or write-enabled subcommand exists in the codebase.

REQ-BUS-06

Zero-Effort Localization & Asynchronous Translation Governance

[UNIMPLEMENTED] The documentation system must support high-quality multi-language generation with zero developer translation overhead, employing English as the source and an incremental translation cache for other target languages, supporting human override schemas (committed to Git) for manual quality control. A translation_service field exists in GlobalConfig but is reserved/inactive; no translation cache, override schema, or LLM integration is implemented.

REQ-BUS-07

Build & Execution Reporting

[UNIMPLEMENTED] The engine must generate comprehensive performance, file, and API token usage/cost metrics after every compilation run to track operational footprint. No performance, file, or API token/cost metrics reporting exists anywhere in the orchestration or parsing pipeline.

REQ-BUS-08

Documentation Coverage & Quality Gate Separation

The engine must support quantifying the documentation status of API entities. It must strictly separate Quality Gate Enforcement (blocking integrations in CI/CD when thresholds are violated) from Standalone Coverage Reporting (generating independent, detailed reports about undocumented entities, executable decoupled from documentation compilation). Both mechanisms must support custom ignore tags to exclude internal or development-specific code from metrics.

REQ-BUS-09

Seamless Pipeline Automation

The system must be fully automatible inside standard containerized and serverless CI/CD environments (GitHub Actions, GitLab CI, Jenkins, etc.), removing any requirements for interactive steps or manual intervention during standard compilation runs.

REQ-BUS-10

Premium Developer Portal UX & Unified Taxonomy Layouts

The documentation engine must be capable of generating technical publications with standardized, language-specific layouts, structured Table of Contents (TOC) mappings, and highly interactive navigation interfaces tailored to offline or online rendering formats without relying on site-specific frameworks.

REQ-BUS-11

Integrated Document Indexing & Catalog Referencing

The engine must support injecting custom, user-defined catalog or index references into the generated navigation trees to ensure unified coverage across multiple distinct guides and technical manuals.

REQ-BUS-12

Hierarchical & Inherited Configurations

The system must support configuration inheritance and flat-merging of global and local settings (e.g., merging global ude_global_config.json and target-specific ude_doc_config.json). This must enable centralized governance of base environments (like output base paths) and individual target-level specifications (like subfolders) while maintaining backward-compatible fallbacks for legacy standalone targets.

REQ-BUS-13

Three-Tier Multi-Level Doxygen Configuration Merging

The collection pipeline must support a sequential multi-level configuration model for Doxygen, enabling performance and optimization defaults (such as thread parameters and lookup cache sizes) to be defined globally as templates, overridden locally by target-specific files, and augmented dynamically with runtime parameters (like source and output paths) generated by the orchestrator.

REQ-BUS-14

Configurable Source Scope Control — Path/File Inclusion & Exclusion

[PARTIAL] The engine must let a target configuration precisely control which source files and directories are fed into the parsing stage, both by explicit inclusion (glob/path allowlist) and explicit exclusion (glob/path denylist), independent of the existing in-source annotation mechanisms (\internal, DOM-IGNORE, \cond). This is required so that a project can reliably scope its input to only the surface it intends to expose — including scenarios where the resulting Intermediate Representation (IR) itself leaves the source's own environment (e.g., is submitted to an external rendering service) and must not depend solely on developer discipline in tagging individual entities.

Corrected 2026-08-14 (this claim was previously "no configuration exists today," which was false): engine/ude/collectors/doxygen.py:642-657 already wires three declared ude_doc_config.json collector keys into the generated Doxyfile — exclude (→ EXCLUDE), exclude_patterns (→ EXCLUDE_PATTERNS, wildcard-based), and file_patterns (→ FILE_PATTERNS, with a leading **/ stripped so "any depth" is preserved). These are declared config keys, not the hand-authored collector.doxyfile_template escape hatch this requirement originally described as the only route in — and they are in real production use (e.g. ude_projects/Kernel/kernel_api_cpp/ude_doc_config.json sets both file_patterns and exclude_patterns). What remains unimplemented: a true include allowlist distinct from file_patterns-style narrowing, namespace-level (not just file-path) scoping, and an implementation independent of Doxygen. See requirements/v3.0-next.md for the full, corrected requirement and user-docs/docs/exclusion-gates.md for the user-facing correction.