# thesimonho/herald-of-completion architecture

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

- Interactive diagram: https://gitdiagram.com/thesimonho/herald-of-completion
- Repository: https://github.com/thesimonho/herald-of-completion

## Overview

##### Main components
- Core Library (src/herald) – This includes the decorator logic (in decorators.py) that wraps target functions, utility functions (in utils.py) that perform notification sending, and data types (in types.py) that define the notification payload using TaskInfo.
- Messenger Modules (src/herald/messengers) – These modules encapsulate different messaging strategies (e.g. Discord, Email, Desktop) that implement an abstract “Messenger” interface. They are responsible for formatting and delivering the notification.
- Configuration (.env file) – Not directly checked in but referenced in the README, this file contains sensitive settings (webhook URLs, SMTP credentials) that the herald’s initialization and messenger classes read.
- Tests (tests) – Unit and integration tests verify intended functionality.
- Documentation & CI/CD (docs and .github folders) – These components provide documentation building and continuous integration workflows, which support code quality and deployment but are auxiliary to the core notification architecture.

##### Understand the relationships and interactions
- The user imports and initializes a “Herald” object (from src/herald/decorators.py), passing the path to a configuration file.
- The Herald instance takes one or more messenger instances (from src/herald/messengers) as arguments.
- When a decorated function is called, the decorator wraps its execution, catching the result or exceptions. It then builds a TaskInfo instance (from src/herald/types.py) with details of the execution.
- The utility function (in utils.py) or the decorator itself calls the “notify()” method on each assigned messenger, passing in the TaskInfo along with configuration read from the .env.
- The actual message sending is performed by each messenger’s implementation (e.g., DiscordMessenger, EmailMessenger) using their specific protocol details.

##### Architectural patterns and design principles
- Modular Design: Separation of concerns is clear – the core functionality (decorators, helpers, types) is independent from the actual messenger implementations.
- Extensibility: New messengers can be added simply by creating a new module under src/herald/messengers and implementing the abstract methods.
- Loose Coupling: The use of an abstract Messenger interface means adding or modifying notification channels does not affect the core decorator logic.
- Configurable Behavior: Externalizing settings to a .env file allows different environments (development/production) to use distinct configurations.

a. Start by listing and diagramming all major components:
- User Application Code (client functions decorated with @herald)
- Herald Module (core decorator and initialization logic)
- Messenger Components (DiscordMessenger, EmailMessenger, DesktopMessenger, etc.)
- TaskInfo Data Structure (defines the notification payload)
- Utility Functions (send_notification for manual messaging)
- Configuration (External .env settings)

- Another style for “messengers” to differentiate between types implementing the common interface.
- Different symbols for configuration files and external service endpoints.

##### Final checklist
- All main components (core decorator, messenger modules, utility, configuration) are clearly labeled.
- Notes on extensibility – how new messenger modules can be integrated without altering the core notification pipeline.

## Diagram (Mermaid)

```mermaid
graph TD
    UA["User Application Code"]:::client

    subgraph "Core Library"
        D["Decorator"]:::core
        U["Utils"]:::core
        T["Types"]:::core
    end

    subgraph "Messenger Modules"
        DT["Desktop Messenger"]:::messenger
        DC["Discord Messenger"]:::messenger
        EM["Email Messenger"]:::messenger
    end

    C["Configuration (.env)"]:::config
    ES["External Notification Services"]:::external

    subgraph "Supporting Infrastructure"
        TS["Tests"]:::auxiliary
        DOC["Documentation"]:::auxiliary
        CI["CI/CD"]:::auxiliary
    end

    UA -->|"calls_decorated_function"| D
    D -->|"creates_TaskInfo"| T
    D -->|"invokes_notify"| DT
    D -->|"invokes_notify"| DC
    D -->|"invokes_notify"| EM
    U -->|"sends_TaskInfo"| DT
    U -->|"sends_TaskInfo"| DC
    U -->|"sends_TaskInfo"| EM

    C -->|"provides_settings"| D
    C -->|"provides_settings"| U
    C -->|"provides_settings"| DT
    C -->|"provides_settings"| DC
    C -->|"provides_settings"| EM

    DT -->|"sends_notification"| ES
    DC -->|"sends_notification"| ES
    EM -->|"sends_notification"| ES

    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
    classDef messenger fill:#bbf,stroke:#333,stroke-width:2px;
    classDef config fill:#bfb,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#ffa,stroke:#333,stroke-width:2px;
    classDef client fill:#cff,stroke:#333,stroke-width:2px;
    classDef external fill:#fcc,stroke:#333,stroke-width:2px;

    click D "https://github.com/thesimonho/herald-of-completion/blob/master/src/herald/decorators.py"
    click U "https://github.com/thesimonho/herald-of-completion/blob/master/src/herald/utils.py"
    click T "https://github.com/thesimonho/herald-of-completion/blob/master/src/herald/types.py"
    click DT "https://github.com/thesimonho/herald-of-completion/blob/master/src/herald/messengers/desktop.py"
    click DC "https://github.com/thesimonho/herald-of-completion/blob/master/src/herald/messengers/discord.py"
    click EM "https://github.com/thesimonho/herald-of-completion/blob/master/src/herald/messengers/email.py"
    click TS "https://github.com/thesimonho/herald-of-completion/tree/master/tests"
    click DOC "https://github.com/thesimonho/herald-of-completion/tree/master/docs"
    click CI "https://github.com/thesimonho/herald-of-completion/blob/master/.github"
```
