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 system must generate a developer portal with a premium visual design and advanced interactivity. This includes a clear logical-to-physical flat-mapped Table of Contents (TOC), highly responsive offline-friendly sidebar navigation (supporting drag-to-resize, persistent states, and real-time filtering without CORS limitations), and standardized page templates customized for each language's native API taxonomy elements (classes, packages, methods, etc.) to ensure aesthetic excellence and supreme technical readability. Additionally, every sidebar category, group, or section node must resolve to a valid, navigable page (either an explicit index page or its first-level child document), preventing empty collapsible headers.
• REQ-BUS-11 (Integrated Document Indexing & Catalog Referencing): The documentation system must require all generated publications to contain an integrated, easily accessible link referencing a centralized document catalog file (e.g., ude_portal_blueprint.md or a centralized table of contents index) to ensure full navigational coverage of all available guides, manuals, and technical documents.