# joostvanwollingen/alerticorn architecture

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

## Overview

##### Project Type and Overall Purpose
- Alerticorn is a lightweight Kotlin library that sends notifications when tests (or code blocks) fail. It is designed to be easily integrated with various test frameworks (with built-in JUnit support and planned support for TestNG/Kotest) and supports multiple notification platforms.
- The framework’s core idea is to provide a pluggable notification system where different modules (notifiers) implement the common Notifier interface, and integration modules (like JUnit and TestNG) adapt Alerticorn for specific test runners.

##### Main Components
a. Core Module:
- This is the heart of Alerticorn (located under the “core” directory). It includes the API definitions (like Notifier, NotificationManager, Message, AlerticornMessage, and ConfigurationManager) and basic functionality.
- That the “Core” defines interfaces and common behaviors upon which other modules rely.

b. Notifier Implementations:
- Notifier modules such as “discord-notifier”, “slack-webhook-notifier”, and “teams-workflow-notifier”. Each provides a concrete implementation of the Notifier interface.
- That these modules register their implementations (via META-INF/services files) so that the core module can discover and use them, which demonstrates the pluggable architecture.
- You might also note that the “docs” directory contains documentation and architectural guidelines, including details about each notifier.

c. Integration/Testing Framework Modules:
- The “junit” module is used to integrate Alerticorn with JUnit (via a JUnit extension) to trigger notifications on test failures.
- The “testng” module indicates planned integration with TestNG.
- Optionally, mention that Kotest integration is “coming soon” as noted in the README.

d. Additional Modules and Artifacts:
- The build files (build.gradle.kts, settings.gradle.kts, gradle directory) indicating that this is a multi-module Gradle project.
- The documentation component (docs) where detailed guidelines, architecture description, and usage examples are available.

##### Relationships and Interactions
- Dynamic discovery through service loading (point out that each notifier is discovered via the META-INF/services mechanism).

##### Architectural Patterns and Design Principles
- “Pluggable” architecture pattern where the core exposes a set of interfaces (Notifier, MessageProvider, etc.), and external modules provide specific behaviors.
- Dependency Injection / Service Locator concepts – the system discovers notifier implementations at runtime.
- Mention modularity as a design principle, with clear separation (each notifier in its own module, separate modules for testing integrations).

##### Additional Elements to Include for Clarity
- Lines between components with annotations like “implements”, “calls”, “invokes on failure”, etc.
- Mention that the service locator pattern is used – you could include a note or an annotation “Service Loader” on the connection lines between “Core” and each individual notifier module.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Testing Framework Integrations
    subgraph "Testing Framework Integrations"
        JUnit["JUnit Integration Module\n(integrates with testing framework)"]:::integration
        TestNG["TestNG Integration Module\n(planned integration)"]:::integration
    end

    %% Core API/Engine
    Core["Core API/Engine\n(Defines Notifier interface & common behaviors)"]:::core

    %% Notifier Implementations
    subgraph "Notifier Implementations"
        Discord["Discord Notifier Implementation\n(Uses Discord APIs)"]:::notifier
        Slack["Slack Notifier Implementation\n(Uses Slack Webhook)"]:::notifier
        Teams["Teams Notifier Implementation\n(Uses Teams Webhook)"]:::notifier
    end

    %% External Notification Services
    subgraph "External Notification Services"
        DiscordAPI["Discord API"]:::external
        SlackWebhook["Slack Webhook"]:::external
        TeamsWebhook["Teams Webhook"]:::external
    end

    %% Project Artifacts
    subgraph "Project Artifacts"
        Docs["Documentation\n(Architectural guidelines & usage examples)"]:::docs
        Build["Build Config & Artifacts\n(Multi-module Gradle project)"]:::docs
    end

    %% Relationships
    JUnit -->|"calls"| Core
    TestNG -->|"calls"| Core

    Core -->|"discovers_via_ServiceLoader"| Discord
    Core -->|"discovers_via_ServiceLoader"| Slack
    Core -->|"discovers_via_ServiceLoader"| Teams

    Discord -->|"notifies"| DiscordAPI
    Slack -->|"notifies"| SlackWebhook
    Teams -->|"notifies"| TeamsWebhook

    %% Styles
    classDef core fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef notifier fill:#ccffcc,stroke:#339900,stroke-width:2px,rx:5,ry:5;
    classDef integration fill:#cce5ff,stroke:#3366cc,stroke-width:2px;
    classDef external fill:#e5ccff,stroke:#9933cc,stroke-width:2px,stroke-dasharray: 5 5;
    classDef docs fill:#ffe5cc,stroke:#cc6600,stroke-width:2px;

    %% Click Events
    click Core "https://github.com/joostvanwollingen/alerticorn/tree/main/core/src/main/kotlin/nl/vanwollingen/alerticorn/api"
    click Discord "https://github.com/joostvanwollingen/alerticorn/tree/main/discord-notifier/src/main/kotlin/nl/vanwollingen/alerticorn/discord"
    click Slack "https://github.com/joostvanwollingen/alerticorn/tree/main/slack-webhook-notifier/src/main/kotlin/nl/vanwollingen/alerticorn/slack"
    click Teams "https://github.com/joostvanwollingen/alerticorn/tree/main/teams-workflow-notifier/src/main/kotlin/nl/vanwollingen/alerticorn/teams"
    click JUnit "https://github.com/joostvanwollingen/alerticorn/blob/main/junit/src/main/kotlin/nl.vanwollingen.alerticorn.junit"
    click TestNG "https://github.com/joostvanwollingen/alerticorn/tree/main/testng/src/main/kotlin/nl/vanwollingen/alerticorn/testng"
    click Docs "https://github.com/joostvanwollingen/alerticorn/tree/main/docs/"
    click Build "https://github.com/joostvanwollingen/alerticorn/tree/main/gradle/"
```
