Voor ontwikkelaars

Architectuur

De grenzen tussen Core, optionele domeinfuncties, provideradapters en presentatie.

Op deze pagina

Eén modulaire Laravel-applicatie

Agovena is een modulaire monoliet. Core, ingeschakelde Modules, Extensions en het gekozen Theme draaien binnen dezelfde Laravel-applicatie. Het zijn geen afzonderlijk te deployen services. De winkel en klantomgeving gebruiken servergerenderde views en Livewire. De geversioneerde klant-API biedt daarnaast een HTTP-interface voor geselecteerde handelingen.

De dependencyvoorwaarden staan in composer.json: PHP ^8.3, Laravel ^13.8, Livewire ^4.4 en Sanctum ^4.3. Raadpleeg het lockbestand voor de exacte versies van je checkout. Vite bouwt de frontendbestanden; PHP handelt de productieverzoeken af.

Kies de juiste laag

Laag	Verantwoordelijkheid	Voorbeeld	Hoort hier niet
Core	Gedeelde commercemodellen, applicatieservices, registraties, beveiliging en packageruntime	Bestellen, facturen, normalisatie van betalingen	De provisioning-API van één leverancier
Module	Een optioneel domein met eigen gegevensopslag	Evenementen, digitale levering, provisioning	Alle providerimplementaties voor dat domein
Extension	Een adapter of bijdrage aan een bestaand uitbreidingspunt	Betaalgateway, vervoerder, checkoutvereiste	Een tweede bestel- of facturatiedomein
Theme	Presentatie van de winkel en eventueel Admin	Layouts, native CSS, vormgevingsinstellingen, foutpagina's	Autorisatie, voorraadreservering, betaalstatussen wijzigen

Een product kan meerdere capabilities hebben. Voeg daarom geen permanente winkeltypekeuze toe aan Core om fysieke producten, digitale levering en provisioning van elkaar te scheiden. Core Physical Commerce en Availability registreren bijvoorbeeld de product-capabilities physical en availability, bewaren voorraad in hun eigen modellen en luisteren naar bestelevents. Bekijk AvailabilityCapability en de runtimetests.

Indeling van de repositories

text

agovena-platform/
  app/Agovena/          Applicatieservices en publieke integratiecontracten
  app/Http/            API-controllers, resources en middleware
  app/Livewire/        Servergestuurde schermen van Core
  app/Models/          Gedeelde datamodellen
  app/Events/          Domeinevents van Core
  routes/              Webroutes en geversioneerde API-routes
  database/            Core-migraties, factories en seeders
  themes/default/      Referentiepresentatie voor winkel en Admin
  tests/               Core-tests en package-integratietests
optional-packages/
  modules/<id>/        Optionele domeinpackages
  extensions/<group>/<id>/  Providerpackages

De ontdekking van Modules begint bij storage/app/packages/modules, gaat daarna naar de ingestelde optional-packages-checkout en eindigt bij agovena.packages.extra_module_paths. Extensions gebruiken dezelfde volgorde voor hun extensions-mappen. Het eerste manifest met een bepaald ID wint. Een geïnstalleerde kopie kan daardoor de ontwikkelkopie in de sibling-repository verbergen. Controleer dus welk pad de applicatie werkelijk gebruikt.

Voor lokaal packagewerk wijs je Core naar de naastgelegen repository:

dotenv

AGOVENA_OPTIONAL_PACKAGES_PATH=../optional-packages

Deze instelling maakt packages vindbaar, maar activeert ze niet. Installeren en inschakelen blijven aparte stappen. Zie Modules en Extensions.

Van request naar domeinhandeling

bootstrap/app.php registreert web-, API-, console- en healthroutes. Het bestand voegt installatiecontroles, taalkeuze, beveiligingsheaders, stateful Sanctum-ondersteuning en het IP-beleid voor API-tokens toe. API-fouten worden JSON-responses in plaats van redirects naar het inlogscherm.

AgovenaServiceProvider verbindt services en registraties. Buiten unittests start deze provider eerst de ingeschakelde Modules en daarna de Extensions. Vervolgens wordt het actieve Theme bepaald en de viewnamespace theme:: geregistreerd. Voor Admin kan Default worden gebruikt als het actieve Theme geen Admin-ondersteuning aangeeft.

Een doorsnee API-request doorloopt:

Routemiddleware voor authenticatie, tokenbevoegdheden en snelheidslimieten waar die van toepassing zijn.
Een controller die invoer valideert en de ingelogde klant bepaalt.
Een applicatieservice die domeinregels toepast en wijzigingen opslaat.
Een resource of expliciete serializer die de publieke uitvoervelden kiest.

De huidige v1-controllers gebruiken Request::validate(). Er is voor deze endpoints geen aparte API-FormRequest waarop je het contract kunt baseren. Ook de fillable-velden van een model bepalen niet welke API-invoer geldig is. Lees controller, aangeroepen service en resource samen.

Commerce en neveneffecten

PlaceOrder coördineert geconfigureerde winkelwagenregels, adressen, prijzen, verzending, kortingen, belastingen, klanteigenschappen en idempotentie. De client stuurt keuzes en aantallen, niet de definitieve totalen. De API-controller ontsluit bovendien maar een deel van de invoer van deze service. Een serviceparameter is niet automatisch een API-veld.

Een betaling starten en een betaling bevestigen zijn verschillende handelingen. HandlePaymentWebhook verifieert het inkomende providerbericht, bewaart een idempotent event en past de genormaliseerde betaalstatus toe. Een terugkerende browserredirect is geen betalingsbewijs.

Interne eventlisteners voeren domeingevolgen uit. Uitgaande HTTP-webhooks gebruiken een apart wachtrijsysteem en een expliciete eventcatalogus. Niet ieder intern event is dus automatisch een publieke webhook. Zie Events en webhooks.

Houd de grenzen intact

Hergebruik applicatieservices vanuit Livewire en de API, zodat financiële regels niet worden gedupliceerd.
Beperk klantgegevens in de query of controller tot de eigenaar. Een tokenbevoegdheid geeft geen toegang tot andere klanten.
Registreer capabilities, navigatie, providers en checkoutvereisten via de daarvoor bestemde contextobjecten.
Houd geheimen buiten resources, URL's, logs, Theme-instellingen en publieke assets.
Test zowel ingeschakelde als uitgeschakelde packages. Optionele routes bestaan niet zolang de bijbehorende Module uitgeschakeld is.
Behandel v1 als een vroege geversioneerde interface, niet als een onveranderlijke compatibiliteitsbelofte.

Begin bij de API-overzicht voor integraties of bij bijdragen en testen voor broncodewijzigingen.