> ## Documentation Index > Fetch the complete documentation index at: https://mint-tsdocs.saulo.engineer/llms.txt > Use this file to discover all available pages before exploring further. # Architecture Overview > Understanding the mint-tsdocs pipeline and component architecture ## Introduction `mint-tsdocs` transforms structured API data into beautiful Mintlify documentation through a multi-stage pipeline. ```mermaid theme={null} 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 theme={null} interface DocHeading { title: string; level: number; // 1-4 } ``` Represents complete tables - the most important custom node! ```typescript theme={null} 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 theme={null} interface DocExpandable { title: string; content: DocSection; } ``` Represents note/warning boxes (rendered as blockquotes) ```typescript theme={null} 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 theme={null} 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