High-Level Business Requirements

The core high-level business requirements form the traceability baseline for the system:

• 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.
• 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): 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.
  • Verify-Document Mode (verify-document): 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.
• REQ-BUS-06 (Zero-Effort Localization & Asynchronous Translation Governance): 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.
• REQ-BUS-07 (Build & Execution Reporting): The engine must generate comprehensive performance, file, and API token usage/cost metrics after every compilation run to track operational footprint.
• 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.