# onjin/mkchangelog architecture

> Architecture diagram of the GitHub repository onjin/mkchangelog, 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/onjin/mkchangelog
- Repository: https://github.com/onjin/mkchangelog

## Overview

##### Project Type and Purpose
- The project is a command-line utility written in Python for generating a changelog from git commits following the conventional commits standard.
- It supports generating changelogs using git tags for versioning—but, as per the additional instructions, it can also support alternative version providers (for example, month-based versions or other date-based schemes).
- The tool is configurable (using an .ini configuration file) and supports custom templates via Jinja2 with additional template filters via a plugin/hooks system.

##### Analyzing the File Structure – Key Components
- Directories like src/mkchangelog hold the main library code.
- app.py: Most likely the CLI entry point.
- commands/ directory: Contains different subcommands (generate, commit, bump, settings) that implement various functions.
- config.py, core.py, parser.py, providers.py, models.py: Manage configuration, core logic, parsing commits, and interfacing with version providers.
- templates/ directory: Contains built-in Jinja2 templates (markdown, rst, text) used for rendering changelog.
- hookspecs.py and .mkchangelog.d/hooks.py: Show that a hooks system is in place allowing extension via custom filters.
- Other directories include tests (unit tests for various components), docs (documentation), and configuration in CI/CD folders (.github).
- The .mkchangelog.d directory holds additional version-specific files (headers, footers, commit text files) that allow inclusion of extra commit messages for versions.

A. CLI Interface and Command Dispatcher:
- Entry-point (app.py) that parses command-line arguments.
- The dispatcher routes commands (generate, commit, bump, settings) to the corresponding module in the commands/ folder.
B. Core Engine:
- The core logic, located in core.py and lib.py, that orchestrates functionality:
- It retrieves configuration settings (from config.py).
- Calls the commit parser (parser.py) to process git log messages.
- Manages the grouping and sorting of commits based on conventional commits.
C. Version Provider Module:
- This component is responsible for determining the versions to include.
- Git Tag Version Provider: Processes annotated git tags (default behavior).
- Date-based/Monthly Version Provider: (your additional design option) which can generate version identifiers based on dates.
- These providers may be configurable through the .mkchangelog file.
D. Template Rendering Engine:
- Uses Jinja2 to render the final changelog output.
- The built-in templates are stored under src/mkchangelog/templates.
- Includes a custom filter system enabled via hooks (see .mkchangelog.d/hooks.py) that allows additional filters (e.g., fancylize, underline, regex_replace).
E. File System Integration:
- Handles files under .mkchangelog.d/versions for additional version-specific header, footer, and commit text file inputs.
F. Configuration and Hooks:
- The settings, loaded from configuration files (e.g., .mkchangelog, and .mkchangelog.d/hooks.py) feed into nearly all modules.
- The hooks system lets you extend functionality (like template filter registration and custom commit filtering).

##### Architectural Patterns and Relationships
- There is a clear separation of concerns: CLI parsing, core processing, version generation, and rendering are all in separate modules.
- The design leverages a plugin system (hooks) which is key for extensibility.
- Data flows from the configuration component to the version provider and parser, then to the rendering engine, and finally output to a file (default CHANGELOG.md) or stdout.
- The inclusion of additional static files (commits, headers, footers) enhances modularity and customization per version.
- Commands call the core engine.
- Core engine interacts with both version providers and parsing modules.
- The rendered output is directed to deployment/output (either file system or a Docker entry point).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI (app.py)"]:::module
        COMMANDS["Command Handlers (commands)"]:::module
    end

    %% Core Processing Layer
    subgraph "Core Processing"
        CORE["Core Engine"]:::module
        PARSER["Commit Parser"]:::module
    end

    %% Version Providers Layer
    subgraph "Version Providers"
        GIT["Git Tag Provider"]:::module
        DATE["Date-based Provider"]:::module
    end

    %% Output Generation Layer
    subgraph "Output Generation"
        TEMPLATE["Template Renderer (Jinja2)"]:::module
        OUTPUT["Output (CHANGELOG.md/stdout)"]:::output
    end

    %% Global Configuration and Hooks
    CONFIG["Configuration Module"]:::config
    HOOKS["Hooks/Plugin System"]:::plugin
    FILES["File System Integration (.mkchangelog.d/versions)"]:::external

    %% Connections
    CLI -->|"parsesArgs"| COMMANDS
    COMMANDS -->|"dispatchesCmds"| CORE
    CORE -->|"parsesCommits"| PARSER
    CORE -->|"fetchesVersion"| GIT
    CORE -->|"orSelectsDateBased"| DATE
    CORE -->|"generatesChangelog"| TEMPLATE
    TEMPLATE -->|"writesOutput"| OUTPUT
    FILES -->|"providesHeadersFooters"| TEMPLATE

    %% Dotted arrows for configuration/hook influences
    CONFIG -.->|"configures"| GIT
    CONFIG -.->|"configures"| DATE
    CONFIG -.->|"configures"| TEMPLATE
    CONFIG -.->|"settings"| CORE
    HOOKS -.->|"plugins"| TEMPLATE
    HOOKS -.->|"extends"| CORE

    %% Styles
    classDef module fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef config fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef plugin fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef output fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/onjin/mkchangelog/blob/master/src/mkchangelog/app.py"
    click COMMANDS "https://github.com/onjin/mkchangelog/tree/master/src/mkchangelog/commands"
    click CORE "https://github.com/onjin/mkchangelog/blob/master/src/mkchangelog/core.py"
    click CORE "https://github.com/onjin/mkchangelog/blob/master/src/mkchangelog/lib.py"
    click PARSER "https://github.com/onjin/mkchangelog/blob/master/src/mkchangelog/parser.py"
    click GIT "https://github.com/onjin/mkchangelog/blob/master/src/mkchangelog/providers.py"
    click DATE "https://github.com/onjin/mkchangelog/blob/master/src/mkchangelog/providers.py"
    click CONFIG "https://github.com/onjin/mkchangelog/blob/master/src/mkchangelog/config.py"
    click CONFIG "https://github.com/onjin/mkchangelog/blob/master/.mkchangelog"
    click TEMPLATE "https://github.com/onjin/mkchangelog/blob/master/src/mkchangelog/renderers.py"
    click TEMPLATE "https://github.com/onjin/mkchangelog/tree/master/src/mkchangelog/templates"
    click HOOKS "https://github.com/onjin/mkchangelog/blob/master/src/mkchangelog/hookspecs.py"
    click HOOKS "https://github.com/onjin/mkchangelog/blob/master/.mkchangelog.d/hooks.py"
    click FILES "https://github.com/onjin/mkchangelog/tree/master/.mkchangelog.d/versions"
```
