ARCHITECTURE.md

Doel

SimpleHealthMonitor is een Joomla System Plugin voor het bewaken van de technische gezondheid van een Joomla-website.

De plugin voert zelfstandig een aantal health checks uit, berekent een Health Score en stelt een JSON-endpoint beschikbaar voor externe monitoringdiensten.

Architectuuroverzicht

                 Frontend Request
                        │
                        ▼
              SimpleHealthMonitor Plugin
                        │
                        ▼
                 HealthService
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
  ContentCheck     MailCheck     SchedulerCheck
        │               │               │
        └───────────────┼───────────────┘
                        ▼
                HealthResult[]
                        │
                        ▼
                 HealthStatus
                        │
          ┌─────────────┴─────────────┐
          ▼                           ▼
   Backend presentatie          JSON Endpoint

De plugin bestaat uit een kleine set duidelijk gescheiden componenten. Iedere laag heeft een eigen verantwoordelijkheid en kent uitsluitend de componenten die noodzakelijk zijn voor haar taak.

Architectuurprincipes

Business First

Alle businesslogica bevindt zich binnen de plugin.

De businesslaag bepaalt:

• welke controles worden uitgevoerd;
• hoe de Health Score wordt berekend;
• wanneer een website als gezond of ongezond wordt beschouwd;
• welke informatie aan de beheerder of een monitoringdienst wordt geleverd.

Joomla First

SimpleHealthMonitor volgt zoveel mogelijk de architectuur en conventies van Joomla.

Waar Joomla bestaande voorzieningen biedt, worden deze gebruikt.

Voorbeelden hiervan zijn:

• Plugin Events;
• HTTP Client;
• Registry;
• Language API;
• Plugin Parameters;
• Installer Script.

Administrator First

De configuratie van SimpleHealthMonitor is geschreven voor websitebeheerders.

Technische implementatiedetails blijven zoveel mogelijk verborgen.

Instellingen zijn begrijpelijk zonder kennis van de interne architectuur of de gebruikte Joomla API's.

Hierdoor blijft de plugin eenvoudig te configureren zonder afbreuk te doen aan de onderliggende architectuur.

Constructor Injection

Waar Joomla dit op een natuurlijke wijze ondersteunt, worden afhankelijkheden via Constructor Injection aangeboden.

Wanneer dit de architectuur niet vereenvoudigt of Joomla hiervoor geen duidelijke ondersteuning biedt, wordt bewust gekozen voor een eenvoudige implementatie volgens het KISS-principe.

Resultaatgestuurd ontwerp

Iedere health check retourneert een uniform HealthResult.

Presentatielagen interpreteren uitsluitend dit resultaat en bevatten geen businesslogica.

Hierdoor kunnen backendpresentatie en JSON-uitvoer dezelfde businessresultaten gebruiken zonder duplicatie.

Geen database-afhankelijkheid

De plugin maakt geen eigen databasetabellen aan.

Alle configuratie wordt opgeslagen in de pluginparameters (#__extensions.params).

De plugin blijft hierdoor volledig zelfstandig en eenvoudig te installeren of verwijderen.

Hoofdcomponenten

System Plugin

De Joomla System Plugin vormt het startpunt van de extensie.

Verantwoordelijkheden:

• afhandelen van het health endpoint;
• tokenvalidatie;
• uitvoeren van de HealthService;
• bepalen van de HTTP-statuscode;
• retourneren van JSON.

De plugin bevat geen businesslogica rondom health checks.

HealthService

HealthService vormt de centrale orchestrator van de businesslaag.

Verantwoordelijkheden:

• uitvoeren van alle beschikbare health checks;
• verzamelen van alle HealthResult-objecten;
• berekenen van de totale Health Score;
• bepalen van de algemene healthstatus;
• retourneren van een HealthStatus.

HealthService kent uitsluitend de uitvoering van de checks en bevat geen kennis over HTML, JSON of HTTP.

Health Checks

Iedere health check heeft exact één verantwoordelijkheid.

De plugin bevat de volgende health checks:

• Content Check
• Mail Check
• Scheduler Check

Iedere check:

• voert zelfstandig zijn controle uit;
• bepaalt zelfstandig de penalty;
• bepaalt zelfstandig de melding;
• levert optioneel een HealthAction;
• retourneert altijd één HealthResult.

Health checks kennen geen onderlinge afhankelijkheden.

Domeinmodel

HealthResult

Een HealthResult beschrijft de uitkomst van één health check.

Een resultaat bestaat uit:

• naam;
• status;
• penalty;
• melding;
• detailinformatie;
• optionele HealthAction.

Hierdoor gebruiken alle onderdelen van de plugin hetzelfde contract.

HealthAction

Een HealthAction beschrijft een optionele vervolgstap voor de beheerder.

Een action:

• beïnvloedt nooit de Health Score;
• beïnvloedt nooit de status;
• bevat uitsluitend presentatiedata;
• helpt de beheerder een probleem op te lossen.

Iedere health check blijft eigenaar van zijn eigen acties.

HealthStatus

HealthStatus vertegenwoordigt de totale gezondheid van de website.

Het object bevat:

• algemene status;
• totale Health Score;
• configureerbare threshold;
• alle uitgevoerde health checks.

Hiermee vormt HealthStatus het centrale resultaat van de businesslaag.

HealthCheckStatus

Iedere health check gebruikt de PHP Enum HealthCheckStatus.

Beschikbare statussen:

UNKNOWN is uitsluitend bedoeld voor situaties waarin de controle zelf geen betrouwbaar resultaat kan bepalen.

Een UNKNOWN verhoogt nooit de Health Score.

Health Score

Iedere health check bepaalt uitsluitend zijn eigen penalty.

De totale Health Score wordt berekend door HealthService als de som van alle penalties.

Wanneer de totale score gelijk is aan of hoger is dan de configureerbare threshold, wordt de website als ongezond beschouwd.

Hierdoor blijven de verantwoordelijkheden duidelijk gescheiden:

• Health Checks bepalen individuele penalties;
• HealthService berekent de totaalscore;
• HealthStatus bepaalt de uiteindelijke status.

Ondersteunende services

HttpService

Verantwoordelijkheden:

• uitvoeren van HTTP-verzoeken;
• configureren van de Joomla HTTP Client;
• afhandelen van transportfouten;
• afschermen van de transportlaag voor de businesslogica.

Health checks bevatten hierdoor uitsluitend businesslogica.

EndpointUrlService

Verantwoordelijkheden:

• bepalen van de frontend URL;
• opbouwen van de Health Endpoint URL;
• interpreteren van live_site;
• terugvallen op Uri::root() wanneer nodig.

Alle kennis over de endpointstructuur bevindt zich op één centrale plaats.

AdminUrlService

Verantwoordelijkheden:

• centraal beheren van Administrator-URL's;
• voorkomen van duplicatie;
• afschermen van Joomla-routering voor de businesslaag.

Health checks kennen hierdoor uitsluitend de gewenste beheeractie.

Backend-presentatie

De plugin toont de resultaten van iedere health check binnen de pluginconfiguratie.

De backend:

• presenteert uitsluitend DTO's;
• bevat geen businessregels;
• toont statussen met Bootstrap-badges;
• toont optionele HealthAction-knoppen;
• presenteert aanvullende detailinformatie zonder deze te interpreteren.

Alle betekenis van de gegevens blijft eigendom van de businesslaag.

JSON Endpoint

Het frontend endpoint publiceert de volledige Health Status als JSON.

Het endpoint gebruikt drie HTTP-statuscodes:

Hierdoor kan de plugin direct worden gebruikt door externe monitoringdiensten.

Installer

De installer is uitsluitend verantwoordelijk voor installatiegerelateerde werkzaamheden.

Verantwoordelijkheden:

• activeren van de plugin;
• legen van relevante Joomla-caches;
• ondersteunen van Joomla-installatie en updates.

De installer bevat geen runtime-businesslogica.

Configuratie

Alle configuratie wordt opgeslagen in de pluginparameters.

Er worden geen aanvullende configuratietabellen gebruikt.

De plugin blijft eigenaar van alle configuratie.

Codekwaliteit

SimpleHealthMonitor volgt de volgende uitgangspunten:

• UTF-8 zonder BOM;
• declare(strict_types=1);;
• Joomla Coding Standards;
• kleine, duidelijk afgebakende services;
• gebruik van PHP 8.1 Enums waar dit de domeinlogica verduidelijkt;
• resultaatgestuurde businesslaag;
• geen duplicatie van businesslogica;
• geen deprecated Joomla API's.

Compatibiliteit

Primair

• Joomla 6

Compatibel met

• Joomla 5.4

Architectuurtoets

Iedere wijziging moet positief kunnen beantwoorden:

• Blijft alle businesslogica eigendom van de plugin?
• Volgt de oplossing Joomla Core-conventies?
• Is de verantwoordelijkheidsverdeling duidelijk?
• Blijven businesslogica en presentatie gescheiden?
• Gebruiken alle health checks hetzelfde resultaatmodel?
• Verhoogt een UNKNOWN nooit de Health Score?
• Blijft iedere health check eigenaar van zijn eigen penalty en eventuele HealthAction?
• Kan nieuwe functionaliteit worden toegevoegd zonder bestaande businesslogica te dupliceren?
• Blijft de plugin zelfstandig bruikbaar zonder aanvullende databaseobjecten?
• Blijft de configuratie begrijpelijk voor websitebeheerders?