--- title: Architecture Overview description: Understanding the mint-tsdocs pipeline and component architecture icon: "sitemap" --- ## Introduction `mint-tsdocs` transforms structured API data into beautiful Mintlify documentation through a multi-stage pipeline. ```mermaid graph LR A[.api.json files] --> B[API Model] B --> C[TSDoc AST] C --> D[MDX String] D --> E[.mdx files] style A fill:#e1f5ff style E fill:#e1ffe7 ``` ## Core Libraries The tool is built on three foundational libraries from Microsoft's Rush Stack: Command-line interface framework with typed parameters and actions Loads `.api.json` files into a traversable object model (`ApiModel`) Creates an Abstract Syntax Tree (AST) of documentation content ## Component Layers The codebase is organized into distinct layers, each with a specific responsibility: **Location**: `src/cli/` Parses user commands and initializes the documentation generation process. - `start.ts` - Executable entry point - `ApiDocumenterCommandLine.ts` - Main CLI parser - `BaseAction.ts` - Common action functionality - `MarkdownAction.ts` - Mintlify-specific command implementation **Location**: `src/documenters/` Orchestrates the conversion from API model to documentation pages. - `MarkdownDocumenter.ts` - Core orchestrator (now modular) - Builds TSDoc AST for each page - Delegates navigation to `NavigationManager` - Integrates caching for performance optimization **Location**: `src/markdown/` Serializes the TSDoc AST into Mintlify-compatible MDX. - `CustomMarkdownEmitter.ts` - Mintlify-specific rendering with API resolution caching - `MarkdownEmitter.ts` - Base markdown functionality - Generates `` and `` components **Location**: `src/navigation/` Dedicated navigation management for Mintlify documentation. - `NavigationManager.ts` - Hierarchical navigation generation - `docs.json` structure management - Mintlify v4 compatibility - API item categorization **Location**: `src/cache/` Performance optimization through intelligent caching. - `CacheManager.ts` - Centralized cache coordination - `TypeAnalysisCache.ts` - Caches expensive type parsing operations - `ApiResolutionCache.ts` - Caches API model cross-reference resolution - LRU eviction with configurable sizes **Location**: `src/utils/`, `src/nodes/` Supporting components for type analysis and AST nodes. - Custom TSDoc nodes (`DocTable`, `DocHeading`, etc.) - Type analysis utilities (`ObjectTypeAnalyzer` with caching) - Documentation helpers (`DocumentationHelper`) - Security utilities and error handling ## Data Flow ### 1. CLI Parsing User runs `mint-tsdocs markdown ...` - `start.ts` creates `DocumenterCli` instance - CLI parser invokes `MarkdownAction.onExecuteAsync()` - Parameters are validated and processed ### 2. API Model Building `BaseAction.buildApiModel()` loads the API data: - Reads all `*.api.json` files from input folder - Creates `ApiModel` instance - Loads each package into the model - Applies `@inheritDoc` workarounds ### 3. Document Generation `MarkdownDocumenter.generateFiles()` orchestrates: - Deletes old output files - Traverses API model recursively - Calls `_writeApiItemPage()` for each item - Builds TSDoc AST (not markdown strings!) ### 4. AST Construction For each page, `MarkdownDocumenter`: - Creates `DocSection` root node - Adds `DocHeading` for titles - Creates `DocTable` nodes for member lists - Builds `DocTableRow` and `DocTableCell` for each member - This AST represents semantic structure ### 5. MDX Emission `CustomMarkdownEmitter.emit()` serializes the AST: - Traverses TSDoc AST recursively - Identifies `DocTable` nodes with properties/methods - Calls `DocumentationHelper` for type analysis - Generates Mintlify components - Writes formatted MDX string ### 6. Navigation Update `NavigationManager.generateNavigation()`: - Reads existing `docs.json` - Merges new page paths hierarchically - Organizes by API item categories - Supports Mintlify v4 tab structure - Writes updated `docs.json` ### 7. Cache Statistics `CacheManager.printStats()` reports: - Type analysis cache performance - API resolution cache performance - Overall hit rates and usage ## Key Components Deep Dive **The Central Orchestrator** Responsibilities: - File management (delete old, write new) - API traversal (recursive iteration) - AST construction (build document structure) - Frontmatter generation (YAML blocks) - Navigation management (docs.json updates) **Key Method**: `_writeApiItemPage()` - Generates a single documentation page **The Mintlify Renderer** Responsibilities: - TSDoc AST → MDX conversion - Custom node rendering - Mintlify component generation - Link resolution - Type analysis integration **Key Feature**: Intelligent `DocTable` conversion to ``/`` components **The Type Analyzer** Responsibilities: - Parse TypeScript type strings - Extract nested object properties - Enrich with JSDoc descriptions - Generate property metadata **Key Method**: `analyzeTypeProperties()` - Recursively analyzes complex types **The Navigation Orchestrator** Responsibilities: - Hierarchical navigation generation - API item categorization (Classes, Interfaces, Functions, etc.) - Mintlify v4 tab structure support - docs.json management with validation - Duplicate prevention and path normalization **Key Feature**: Automatic categorization by API item type with configurable icons **The Performance Optimizer** Responsibilities: - Centralized cache coordination - Type analysis caching (30-50% performance improvement) - API resolution caching (20-40% performance improvement) - LRU eviction with configurable sizes - Hit rate monitoring and statistics **Key Feature**: Intelligent caching with environment-specific configurations **The Type Parser** (now with caching) Handles all TypeScript type patterns: - Primitives (`string`, `number`) - Arrays (`string[]`) - Unions (`A | B`) - Intersections (`A & B`) - Generics (`Promise`) - Object literals (`{ a: string; b: number }`) **New**: Integrated with TypeAnalysisCache for 30-50% performance improvement Returns structured `TypeAnalysis` objects for processing ## Custom TSDoc Nodes We extend the standard TSDoc nodes with custom types: Represents section headings with levels (h1-h4) ```typescript interface DocHeading { title: string; level: number; // 1-4 } ``` Represents complete tables - the most important custom node! ```typescript interface DocTable { header: DocTableRow; rows: DocTableRow[]; } ``` The emitter inspects tables to decide whether to render as HTML `` or Mintlify components. Represents Mintlify `` components for nested properties ```typescript interface DocExpandable { title: string; content: DocSection; } ``` Represents note/warning boxes (rendered as blockquotes) ```typescript interface DocNoteBox { content: DocSection; } ``` ## How to Contribute Understanding the pipeline helps you contribute effectively: Modify `CustomMarkdownEmitter` or `DocumentationHelper` Modify `MarkdownDocumenter` and AST construction Start in `MarkdownAction`, pass to `MarkdownDocumenter` Enhance `ObjectTypeAnalyzer` type detection ## Architecture Diagrams ```mermaid sequenceDiagram participant CLI participant Action participant Documenter participant NavigationManager participant CacheManager participant Emitter participant Helper participant TypeAnalyzer CLI->>Action: execute markdown command Action->>Action: buildApiModel() Action->>Documenter: generateFiles() Documenter->>CacheManager: initialize caches Documenter->>Documenter: traverse API items loop For each API item Documenter->>Documenter: build TSDoc AST Documenter->>Emitter: emit(ast) Emitter->>CacheManager: check API resolution cache alt cache miss Emitter->>Helper: analyzeTypeProperties() Helper->>TypeAnalyzer: analyzeType() TypeAnalyzer->>CacheManager: check type analysis cache alt type cache miss TypeAnalyzer->>TypeAnalyzer: parse type string TypeAnalyzer->>CacheManager: cache type result end Helper-->>Emitter: PropertyInfo end Emitter-->>Documenter: MDX string Documenter->>Documenter: write file Documenter->>NavigationManager: add to navigation end Documenter->>NavigationManager: generateNavigation() Documenter->>CacheManager: print stats ``` ## Next Steps Understand command-line parsing Learn about document generation Explore MDX rendering Master navigation management Optimize performance with caching Discover helper utilities