# uxiew/epub2md architecture

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

- Interactive diagram: https://gitdiagram.com/uxiew/epub2md
- Repository: https://github.com/uxiew/epub2md

## Overview

##### Main Components
- CLI Layer: Located under src/bin (files like cli.ts, convert.ts, helper.ts). This is the entry point when users run epub2md from the command line.
- Core Library / Parsing Modules: Consists of modules like parseEpub.ts, parseHTML.ts, parseLink.ts, parseSection.ts, and converter.ts. These modules handle file reading, parsing the EPUB structure, and conversion logic.
- Utility Components: Files like utils.ts and types.ts provide supporting functionality and type definitions.
- Format-Specific Converters: For instance, mobi.ts (possibly for converting or processing MOBI files) to support extended functionality.
- Testing Infrastructure: The test directory (with files such as parseEpub.spec.ts and parseHTML.spec.ts) and configuration files like jest.config.ts ensuring quality and integrity.
- Build & Deployment: Build scripts (like build.config.ts, deno-build.mjs), CI workflows (in .github/workflows), and configuration files (tsconfig.json, tslint.json, .npmignore, etc.) emphasize that this project is maintained with automated tests and continuous integration.
- Example Usage: The examples directory shows how a user might programmatically integrate and run the conversion.

##### Relationships and Interactions
- User Interaction via CLI: A user runs the entry point (cli.ts). The CLI layer then calls the core conversion modules.
- Conversion Pipeline: The CLI or programmatic API calls parseEpub to load and parse the EPUB file. The parsed data (such as table of contents, sections, and raw HTML) is then handed off to converter functions (including parseHTML, parseSection, etc.) for formatting.
- Data Flow: Input EPUB file → Parser (parseEpub) → Extraction of structure/info → Section-level conversion (each section has methods to toMarkdown, etc.) → Output Markdown.
- Utility and Helper Modules: Work “invisibly” to support the conversion, from string manipulations to type validations.
- Testing: The test suite ensures each part of the conversion pipeline works as expected (unit tests for parsing and CLI options).

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear distinction between the CLI layer and the conversion/parsing library.
- Reusability & Modularity: Components are broken into small modules (e.g., separate files for parsing HTML, linking, and sections) that can be used independently.
- Extensibility: The design permits the user to inject a custom HTML-to-Markdown conversion function, thereby following an injection or strategy pattern.
- Programmatic vs. CLI Use: Dual entry points ensure that the conversion logic is decoupled from the presentation (CLI) layer.

##### Relevant Technologies & Frameworks
- Node.js (and Deno support) for running the CLI and programmatic library.
- TypeScript is used throughout (as evidenced by tsconfig.json, linting configurations, etc.).
- GitHub Actions (.github/workflows) for automated testing and publishing.
- npm/ pnpm for package management.
- Testing is managed by Jest (jest.config.ts).

- Every component has a clear label. For example, “CLI Entry (src/bin)” or “EPUB Parser (parseEpub.ts)” and “HTML Converter (parseHTML.ts)”.
- Another for core logic modules.
- And yet another for configuration/build/test tools.
- Integration points—show that the CLI can invoke the programmatic API and that external utilities (like custom conversion functions) can plug into the pipeline.
- Incorporate annotations highlighting design patterns. For instance, mention that dependency injection is used when an external convertToMarkdown function is provided.

##### Detail
- It’s best to break down the project into as many “logical” components as possible. Even if some modules are small, mapping them helps display the complete design.
- Do not shy from illustrating file interactions – this is useful given the modularity found in this open-source library.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    user("User Input"):::cli

    %% CLI Layer
    subgraph "CLI Layer"
        cli_entry("CLI Entry (cli.ts)"):::cli
        cli_convert("Convert Command (convert.ts)"):::cli
        cli_helper("Helper Functions (helper.ts)"):::cli
        cli_entry --> cli_convert
        cli_convert --> cli_helper
    end

    %% Core Parsing & Conversion Modules
    subgraph "Core Parsing & Conversion"
        epub_parser("EPUB Parser (parseEpub.ts)"):::core
        html_converter("HTML Converter (parseHTML.ts)"):::core
        link_parser("Link Parser (parseLink.ts)"):::core
        section_parser("Section Parser (parseSection.ts)"):::core
        main_converter("Main Converter (converter.ts)"):::core
        mobi_converter("MOBI Converter (mobi.ts)"):::core
        epub_parser -->|"parses"| html_converter
        html_converter -->|"converts"| link_parser
        link_parser -->|"extracts"| section_parser
        section_parser -->|"processes"| main_converter
        main_converter -->|"optional"| mobi_converter
    end

    %% Utility Components
    subgraph "Utility Components"
        utils("Utils (utils.ts)"):::util
        types("Types (types.ts)"):::util
    end

    %% Testing Infrastructure
    subgraph "Testing Infrastructure"
        tests("Unit Tests (parseEpub.spec.ts, parseHTML.spec.ts)"):::test
        jest_config("Jest Config (jest.config.ts)"):::test
        tests --> jest_config
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        build_scripts("Build Scripts (build.config.ts, deno-build.mjs)"):::build
        ci_workflows("CI Workflows (.github/workflows)"):::build
        configs("Configurations (tsconfig.json, tslint.json, .npmignore)"):::build
        build_scripts --> ci_workflows
        ci_workflows --> configs
    end

    %% Example Usage
    subgraph "Example Usage"
        example("Example Usage (examples)"):::example
    end

    %% Relationships between layers
    user --> cli_entry
    cli_entry --> epub_parser
    cli_convert --> epub_parser
    epub_parser --- utils
    html_converter --- types
    main_converter --- utils
    example --> main_converter
    tests --- epub_parser
    tests --- cli_entry
    build_scripts -.-> cli_entry
    build_scripts -.-> epub_parser
    build_scripts -.-> tests
    build_scripts -.-> example

    %% Click Events
    click cli_entry "https://github.com/uxiew/epub2md/blob/main/src/bin/cli.ts"
    click cli_convert "https://github.com/uxiew/epub2md/blob/main/src/bin/convert.ts"
    click cli_helper "https://github.com/uxiew/epub2md/blob/main/src/bin/helper.ts"

    click epub_parser "https://github.com/uxiew/epub2md/blob/main/src/parseEpub.ts"
    click html_converter "https://github.com/uxiew/epub2md/blob/main/src/parseHTML.ts"
    click link_parser "https://github.com/uxiew/epub2md/blob/main/src/parseLink.ts"
    click section_parser "https://github.com/uxiew/epub2md/blob/main/src/parseSection.ts"
    click main_converter "https://github.com/uxiew/epub2md/blob/main/src/converter.ts"
    click mobi_converter "https://github.com/uxiew/epub2md/blob/main/src/mobi.ts"

    click utils "https://github.com/uxiew/epub2md/blob/main/src/utils.ts"
    click types "https://github.com/uxiew/epub2md/blob/main/src/types.ts"

    click tests "https://github.com/uxiew/epub2md/blob/main/test/parseEpub.spec.ts"
    click jest_config "https://github.com/uxiew/epub2md/blob/main/jest.config.ts"

    click build_scripts "https://github.com/uxiew/epub2md/blob/main/build.config.ts"
    click ci_workflows "https://github.com/uxiew/epub2md/tree/main/.github/workflows"
    click configs "https://github.com/uxiew/epub2md/blob/main/tsconfig.json"

    click example "https://github.com/uxiew/epub2md/tree/main/examples"

    %% Styles
    classDef cli fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef core fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef util fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef test fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef build fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef example fill:#ffdead,stroke:#333,stroke-width:2px;
```
