# ashok19rd91/md2ml architecture

> Architecture diagram of the GitHub repository ashok19rd91/md2ml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashok19rd91/md2ml
- Repository: https://github.com/ashok19rd91/md2ml

## Overview

#### Purpose and Entry Point
MD2ML is a .NET library for generating Word documents as WordProcessingML/OpenXML, with Markdown-to-document conversion plus direct document-construction APIs. Consumers instantiate `Md2MlEngine`, clone/create a DOCX from a template, write content, and save it. Core entry points are in `Md2Ml/Md2Ml/Md2MlCore.cs` and the project is built through `Md2Ml/Md2Ml/Md2Ml.csproj`.

#### Document Lifecycle
`Md2MlEngine` owns the document-generation lifecycle: create a destination document from a source/template DOCX, attach content to the document body, perform cleanup, and persist the finished package. It is the boundary between caller-provided paths/content and OpenXML document state.
- `Md2Ml/Md2Ml/Md2MlCore.cs`
- `Md2Ml/Md2Ml/Md2Ml.csproj`

#### Markdown Parsing Stage
Markdown text is accepted by the engine’s Markdown-writing APIs and passed through a parser that identifies document-level constructs and inline formatting. The parser separates Markdown interpretation from OpenXML emission, enabling Markdown text to be used within paragraphs, lists, and other generated structures.
- `Md2Ml/Md2Ml/MarkdownStingParser.cs`
- `Md2Ml/Md2Ml/Md2MlCore.cs`

#### Pattern-Based Formatting Model
The conversion design uses pattern objects and a matcher to recognize Markdown syntax and map it to formatting behavior. Paragraph patterns represent block-level constructs; run patterns represent inline spans such as emphasis, bold text, code, or hyperlinks. This is the main extensibility boundary for additional Markdown syntax.
- `Md2Ml/Md2Ml/PatternMatcher.cs`
- `Md2Ml/Md2Ml/ParaPattern.cs`
- `Md2Ml/Md2Ml/RunPattern.cs`

#### Paragraph and Run Property Translation
Recognized patterns are represented with separate property models for paragraph and run formatting. These models isolate semantic Markdown results from the eventual WordProcessingML paragraph/run properties, supporting composition of text styling with block layout.
- `Md2Ml/Md2Ml/ParaProperties.cs`
- `Md2Ml/Md2Ml/RunProperties.cs`
- `Md2Ml/Md2Ml/MarkdownStingParser.cs`

#### Direct OpenXML Authoring
Beyond Markdown conversion, the engine exposes imperative operations for paragraphs, plain/formatted text, hyperlinks, ordered and bulleted lists, page breaks, bookmarks, tables, and images. These operations likely share the same active document/body managed by the engine, while tables and non-body paragraphs permit composing content before attachment.
- `Md2Ml/Md2Ml/Md2MlCore.cs`

#### Runtime and External Boundaries
The library targets the .NET runtime and uses OpenXML specifications/packages to create and modify DOCX WordProcessingML packages. Input boundaries include local DOCX template/output paths, Markdown strings, image URLs or file paths, and hyperlink URLs. Image retrieval may require network access when callers provide URLs.
- `Md2Ml/Md2Ml/Md2Ml.csproj`
- `Md2Ml/Md2Ml/Md2MlCore.cs`

Main entry points: [`Md2Ml/Md2Ml/Md2MlCore.cs`](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2MlCore.cs) (Md2MlEngine), [`Md2Ml/Md2Ml/MarkdownStingParser.cs`](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/MarkdownStingParser.cs) (Markdown parser), [`Md2Ml/Md2Ml/PatternMatcher.cs`](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/PatternMatcher.cs) (Pattern matcher), [`Md2Ml/Md2Ml/Md2Ml.csproj`](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2Ml.csproj) (Md2Ml project)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Library API"]
  node_engine{{"Md2MlEngine<br/>lifecycle facade<br/>[Md2MlCore.cs]"}}
  node_markdown_api["Markdown writing APIs<br/>engine operations<br/>[Md2MlCore.cs]"]
  node_direct_api["Direct authoring APIs<br/>engine operations<br/>[Md2MlCore.cs]"]
end

subgraph group_markdown["Markdown Conversion"]
  node_parser["Markdown parser<br/>syntax interpreter"]
  node_matcher["Pattern matcher<br/>syntax matcher<br/>[PatternMatcher.cs]"]
  node_para_patterns["Paragraph patterns<br/>block syntax rules<br/>[ParaPattern.cs]"]
  node_run_patterns["Run patterns<br/>inline syntax rules<br/>[RunPattern.cs]"]
  node_para_properties["Paragraph properties<br/>block format model<br/>[ParaProperties.cs]"]
  node_run_properties["Run properties<br/>inline format model<br/>[RunProperties.cs]"]
end

subgraph group_document["Document Authoring"]
  node_docx[("DOCX / WordProcessingML<br/>OpenXML package")]
end

subgraph group_external["Runtime Boundaries"]
  node_consumer(("Library consumer<br/>caller"))
  node_project["Md2Ml project<br/>.NET library project<br/>[Md2Ml.csproj]"]
  node_openxml["OpenXML packages<br/>external dependency<br/>[Md2Ml.csproj]"]
  node_input_resources["Templates and resources<br/>[Md2MlCore.cs]"]
end

node_project -->|"builds"| node_engine
node_project -->|"references"| node_openxml
node_consumer -->|"uses"| node_engine
node_input_resources -->|"provides inputs"| node_engine
node_engine -->|"accepts Markdown through"| node_markdown_api
node_engine -->|"exposes"| node_direct_api
node_markdown_api -->|"parses"| node_parser
node_parser -->|"matches syntax with"| node_matcher
node_matcher -->|"uses block rules"| node_para_patterns
node_matcher -->|"uses inline rules"| node_run_patterns
node_parser -->|"produces"| node_para_properties
node_parser -->|"produces"| node_run_properties
node_parser -->|"emits formatted content"| node_docx
node_direct_api -->|"authors content"| node_docx
node_engine -->|"creates, cleans, and saves"| node_docx
node_openxml -->|"manipulates"| node_docx

click node_project "https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2Ml.csproj"
click node_engine "https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2MlCore.cs"
click node_markdown_api "https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2MlCore.cs"
click node_direct_api "https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2MlCore.cs"
click node_parser "https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/MarkdownStingParser.cs"
click node_matcher "https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/PatternMatcher.cs"
click node_para_patterns "https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/ParaPattern.cs"
click node_run_patterns "https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/RunPattern.cs"
click node_para_properties "https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/ParaProperties.cs"
click node_run_properties "https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/RunProperties.cs"
click node_openxml "https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2Ml.csproj"
click node_input_resources "https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2MlCore.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_engine,node_markdown_api,node_direct_api toneBlue
class node_parser,node_matcher,node_para_patterns,node_run_patterns,node_para_properties,node_run_properties toneAmber
class node_docx toneMint
class node_consumer,node_project,node_openxml,node_input_resources toneRose
```

## Components

### Library API

- [Md2MlEngine](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2MlCore.cs): lifecycle facade · Owns the active document, body attachment, cleanup, and save lifecycle. · `Md2Ml/Md2Ml/Md2MlCore.cs`
- [Markdown writing APIs](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2MlCore.cs): engine operations · `Md2Ml/Md2Ml/Md2MlCore.cs`
- [Direct authoring APIs](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2MlCore.cs): engine operations · Creates paragraphs, text, links, lists, breaks, bookmarks, tables, and images. · `Md2Ml/Md2Ml/Md2MlCore.cs`

### Markdown Conversion

- [Markdown parser](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/MarkdownStingParser.cs): syntax interpreter · Separates Markdown interpretation from OpenXML emission. · `Md2Ml/Md2Ml/MarkdownStingParser.cs`
- [Pattern matcher](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/PatternMatcher.cs): syntax matcher · Recognizes Markdown syntax using block and inline patterns. · `Md2Ml/Md2Ml/PatternMatcher.cs`
- [Paragraph patterns](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/ParaPattern.cs): block syntax rules · `Md2Ml/Md2Ml/ParaPattern.cs`
- [Run patterns](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/RunPattern.cs): inline syntax rules · `Md2Ml/Md2Ml/RunPattern.cs`
- [Paragraph properties](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/ParaProperties.cs): block format model · Carries paragraph layout semantics before WordProcessingML translation. · `Md2Ml/Md2Ml/ParaProperties.cs`
- [Run properties](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/RunProperties.cs): inline format model · Carries text styling semantics before WordProcessingML translation. · `Md2Ml/Md2Ml/RunProperties.cs`

### Document Authoring

- **DOCX / WordProcessingML**: OpenXML package · Template-derived destination package and generated document body.

### Runtime Boundaries

- **Library consumer**: caller · Supplies templates, Markdown, and direct authoring commands.
- [Md2Ml project](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2Ml.csproj): .NET library project · Builds the MD2ML library against its runtime dependencies. · `Md2Ml/Md2Ml/Md2Ml.csproj`
- [OpenXML packages](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2Ml.csproj): external dependency · `Md2Ml/Md2Ml/Md2Ml.csproj`
- [Templates and resources](https://github.com/ashok19rd91/md2ml/blob/master/Md2Ml/Md2Ml/Md2MlCore.cs): file, URL, and text input · Includes DOCX paths, Markdown strings, image sources, and hyperlink URLs. · `Md2Ml/Md2Ml/Md2MlCore.cs`

## Connections

- Md2Ml project → Md2MlEngine: builds
- Md2Ml project → OpenXML packages: references
- Library consumer → Md2MlEngine: uses
- Templates and resources → Md2MlEngine: provides inputs
- Md2MlEngine → Markdown writing APIs: accepts Markdown through
- Md2MlEngine → Direct authoring APIs: exposes
- Markdown writing APIs → Markdown parser: parses
- Markdown parser → Pattern matcher: matches syntax with
- Pattern matcher → Paragraph patterns: uses block rules
- Pattern matcher → Run patterns: uses inline rules
- Markdown parser → Paragraph properties: produces
- Markdown parser → Run properties: produces
- Markdown parser → DOCX / WordProcessingML: emits formatted content
- Direct authoring APIs → DOCX / WordProcessingML: authors content
- Md2MlEngine → DOCX / WordProcessingML: creates, cleans, and saves
- OpenXML packages → DOCX / WordProcessingML: manipulates