# pplmx/h2h architecture

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

- Interactive diagram: https://gitdiagram.com/pplmx/h2h
- Repository: https://github.com/pplmx/h2h

## Overview

##### Main components
- CLI Entry Point: Represented by main.go and cmd/root.go, which handle command-line arguments and act as the interface between the user and the application logic.
- Conversion Engine: Encapsulated largely in internal/convert.go, this component contains the core logic to parse Markdown files, transform FrontMatter between Hexo and Hugo formats, and handle conversion directions (hexo2hugo and hugo2hexo).
- File I/O & Logging: The tool processes directories of Markdown files (specified by --src and --dst), reads/writes these files, and logs conversion activity to h2h.log.
- Configuration & Build Tools: Though not part of the runtime flow, files like go.mod, Makefile, Dockerfile, and the various CI/CD GitHub workflows indicate additional support for building, testing, and deploying the tool.
- Testing & Documentation: The tests directory and various documentation files (e.g., docs/usage.md) ensure the system’s functionality and provide guidance for contributors.

##### Relationships and interactions
- The User (via CLI) supplies the source/destination directories and options (e.g., --format, --direction).
- The CLI system (main.go and cmd/root.go) parses these inputs and invokes the conversion engine.
- The Conversion Engine (internal/convert.go) then reads each Markdown file, identifies the FrontMatter format, converts it as needed, and then writes the output to the destination directory.
- Logging is performed concurrently, writing detailed information and errors to h2h.log.
- Optionally, integration with external tools (GitHub workflows, Docker, etc.) ensures continuous testing, building, and deployment, though these do not directly interact with the live conversion process.

##### Important architectural patterns and design principles
- Separation of Concerns: Splitting the CLI interface, conversion core, file management, and logging into distinct modules (cmd, internal, tests).
- Modularity: Isolating conversion logic within a dedicated internal package makes the tool easier to understand, test, and extend.
- Layered Architecture: Input (CLI) → Processing (Conversion Engine) → Output (File I/O & Logging).

- User Input → CLI Command Parsing → Conversion Logic → File I/O/Logging.
- Annotations for key technologies:
- Go for the programming language (main.go, cmd, internal, tests).
- GitHub Actions & Docker for CI/CD, building containerized versions.
- Detail on error handling: note that conversion errors and path issues are documented in the h2h.log file.

- That the tool accepts command-line parameters to drive the conversion process and that the conversion engine supports both YAML and TOML for FrontMatter conversion.
- Logging mechanism as a vital component for tracing conversion steps and any errors that occur.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Process Flow"
        A["User Input"]:::inputStyle
        B["CLI Entry Point (main.go, cmd/root.go)"]:::cliStyle
        C["Conversion Engine (internal/convert.go)"]:::conversionStyle
        D["File I/O & Logging (h2h.log)"]:::ioStyle
    end

    subgraph "Supporting Components"
        E["Build & Configuration (go.mod, Makefile, Dockerfile, .github/workflows)"]:::configStyle
        F["Testing & Documentation (tests, docs)"]:::docsStyle
    end

    A -->|"supplies"| B
    B -->|"invokes"| C
    C -->|"reads/writes_logs"| D
    D -->|"feedback"| A

    %% Click Events for CLI Entry Point files
    click B "https://github.com/pplmx/h2h/blob/main/main.go"
    click B "https://github.com/pplmx/h2h/blob/main/cmd/root.go"

    %% Click Event for Conversion Engine
    click C "https://github.com/pplmx/h2h/blob/main/internal/convert.go"

    %% Click Events for Build & Configuration
    click E "https://github.com/pplmx/h2h/blob/main/go.mod"
    click E "https://github.com/pplmx/h2h/tree/main/Makefile"
    click E "https://github.com/pplmx/h2h/tree/main/Dockerfile"
    click E "https://github.com/pplmx/h2h/tree/main/.github/workflows"

    %% Click Events for Testing & Documentation
    click F "https://github.com/pplmx/h2h/tree/main/tests"
    click F "https://github.com/pplmx/h2h/tree/main/docs"

    %% Styles
    classDef inputStyle fill:#c8e1ff,stroke:#0277bd,stroke-width:2px;
    classDef cliStyle fill:#dcedc8,stroke:#558b2f,stroke-width:2px;
    classDef conversionStyle fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef ioStyle fill:#ffccbc,stroke:#d84315,stroke-width:2px;
    classDef configStyle fill:#e1bee7,stroke:#8e24aa,stroke-width:2px;
    classDef docsStyle fill:#f8bbd0,stroke:#c2185b,stroke-width:2px;
```
