How thesimonho/herald-of-completion works
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.