# hankanman/changelog-weaver architecture

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

- Interactive diagram: https://gitdiagram.com/hankanman/changelog-weaver
- Repository: https://github.com/hankanman/changelog-weaver

## Overview

##### Project Type and Purpose
- Changelog Weaver is essentially a CLI tool (with a __main__.py entry point) that automatically generates professional release notes.
- It supports multiple platforms (GitHub & Azure DevOps) for fetching work items and issues, processes them with GPT‐powered summarization, and outputs changelog files.
- The README clearly spells out details such as automated work item retrieval, multi-format output (Markdown and HTML), and CI/CD integration (via GitHub Actions and Azure pipelines).

##### Analyzing the File Structure
- Top-Level Files/Directories:
- Configuration files and environment templates (.env.template, setup files, requirements.txt)
- CI/CD artifacts (.github directory with workflows, pipelines directory)
- The core application code is under the “changelog_weaver” directory.
- Core modules within changelog_weaver include:
- __main__.py: serves as the entry point.
- changelog.py & work.py: likely contain the business logic for changelog generation.
- A “configuration” subdirectory handles configuration management (base_config, config, model, output, prompts).
- A “platforms” directory encapsulates API interactions with Azure DevOps and GitHub (devops_api, github_api, plus corresponding clients).
- “typings” and “utilities” add support for type definitions and helper functions.
- Evident CI/CD integration: GitHub Actions and Azure pipelines are explicitly provided, indicating an emphasis on automated build and deployment routines.

##### Key System Components and Relationships
- Input/Configuration Layer
- Components: .env file, configuration modules (in changelog_weaver/configuration/)
- Purpose: Collects environment variables and user-defined settings (e.g., API tokens, project URL, GPT API keys).
- Entry Point / Orchestration
- Component: changelog_weaver/__main__.py, and potentially work.py
- Role: Bootstraps the application, loads configuration, and directs the overall workflow.
- Platform API Clients
- Components: Modules under changelog_weaver/platforms (e.g., github_api.py, devops_api.py, alongside their respective client wrappers).
- Role: Responsible for interfacing with external service APIs to fetch work items or issues.
- GPT Summarization Engine Integration
- Mechanism: Likely embedded within the business logic in changelog.py (or configuration/prompts.py) where GPT is used to process fetched work items and summarize results.
- Project integrates with GPT using the provided GPT_API_KEY and model settings.
- Output Generation
- Components: Modules handling output (e.g., configuration/output.py).
- Role: Formats the summarization result into release notes (Markdown/HTML) and writes them to the specified folder.
- Supportive Modules
- Logger (changelog_weaver/logger.py): Handles logging throughout the execution.
- Typings (changelog_weaver/typings/): Provides type definitions to ensure consistency.
- Utilities (changelog_weaver/utilities/): Contains helper functions used across internal modules.

##### Architectural Patterns and Design Principles
- Modularity: Code is divided into distinct directories based on functionality (configuration, platforms, utilities), thereby emphasizing a separation of concerns.
- Extensibility: The configuration and platforms modules suggest that you could easily extend the tool to support additional platforms or modify GPT prompts.
- CI/CD Integration: The presence of YAML workflows in .github and pipelines directories highlights a design that is tightly integrated with automation and release cycles.
- Clean API Abstraction: The abstraction of platform-specific interactions (encapsulated in separate API client modules) allows for clear separation between the core logic and external services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        WP("GitHub Workflows"):::ci
        AP("Azure Pipelines"):::ci
    end

    %% Configuration Manager
    subgraph "Configuration Manager"
        ENV("Env Template"):::config
        CM("Configuration Modules"):::config
    end

    %% Orchestration / Entry Point
    subgraph "Orchestration"
        MAIN("Entry Point (__main__.py)"):::entry
        WORK("Work Orchestrator (work.py)"):::entry
    end

    %% Platform API Clients
    subgraph "Platform API Clients"
        GITHUB("GitHub API Client"):::platform
        AZURE("Azure DevOps API Client"):::platform
        PLATFORM("Platform Client"):::platform
    end

    %% GPT Summarization Engine Integration
    subgraph "GPT Summarization Engine"
        PROCESS("Changelog Processor (changelog.py)"):::gpt
        PROMPTS("GPT Prompts (prompts.py)"):::gpt
    end

    %% Output Generator
    subgraph "Output Generator"
        OUTPUT("Output Generator (output.py)"):::output
    end

    %% Support Modules
    subgraph "Support Modules"
        LOGGER("Logger"):::support
        UTIL("Utilities"):::support
        TYPINGS("Typings"):::support
    end

    %% Flow Connections
    WP --> MAIN
    AP --> MAIN

    ENV --> MAIN
    CM --> MAIN

    MAIN --> WORK

    WORK --> GITHUB
    WORK --> AZURE
    WORK --> PLATFORM

    GITHUB --> PROCESS
    AZURE --> PROCESS
    PLATFORM --> PROCESS

    PROMPTS --> PROCESS

    PROCESS --> OUTPUT

    %% Support Modules Connections (dashed lines represent supportive assistance)
    LOGGER -.-> MAIN
    UTIL -.-> GITHUB
    TYPINGS -.-> PLATFORM

    %% Styles
    classDef ci fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef config fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef entry fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef platform fill:#d2b4de,stroke:#6c3483,stroke-width:2px;
    classDef gpt fill:#fad7a0,stroke:#d35400,stroke-width:2px;
    classDef output fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
    classDef support fill:#d6eaf8,stroke:#3498db,stroke-width:2px;

    %% Click Events
    click ENV "https://github.com/hankanman/changelog-weaver/blob/main/.env.template"
    click CM "https://github.com/hankanman/changelog-weaver/tree/main/changelog_weaver/configuration/"
    click MAIN "https://github.com/hankanman/changelog-weaver/blob/main/changelog_weaver/__main__.py"
    click WORK "https://github.com/hankanman/changelog-weaver/blob/main/changelog_weaver/work.py"
    click GITHUB "https://github.com/hankanman/changelog-weaver/blob/main/changelog_weaver/platforms/github_api.py"
    click AZURE "https://github.com/hankanman/changelog-weaver/blob/main/changelog_weaver/platforms/devops_api.py"
    click PLATFORM "https://github.com/hankanman/changelog-weaver/blob/main/changelog_weaver/platforms/platform_client.py"
    click PROCESS "https://github.com/hankanman/changelog-weaver/blob/main/changelog_weaver/changelog.py"
    click PROMPTS "https://github.com/hankanman/changelog-weaver/blob/main/changelog_weaver/configuration/prompts.py"
    click OUTPUT "https://github.com/hankanman/changelog-weaver/blob/main/changelog_weaver/configuration/output.py"
    click LOGGER "https://github.com/hankanman/changelog-weaver/blob/main/changelog_weaver/logger.py"
    click UTIL "https://github.com/hankanman/changelog-weaver/tree/main/changelog_weaver/utilities/"
    click TYPINGS "https://github.com/hankanman/changelog-weaver/tree/main/changelog_weaver/typings/"
    click WP "https://github.com/hankanman/changelog-weaver/tree/main/.github/workflows/"
    click AP "https://github.com/hankanman/changelog-weaver/tree/main/pipelines/"
```
