# souvikinator/notion-to-md architecture

> Architecture diagram of the GitHub repository souvikinator/notion-to-md, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/souvikinator/notion-to-md
- Repository: https://github.com/souvikinator/notion-to-md

## Overview

##### Main Components
- Notion API Client: Represented by the “@notionhq/client” that the library wraps. This component is responsible for handling all external communication with Notion.
- NotionToMarkdown Module: This is the central component (implemented primarily in src/index.ts and supported by src/notion-to-md.ts) that manages converting pages/blocks into Markdown.
- Conversion Modules/Functions: Within the core functionality, specific functions (like pageToMarkdown, blocksToMarkdown, and blockToMarkdown) transform Notion data into Markdown. Also, the custom transformer mechanism (via setCustomTransformer) is part of this data processing layer.
- Utility Functions: Located in src/utils (with corresponding tests), these include helper functions for Markdown processing (e.g., md.ts and its tests, and notion.ts for handling Notion-specific details).
- Type Definitions: Found under src/types, these ensure that the data structures used throughout processing are well defined and enforce consistency.

##### Relationships and Interactions
- Once the data is fetched, it flows into the conversion modules where:
- The data is parsed into internal representations.
- Utility functions convert these representations into Markdown strings.
- Custom transformers (if configured) modify or override default behaviors.
- Finally, the output is produced as a Markdown object/string which is then returned to the calling application.

##### Architectural Patterns and Design Principles
- Modular Design: The project’s separation into src, types, and utils indicates a component-based approach, making it easy to test and extend.
- Extensibility: The provision for custom transformers shows an intention for users to extend the default behavior.
- Clear Separation of Concerns: There’s a distinct division between handling API interactions, data conversion, and helper utilities.

##### Relevant Technologies and Frameworks
- Node.js: The runtime environment.
- TypeScript: The language used (as indicated by the .ts file extensions and tsconfig.json).
- notion-sdk-js: The external library interacting with the Notion API.
- Jest: For testing, as evidenced by jest.config.js and the test files.
- GitHub Workflows: Managed via the .github directory for CI/CD tasks such as automated testing or releases.

##### Final Recommendations for Execution
- Dig deeper by breaking down the "NotionToMarkdown" processing pipeline into its internals (i.e., fetching, parsing, conversion, and transformation).
- That dependencies (like TypeScript and Jest for testing, and GitHub workflows for CI/CD) are at least noted as part of the overall ecosystem, if not depicted directly in the flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User/Client"]:::user
    User --> NotionToMarkdown_index["NotionToMarkdown (index)"]:::module
    NotionToMarkdown_index --> NotionToMarkdown_nmd["NotionToMarkdown (notion-to-md)"]:::module
    NotionToMarkdown_nmd --> Notion_API["Notion API Client"]:::external
    NotionToMarkdown_nmd --> Conversion_Func["Conversion Functions"]:::module
    Conversion_Func --> Markdown_Utils["Markdown Utils"]:::util
    Conversion_Func --> Notion_Utils["Notion Utils"]:::util
    Conversion_Func --> Output["Markdown Output"]:::module
    NotionToMarkdown_index --> Type_Def["Type Definitions"]:::module

    %% Testing subgraph
    subgraph "Testing"
        Conversion_Tests["Conversion Tests"]:::test
        Utils_Tests["Utils Tests"]:::test
    end
    Conversion_Func --- Conversion_Tests
    Markdown_Utils --- Utils_Tests

    %% CI/CD Workflows node
    CI_CD["CI/CD Workflows"]:::external

    %% Click Events
    click NotionToMarkdown_index "https://github.com/souvikinator/notion-to-md/blob/master/src/index.ts"
    click NotionToMarkdown_nmd "https://github.com/souvikinator/notion-to-md/blob/master/src/notion-to-md.ts"
    click Notion_API "https://github.com/souvikinator/notion-to-md/blob/master/package.json"
    click Conversion_Func "https://github.com/souvikinator/notion-to-md/blob/master/src/notion-to-md.ts"
    click Markdown_Utils "https://github.com/souvikinator/notion-to-md/blob/master/src/utils/md.ts"
    click Notion_Utils "https://github.com/souvikinator/notion-to-md/blob/master/src/utils/notion.ts"
    click Type_Def "https://github.com/souvikinator/notion-to-md/blob/master/src/types/index.ts"
    click Conversion_Tests "https://github.com/souvikinator/notion-to-md/blob/master/src/notion-to-md.spec.ts"
    click Utils_Tests "https://github.com/souvikinator/notion-to-md/blob/master/src/utils/md.spec.ts"
    click CI_CD "https://github.com/souvikinator/notion-to-md/tree/master/.github/workflows"

    %% Styles
    classDef user fill:#f9d,stroke:#333,stroke-width:2px;
    classDef module fill:#ccf,stroke:#333,stroke-width:2px;
    classDef external fill:#fc9,stroke:#333,stroke-width:2px;
    classDef util fill:#9f9,stroke:#333,stroke-width:2px;
    classDef test fill:#ddd,stroke:#333,stroke-width:2px;
```
