Design

Wat is het doel van hoofdstuk 5?

De ontwerpkeuzes voor de architectuur van het systeem beschrijven: wat is ontworpen welke keuzes zijn gemaakt en hoe het ontwerp zich tijdens de realisatiefase heeft ontwikkeld. De diagrammen dienen als bewijs voor de competentie Design en tonen aan dat een complex systeem op meerdere abstractieniveaus gemodelleerd kan worden.

Op hoeveel abstractieniveaus is de architectuur uitgewerkt en welke zijn dat?

Vijf niveaus: (1) ERD — statische datastructuur (2) DFD — globale datastroom (3) Sequence Diagram — exacte chronologische interacties (4) Job Flow — gebruikersperspectief op het aanmaken van een job en (5) Data Validatie Flow — het validatieproces vanuit reviewerperspectief.

Wat is de centrale tabel in het datamodel en wat definieert deze?

"scraper_job_types": deze definieert wat een scraping job is — de te scrapen URL de gebruikte AI-provider het gebruikte model en of resultaten goedkeuring vereisen ("needs_approval"). Het fungeert als template waarop meerdere "scraper_jobs" (uitvoeringen) worden gebaseerd.

Welke statussen kan een "scraper_job" doorlopen en waar is deze status machine een vertaling van?

NEEDS_REVIEW AI_APPROVED HUMAN_APPROVED of REJECTED. Dit is een directe vertaling van het human-in-the-loop principe uit hoofdstuk 3.3 en 4.1.

Wat wordt opgeslagen in "scraper_job_results" en wat is daar opvallend aan?

De resultaten van een uitvoering opgeslagen als ruwe JSON-data inclusief een "confidence_score".

Wat slaat de "validation_feedback"-tabel op?

De menselijke beoordeling: het oordeel van de reviewer de reden en de door AI gegeven betrouwbaarheidscore — zodat deze context bij volgende uitvoeringen meegestuurd kan worden.

Waarom is "agent_context_memory" een van de meest kenmerkende onderdelen van het ontwerp?

Deze tabel koppelt aan een job type een patroonbeschrijving een gewicht ("confidence_weight") voorbeelddata en een gebruiksteller. Hiermee implementeert het de lerende werking van het systeem: naarmate een job succesvol wordt uitgevoerd groeit het contextgeheugen en kan de AI steeds gerichter te werk gaan.

Welke configuratietabellen zijn er en wat doen ze?

"scraper_job_extraction_configuration" (extractie-parameters zoals confidence threshold en verwacht outputformaat) "scraper_job_settings" (job-specifieke instellingen) "scraper_job_resilience_settings" (parameters voor systeemrobuustheid) en "scraper_job_steps" (splitst een job op in stappen elk met eigen actie en selector).

Is het ERD tijdens het project veranderd en waarom is dat relevant om te kunnen uitleggen?

Ja naarmate de realisatie vorderde werden de eisen aan het datamodel concreter en zijn er kolommen en relaties toegevoegd die in het initiële ontwerp nog niet voorzien waren — dit toont een iteratieve op voortschrijdend inzicht gebaseerde ontwerpaanpak.

Waarom is bewust gekozen voor weergave die verantwoordelijkheden van componenten scheidt?

Om duidelijk te maken welk component waarvoor verantwoordelijk is binnen de datastroom wat bijdraagt aan separation of concerns op ontwerpniveau.

Hoe start de flow volgens het DFD?

De Laravel Cron Scheduler maakt op vaste intervallen nieuwe scraping jobs aan op basis van bestaande job types en plaatst ze als "PENDING" in de PostgreSQL database. De Python Worker pollt vervolgens op vaste intervallen de Laravel API om te checken of er nieuwe jobs klaarstaan.

Waarom is bewust gekozen voor polling via een API-laag in plaats van directe communicatie met Redis of de database?

Dit zorgt voor een duidelijke scheiding van verantwoordelijkheden en voorkomt dat de worker rechtstreeks toegang nodig heeft tot interne systemen.

Hoe wordt data daadwerkelijk geëxtraheerd — wordt de ruwe HTML naar het LLM gestuurd?

Nee. In plaats daarvan genereert het LLM eerst een AgentQL-query op basis van het verwachte schema en de historische context. Deze query wordt door de worker uitgevoerd op de pagina waarna de gevraagde data wordt geëxtraheerd.

Wat gebeurt er na de extractie volgens het DFD?

De worker berekent een confidence score en stuurt de resultaten via een HTTP PATCH callback terug naar Laravel inclusief de nieuwe status. Laravel verwerkt dit werkt de jobstatus bij en maakt een los resultaat-record aan voor menselijke beoordeling. Bij afkeuring pakt een aparte feedback worker de taak op en genereert het LLM op basis van de feedback een aangepaste prompt voor de volgende uitvoering van hetzelfde job type.

Wat is het verschil tussen het DFD en het Sequence Diagram?

Het DFD toont de datastroom op hoofdlijnen

het Sequence Diagram laat de exacte chronologische volgorde van berichten zien tussen alle betrokken componenten (gebruiker/reviewer Cron Scheduler Laravel Backend PostgreSQL Redis Queue Python Worker target website en LLM) en is het meest gedetailleerde diagram van het hoofdstuk.

Op welke twee manieren kan een job starten?

Ofwel triggert de Cron Scheduler een job automatisch volgens schema ofwel maakt of start een gebruiker een job handmatig via de webportal. In beide gevallen maakt Laravel een nieuwe ScrapingJob met status "PENDING" en plaatst het Job ID met metadata in de Redis queue.

Hoe claimt de Python Worker een job en wat gebeurt er vóór de daadwerkelijke scraping?

De worker pollt voortdurend de Redis Queue en claimt een beschikbare job expliciet via een PATCH-request naar Laravel waarna de status naar "QUEUED" gaan. Vóór het scrapen haalt de worker eerst historische context op uit "agent_context_memory" samen met het bijbehorende JSON-schema zodat de extractie rekening houdt met eerdere reviewer-feedback.

Hoe verloopt de navigatie en wat gebeurt er als de data niet op de huidige pagina staat?

De worker loopt over de vooraf gedefinieerde stappen uit "scraper_job_steps"

per stap laadt hij de pagina of voert een actie uit via Chromium en wordt de actuele DOM-status teruggegeven. Als de benodigde data niet op de huidige pagina staat maakt de worker een screenshot via AgentQL zodat een reviewer later kan beoordelen waar de data zich daadwerkelijk bevindt.

Hoe verloopt de extractiestap en confidence-berekening volgens het Sequence Diagram?

Na de navigatie genereert de worker op basis van het verwachte schema en de meegestuurde prompt of context een AgentQL-query via het gekozen LLM. Deze query wordt uitgevoerd op de pagina om de data te extraheren. Direct daarna berekent de worker de confidence score via de recursieve "calculate_confidence"-functie (beschreven in hoofdstuk 6.1).

Wat gebeurt er bij goedkeuring versus afkeuring door de reviewer?

Bij succes wordt de jobstatus "COMPLETED" bij falen "FAILED"

in beide gevallen wordt altijd een "scraper_job_result" aangemaakt met status "NEEDS_REVIEW". Bij goedkeuring wordt de status "HUMAN_APPROVED" en wordt het JSON-schema van de goedgekeurde data opgeslagen in "agent_context_memory" als referentie. Bij afkeuring wordt de status "REJECTED" pakt een feedback worker de taak op om een aangepaste prompt te genereren en op te slaan en wordt de oorspronkelijke job opnieuw gedispatched door Laravel via de Redis queue.

Wat is de "door RAG geïnspireerde laag" van het systeem precies?

Het opslaan van het JSON-schema van goedgekeurde data in "agent_context_memory" als referentiemateriaal dat bij toekomstige uitvoeringen wordt geraadpleegd — vergelijkbaar met hoe RAG historische data als naslagwerk gebruikt om hallucinaties te beperken (zie hoofdstuk 3.3).

Welke actoren/componenten en hun verantwoordelijkheden worden onderscheiden?

Vue.js/Cron (triggert jobs handmatig of via schema) Laravel Job handler (beheert jobs verwerkt callbacks/webhooks schrijft naar database) PostgreSQL (slaat jobstatus resultaten en feedback op) Redis Queue (buffert jobs asynchroon tussen Laravel en Worker) Python Worker (voert scraping uit communiceert met LLM API) Target Website (externe bron) en OpenAI LLM API (genereert extractiequeries voor AgentQL).

Voor welk publiek is dit diagram specifiek ontworpen en waarom?

Voor zowel technische als niet-technische stakeholders om de vijf stappen die een job doorloopt inzichtelijk te maken op een toegankelijker niveau dan het Sequence Diagram.

Beschrijf de dertig stappen van de Job Flow in eigen woorden?

(1) Een gebruiker logt in via de webportal en maakt een job aan opgeslagen in "scraper_job_types". (2) De Cron Scheduler checkt of een job uitgevoerd moet worden en plaatst deze in de Redis Queue. (3) De Python Worker pollt periodiek de Laravel endpoint en pakt een taak op zodra beschikbaar. (4) De worker haalt context op uit "agent_context_memory" genereert via een LLM een AgentQL-query voert de scraping uit en slaat het resultaat als JSON op in "scraper_job_results". (5) Een reviewer keurt het resultaat goed of af via de webportal

feedback wordt opgeslagen in "validation_feedback" en meegenomen in volgende uitvoeringen.

Waarvan is dit diagram de visuele uitwerking?

Van de human-in-the-loop strategie beschreven in hoofdstuk 3.3 en 4.1.

Is feedback geven door de reviewer verplicht ook bij correcte data en waarom is dat een bewuste keuze?

Ja de reviewer geeft verplicht feedback ongeacht of de data correct of incorrect is. Dit is bewust omdat ook positieve feedback bijdraagt aan het contextgeheugen van het systeem en de betrouwbaarheid van toekomstige uitvoeringen verhoogt — mits de context goed beheerd wordt (zie hoofdstuk 3.2).

Wat gebeurt er bij goedkeuring versus afkeuring in deze flow?

Bij goedkeuring wordt de data definitief als JSON opgeslagen in de database. Bij afkeuring wordt de job opnieuw in de Redis Queue geplaatst nu met de nieuwe feedback als aanvullende context zodat de AI zichzelf kan corrigeren zonder directe codewijzigingen — het systeem leert van zijn fouten via menselijke sturing.

Hoe zijn deze design patterns tot stand gekomen?

Ze zijn niet vooraf als expliciete keuze gemaakt maar organisch ontstaan tijdens de realisatie voortvloeiend uit de gekozen architectuur en gebruikte tools.

Leg het Job pattern uit?

De volledige scraping pipeline is georganiseerd rondom jobs die via een queue worden aangemaakt opgepakt en uitgevoerd. Dit scheidt het aanmaken van werk van het uitvoering ervan en maakt het systeem schaalbaar doordat meerdere workers parallel jobs kunnen verwerken.

Leg het Strategy pattern uit?

De Python worker is zo opgezet dat de onderliggende LLM-provider (OpenAI Gemini of Claude) uitwisselbaar is zonder dat de rest van de code hoeft te veranderen. De worker communiceert met een gestandaardiseerde interface waardoor het wisselen van provider een configuratiewijziging is in plaats van een codewijziging.

Leg het Callback pattern uit?

De communicatie tussen Laravel en de Python worker verloopt via een HTTP PATCH callback: na een scraping taak stuurt de worker het resultaat naar de Laravel API die dit onafhankelijk van de worker verwerkt. Dit zorgt voor losse koppeling tussen de twee systemen.

Leg het Repository pattern uit?

De Laravel backend gebruikt standaard Eloquent (Laravel's ORM) waardoor wijzigingen in de database zoveel mogelijk gescheiden blijven van de rest van de applicatie.

Wat is de rode draad die door alle vijf diagrammen heen loopt en waarom is dat belangrijk om te kunnen aantonen?

De jobstatus de scheiding tussen extractie en validatie en de feedbackloop komen op elk abstractieniveau terug. Dit toont aan dat de hybride structuur niet alleen theoretisch onderbouwd is (hoofdstuk 3 en 4) maar ook consequent vertaald is naar een werkbaar samenhangend technisch ontwerp — in plaats van losse geïsoleerde onderdelen.

Hoe sluit hoofdstuk 5 af en wat is de link naar hoofdstuk 6?

De diagrammen samen vormen de directe basis voor de technische realisatie die in hoofdstuk 6 wordt beschreven

de vier design patterns (Job Strategy Callback Repository) die tijdens de realisatie zijn ontstaan ondersteunen de onderhoudbaarheid en schaalbaarheid van het systeem.

Waarom is gekozen voor polling (Python Worker pollt de API) in plaats van een push-mechanisme zoals webhooks vanuit Laravel naar de worker?

Dit wordt niet expliciet beargumenteerd in de tekst maar volgt uit het ontwerpprincipe van separation of concerns: door de worker actief te laten pollen via een gestandaardiseerde API-laag hoeft Laravel geen directe netwerktoegang tot de worker te hebben en blijft de worker volledig onafhankelijk aanstuurbaar — een bewuste eenvoudigere koppeling dan een push-architectuur ten koste van enige latency tussen job-aanmaak en oppakken.

Wat is het risico van het verplicht maken van feedback bij elke job ook als de reviewer haast heeft?

Een risico is dat reviewers onder tijdsdruk oppervlakkige of weinig contextrijke feedback invullen wat de kwaliteit van "agent_context_memory" en daarmee de leereffectiviteit van het systeem zou kunnen verlagen — dit is een punt waar je op voorbereid kunt zijn ook al wordt het niet expliciet in de tekst benoemd.