Appendix: Table of Contents & Flat-Mapping Specifications

This specification serves as the official System Design Document (SDD) Appendix (Variant A), outlining the logical hierarchies, Table of Contents (TOC) schemas, and logical-to-physical disk flat-mapping file conventions of the Fast Layered Universal Document Engine (Flude) across all four supported target SDK languages (C++, C#, Java, Python).

---

📐 1. Decoupling and Rendering Architecture

To preserve modular clean design, Flude strictly separates rendering targets. Different formatting rules are applied depending on the renderer component in use:

1. HugoMarkdownRenderer:

   • Generates standard Markdown outputs for static site generators.
   • Compiles the logical TOC hierarchy directly into YAML/TOML front-matter metadata blocks (title, weight, parent) within individual .md files. This allows the SSG (Hugo/VitePress) to automatically build its own sidebar.
   • Markdown formatting and front-matter rules apply strictly to this renderer.

2. HtmlRenderer:

   • Generates offline-friendly standalone flat-mapped .html files.
   • Stores the complete, cross-linked TOC tree structure inside a single global JSON object window.UDE_NAV_DATA in nav_data.js.
   • Integrates an interactive search and resizable sidebar directly inside the DOM without CORS protocol blocks.
   • HTML, visual CSS, and DOM-specific interaction rules apply strictly to this renderer.

---

🌲 2. Language-Specific TOC & Flat-Mapping Specifications

To prevent links breaking and compatibility issues on Windows, IIS, Apache, and Nginx, Flude maps complex logical namespace/package nesting to a flat, safe file directory structure on disk.

2.1 C++ SDK Specification

📁 Logical Hierarchy (Nested Namespaces)

C++ supports arbitrary multi-level nested namespaces. The logical TOC structure represents this nesting, grouping entities (classes, functions, structures, enums) under each namespace.

▲ API Reference (C++)
  ├── [Namespace] MyNamespace
  │     ├── [Namespace] MyNamespace::Features
  │     │     ├── [Namespace] MyNamespace::Features::Parting
  │     │     │     ├── [Folder] Classes
  │     │     │     │     ├── [Class] PartingLine
  │     │     │     │     │     ├── [Constructor] PartingLine
  │     │     │     │     │     ├── [Destructor] ~PartingLine
  │     │     │     │     │     ├── [Folder] Methods
  │     │     │     │     │     │     ├── [Method] apply (double)
  │     │     │     │     │     │     └── [Method] getResult
  │     │     │     │     │     └── [Folder] Variables
  │     │     │     │     │           └── [Field] m_draftAngle
  │     │     │     │     └── [Class] PartingSurface
  │     │     │     ├── [Folder] Functions
  │     │     │     │     └── [Function] createPartingLine (const Body&)
  │     │     │     └── [Folder] Enumerations
  │     │     │           └── [Enum] PartingType

💾 Physical Disk Flat-Mapping Rules (C++)

1. Namespace Scope: Double colons :: are mapped to double underscores __.
2. Class-Namespace Nesting: Linked via double underscores __.
3. Class Members (Methods, Fields): Separated from the enclosing class via double underscores __.
4. Overload Signatures: Parameters are appended after the member name, prefixed and separated by the commercial at @ character. Specifiers like pointer * and reference & are replaced with _ptr and _ref respectively.

Logical API Path	Physical Flat-Mapped Filename
MyNamespace (Namespace)	MyNamespace.html
MyNamespace::Features (Namespace)	MyNamespace__Features.html
MyNamespace::Features::Parting::PartingLine (Class)	class_MyNamespace__Features__Parting__PartingLine.html
PartingLine (Constructor with double)	class_MyNamespace__Features__Parting__PartingLine__PartingLine@double.html
apply(double) (Method)	class_MyNamespace__Features__Parting__PartingLine__apply@double.html
getResult() (Method)	class_MyNamespace__Features__Parting__PartingLine__getResult.html
createPartingLine(const Body&) (Global function)	MyNamespace__Features__Parting__createPartingLine@const_Body_ref.html

---

2.2 C# (.NET) SDK Specification

📁 Logical Hierarchy (Nested Namespaces)

C# namespaces are organized hierarchically using dot separation. The TOC mirrors this directory-style structure, grouping classes, interfaces, delegates, enums, and events.

▲ API Reference (C#)
  └── [Namespace] MyCompany
        └── [Namespace] MyCompany.MyProduct
              └── [Namespace] MyCompany.MyProduct.Core
                    ├── [Namespace] MyCompany.MyProduct.Core.Geom
                    │     ├── [Folder] Classes
                    │     │     ├── [Class] Vector3D
                    │     │     │     ├── [Constructor] Vector3D (double, double, double)
                    │     │     │     ├── [Folder] Properties
                    │     │     │     │     ├── [Property] X (get; set;)
                    │     │     │     │     └── [Property] Y (get; set;)
                    │     │     │     └── [Folder] Methods
                    │     │     │           ├── [Method] Length()
                    │     │     │           └── [Method] DotProduct(Vector3D)
                    │     │     └── [Class] Point3D
                    │     ├── [Folder] Interfaces
                    │     │     └── [Interface] IGeometry3D
                    │     └── [Folder] Enumerations
                    │           └── [Enum] CoordinateSystem

💾 Physical Disk Flat-Mapping Rules (C#)

1. Namespace Scope: Dot separators . are mapped to double underscores __.
2. Class-Namespace Nesting: Linked via double underscores __.
3. Class Members (Properties, Methods, Events, Fields): Separated from the enclosing class via double underscores __.
4. Overload Signatures: Parameters are appended after the member name, prefixed and separated by the commercial at @ character.

Logical API Path	Physical Flat-Mapped Filename
MyCompany.MyProduct (Namespace)	MyCompany__MyProduct.html
MyCompany.MyProduct.Core.Geom.Vector3D (Class)	class_MyCompany__MyProduct__Core__Geom__Vector3D.html
Vector3D (Constructor with 3 doubles)	class_MyCompany__MyProduct__Core__Geom__Vector3D__Vector3D@double@double@double.html
X (Property of Vector3D)	class_MyCompany__MyProduct__Core__Geom__Vector3D__X.html
DotProduct(Vector3D) (Method)	class_MyCompany__MyProduct__Core__Geom__Vector3D__DotProduct@Vector3D.html
IGeometry3D (Interface)	interface_MyCompany__MyProduct__Core__Geom__IGeometry3D.html

---

2.3 Java SDK Specification

📁 Logical Hierarchy (Nested Packages)

Java modules rely on nested package trees. The TOC displays every package as a directory containing sub-packages, classes, interfaces, and enums.

▲ API Reference (Java)
  └── [Package] com
        └── [Package] com.example
              └── [Package] com.example.product
                    ├── [Package] com.example.product.features
                    │     ├── [Package] com.example.product.features.parting
                    │     │     ├── [Folder] Classes
                    │     │     │     ├── [Class] PartingTool
                    │     │     │     │     ├── [Constructor] PartingTool (double)
                    │     │     │     │     ├── [Folder] Methods
                    │     │     │     │     │     ├── [Method] execute()
                    │     │     │     │     │     └── [Method] setTolerance(double)
                    │     │     │     │     └── [Folder] Fields
                    │     │     │     │           └── [Field] DEFAULT_TOLERANCE
                    │     │     │     └── [Class] PartingVerifier
                    │     │     ├── [Folder] Interfaces
                    │     │     │     └── [Interface] IPartingOperation
                    │     │     └── [Folder] Enumerations
                    │     │           └── [Enum] VerificationResult

💾 Physical Disk Flat-Mapping Rules (Java)

1. Package Nesting: In contrast to C++ and C#, Java package dot separators . are mapped to a single underscore _.
2. Class-Package Scope: Linked via a single underscore _.
3. Class Members (Methods, Fields): Separated from the enclosing class via double underscores __.
4. Overload Signatures: Parameters are appended after the member name, prefixed and separated by the commercial at @ character.

Logical API Path	Physical Flat-Mapped Filename
com.example.product (Package)	com_example_product.html
com.example.product.features.parting.PartingTool (Class)	class_com_example_product_features_parting_PartingTool.html
PartingTool(double) (Constructor)	class_com_example_product_features_parting_PartingTool__PartingTool@double.html
execute() (Method)	class_com_example_product_features_parting_PartingTool__execute.html
setTolerance(double) (Method)	class_com_example_product_features_parting_PartingTool__setTolerance@double.html
IPartingOperation (Interface)	interface_com_example_product_features_parting_IPartingOperation.html

---

2.4 Python SDK Specification

📁 Logical Hierarchy (Packages and Modules)

Python structures APIs through packages, sub-packages, and modules. The logical TOC groups classes, module-level functions, and exceptions.

▲ API Reference (Python)
  └── [Package] ude
        ├── [Package] ude.parsers
        │     ├── [Module] doxygen
        │     │     ├── [Folder] Classes
        │     │     │     ├── [Class] DoxygenXmlParser
        │     │     │     │     ├── [Method] __init__ (self, config_path: str)
        │     │     │     │     ├── [Folder] Methods
        │     │     │     │     │     ├── [Method] parse_file (self, file_path: str)
        │     │     │     │     │     └── [Method] cleanup (self)
        │     │     │     │     └── [Folder] Properties
        │     │     │     │           └── [Property] version (fget)
        │     │     │     └── [Class] ParserConfig
        │     │     └── [Folder] Functions
        │     │           └── [Function] get_default_parser()

💾 Physical Disk Flat-Mapping Rules (Python)

1. Module & Package Scope: Dot separators . are mapped to a single underscore _.
2. Class-Module Scope: Linked via a single underscore _.
3. Class Members (Methods, Properties): Separated from the enclosing class via double underscores __.
4. Overload Signatures: Parameters are appended after the member name, prefixed and separated by the commercial at @ character. Dunder (built-in) methods preserve their native double underscores.

Logical API Path	Physical Flat-Mapped Filename
ude.parsers (Package)	ude_parsers.html
ude.parsers.doxygen.DoxygenXmlParser (Class)	class_ude_parsers_doxygen_DoxygenXmlParser.html
__init__(self, config_path: str) (Constructor)	class_ude_parsers_doxygen_DoxygenXmlParser____init__@str.html
parse_file(self, file_path: str) (Method)	class_ude_parsers_doxygen_DoxygenXmlParser__parse_file@str.html
version (Property)	class_ude_parsers_doxygen_DoxygenXmlParser__version.html
get_default_parser() (Global function)	ude_parsers_doxygen_get_default_parser.html

---

🗃️ 3. Sidebar Navigation Configuration (sidebar.toml)

Rewritten 2026-08-10. This section originally described a per-renderer-class toc_<RendererClassName>.json file under SidebarStructures/default/ — one JSON file per each of the 16 concrete renderer classes, each declaring its own navigation array. That mechanism was fully replaced in v2.0 by IMP-32.10/GAP-06: navigation is now sourced from a single sidebar.toml (TOML, not JSON) placed directly in each document directory, next to that project's ude_doc_config.json — not one file per renderer class, one file per project. See user-docs/docs/migration-v2.md ("Hard stop 1") for the end-user migration path.

At runtime, Flude resolves navigation from sidebar.toml through a 3-tier configuration cascade (global → SDK → document), the same cascade the rest of this document's configuration layers use. Two independent tables live in this one file, and they behave differently on purpose:

Table	Engine-tier default	Behavior if a project declares none
[[sidebar]]	None.	Build fails. resolve_config() raises UdeException — missing, empty, and malformed sidebar.toml are all fatal. There is no default navigation at any tier: navigation nobody wrote would render successfully and give nothing to notice, which is a worse outcome than a stopped build.
[groups]	Yes — the folder taxonomy (namespace_level, class_level) shipped in the engine's own <Lang><Output>DefaultRenderer.toml fixtures.	The engine default applies. In practice, 0 of the 78 real ude_projects/ document directories override it.

A project's own [[sidebar]] or [groups] table, when present, replaces the corresponding table wholesale (list-replace, not a field-level merge) — never a partial overlay of the two.

The mandatory-file rule is not theoretical: all 78 real ude_projects/ document directories were checked directly against this rule and every one already carries a sidebar.toml — zero exceptions.

3.1 [[sidebar]] Node Types

[[sidebar]] is a TOML array of tables; each entry is one root-level navigation node, in the order they should render. Four node types are supported, identical in concept to the pre-v2.0 JSON schema — only the file format and location changed:

1. api_reference: The root of the Doxygen-compiled API reference tree. Exactly one api_reference node may exist per project.
2. static: A page compiled from an external HTML or Markdown file, named by a relative source_file key. The engine searches for that filename inside the directories listed in static_source_path (a doc-config-level setting, string or list). For HTML sources, only the <body> content is extracted; for Markdown, everything except front-matter is used.
3. inline: A page whose body is embedded directly in sidebar.toml under a content key (in the target renderer's own output format — HTML or Markdown — without page headers or layout chrome).
4. redirect: A node that redirects to a redirect_url (relative internal path or absolute external URL) — HTML output emits a <meta http-equiv="refresh">, Hugo output emits redirect_url front-matter consumed by the SSG.

static/inline/redirect nodes are siblings of api_reference at the root of the [[sidebar]] array; they support Jinja2 interpolation against the merged configuration context (e.g. {{Product_name}}, {{sdk_name}}).

3.2 What Did Not Carry Over

The old JSON schema let each api_reference node embed a recovered_toc_algorithm block — per-renderer file-naming rules (:: → __, overload markers, aggregation-index regexes) and virtual folder taxonomy, configurable per project. That is no longer configurable via sidebar.toml at all. recovered_toc_algorithm is now fixed, non-user-configurable Python class attributes on each of the 16 concrete renderer classes (see §2 above for the still-current flat-mapping rules themselves). Only the folder taxonomy half of the old block survives as user-facing configuration, and it moved to the separate [groups] table below — not into [[sidebar]].

3.3 [groups] Folder Taxonomy

[groups]
namespace_level = ["Classes", "Fields,_Structures_and_Enums", "Functions", "Types"]
class_level = ["Data", "Nested", "Enumerations", "Unions", "Structures", "Classes", "Operators", "Methods"]

namespace_level and class_level are the only permitted keys (extra="forbid" — a typo is a hard build failure, not a silently empty taxonomy). They list the virtual group folders ("Classes", "Structures", …) under which entities are bucketed at the namespace level and the class level respectively; a group with zero entities in a given compiled target is pruned on-the-fly rather than rendered as an empty folder.

3.4 Example sidebar.toml

[[sidebar]]
type = "static"
label = "API Reference Welcome"
url = "welcome.html"
source_file = "welcome.html"

[[sidebar]]
type = "inline"
label = "Release Notes"
url = "release_notes.html"
content = "<h1>Release Notes</h1><p>{{Product_name}} {{api_version}} has been successfully compiled.</p>"

[[sidebar]]
type = "api_reference"
label = "API Reference (C++)"
url = "index.html"

[[sidebar]]
type = "redirect"
label = "External ODA Developer Portal"
url = "dev_portal.html"
redirect_url = "https://www.opendesign.com"

(Justified external link, DR-NEW-10: redirect_url above is a real example of the redirect sidebar entry type — it must be an actual external URL to demonstrate the feature, not a placeholder.)

This layout guarantees that Flude compiles format-specific, flexible sidebars from a single per-project source of truth, replacing the per-renderer-class JSON files MVP v1.0 shipped.