Tijdens de hackathon begonnen we met een kickoff waarin werd uitgelegd dat we dashboard widgets voor het Hyvä Commerce admin dashboard zouden bouwen. Daarna werden wensen en ideeën verzameld.

Ik besloot me te richten op een "QuickNav" widget: een snelle manier om direct naar een product, categorie, setting, CMS page, CMS block, URL rewrite of andere admin-entiteit te springen.

Het thema was AI Hackathon, dus iedereen liet zijn LLM's op volle toeren draaien. Ik koos voor Claude Code in combinatie met Claude in Chrome. Met claude --chrome kan Claude direct contact leggen met de browser, terwijl je zelf live ziet wat er gebeurt. Dat bleek heel waardevol, vooral bij UI-problemen die unit tests niet vinden.

Opzet en werkwijze

Met Bougie, een tool van mijn collega Jelle Besseling, had ik binnen een paar minuten een Magento omgeving draaiend. Daarna volgden sample data, Hyvä Commerce en de Hyvä theme.

Interessanter is wat ik daarna deed: ik bouwde eerst de AI-context, niet de applicatie. Ik liet een skills/hyva-widgets skill maken op basis van de Hyvä Commerce dashboard-widget documentatie. Dat was achteraf een goede investering. In plaats van Claude telkens opnieuw uit te leggen hoe Hyvä dashboard widgets werken, kreeg Claude project-specifieke instructies en voorbeelden om op terug te vallen.

Eerst specificeren, dan bouwen

Nadat Hyvä Commerce draaide, legde ik Claude uit wat ik wilde maken en hoe ik wilde samenwerken. De eerste echte designprompt was ongeveer:

Ik wil een widget maken die werkt als QuickNav voor users. Navigeren naar settings, product pages, category pages, storeview settings, etc. moet easy en fast zijn. Kinda like configuration panel in Windows or KDE. Icons, search, URL paste, category page, product page, en dan kunnen navigeren naar de category page of producten op die page. Het moet snel zijn en Magento indexes gebruiken waar mogelijk. Het moet "monkey proof" zijn: mijn oma moet het kunnen gebruiken.

Daarna liet ik Claude een design document maken in design/design.md. Na een paar feedbackrondes, plus input van andere developers, ontstond een duidelijke eerste scope: een command-palette achtige zoekervaring voor Magento Admin. Denk aan VS Code, Spotlight of Alfred, maar dan gericht op Magento beheer.

De belangrijkste ontwerpregel was dat het intuïtief moest zijn. Als een niet-technische admin niet binnen een paar seconden begrijpt hoe hij iets vindt, is het ontwerp mislukt.

AI-vriendelijke taakstructuur

Een van de nuttigste keuzes was om het grote specificatiedocument niet direct te laten implementeren. Ik liet Claude het eerst opsplitsen in losse feature-documenten:

design/001-feature-trigger-ui/
design/002-feature-search/
design/003-feature-url-paste/
design/004-feature-category-drilldown/
design/005-feature-scope-awareness/
design/006-feature-access-control/
design/007-feature-search-limiters/
design/008-feature-personalization/
design/009-feature-global-overlay/
design/010-feature-security-audit/

‍
Elke feature ging vervolgens in kleine taken met een vaste naming convention:

feature-complete.md
NNN-feature-requirements.md
NNN-feature-tests.md
steps/NNN-MM-task.md
steps/NNN-MM-task-tests.md
progress.md

Bijvoorbeeld:

001-06-keyboard-navigation.md
001-06-keyboard-navigation-tests.md
002-05-product-provider.md
002-05-product-provider-tests.md

Dat leverde veel kleine bestanden op, maar juist daardoor kon de AI zich per stap focussen. Elke taak had ook testcriteria: hoe een computer dit met unit of integration tests kon controleren, en hoe een mens het in de browser kon verifiëren.

Voor developers is dit misschien wel de belangrijkste les uit de hackathon: de winst zat niet alleen in "AI schrijft code", maar vooral in context-management. Kleine, duidelijke taken voorkomen dat de LLM verdwaalt in een groot feature-idee. Datzelfde gold voor progress.md en memory.md. Toen sessies eindigden, tokens opraakten of de machine opnieuw moest starten, kon Claude verder waar hij gebleven was, met concrete status in plaats van "ongeveer hier ergens".

Wat er gebouwd is

De eerste implementatie probeerde nog een fallback naar oude Magento templating mee te nemen. Dat heb ik eruit laten halen. Het doel was niet om een generieke Magento widget te maken, maar een Hyvä Commerce admin dashboard widget. Door die keuze werd de code lichter en beter te volgen: geen compatibility-laag voor een route die we niet wilden ondersteunen.

Search: snel door bestaande Magento indexen

Een belangrijk performanceprobleem was dat de eerste versie te veel live data probeerde te doorzoeken. Dat voelde niet "snappy" genoeg. Ik gaf Claude daarom de hint om bestaande Magento indexen te gebruiken waar mogelijk.

In de geschiedenis is mooi terug te zien dat ik Claude daar moest terugduwen naar de Magento manier. Op een gegeven moment was Claude aan het over-engineeren, waarna ik aangaf dat een normale Magento indexer logischer was: dagelijks volledig, en incrementeel bij wijzigingen zoals Magento dat zelf ook doet.

Voor categorieën werd bijvoorbeeld gezocht op EAV-waarden zoals naam en url_path, maar productaantallen kwamen uit de bestaande index:

$indexTable = $this->resourceConnection
    ->getTableName('catalog_category_product_index_store' . $storeId);

return $connection->fetchPairs(
    $connection->select()
        ->from($indexTable, ['category_id', 'count' => new \Zend_Db_Expr('COUNT(*)')])
        ->where('category_id IN (?)', $categoryIds)
        ->where('store_id = ?', $storeId)
        ->group('category_id')
);

De tradeoff was acceptabel: producten of pagina's die nog niet geïndexeerd zijn, kunnen ontbreken. Maar voor een quick navigation tool is snelheid belangrijker dan een trage "perfecte" zoekactie. Voor de uitzonderingen bestaat de normale Magento route nog steeds.

Provider-based search

De zoeklaag werd opgebouwd rond providers. Elke provider zoekt in een type data: producten, categorieën, config sections, CMS pages, orders, customers, URL rewrites, search terms, enzovoort. De SearchService doet de fan-out, ranking en limiter-logica:

foreach ($providers as $provider) {
    foreach ($provider->search($searchText, $this->perProviderLimit) as $result) {
        $results[] = $result;
    }
}

usort($results, function (SearchResult $a, SearchResult $b): int {
    if ($a->matchTier !== $b->matchTier) {
        return $a->matchTier <=> $b->matchTier;
    }

    return strcasecmp($a->label, $b->label);
});

Dit maakte de module goed uitbreidbaar. Een nieuwe entiteit toevoegen werd meestal zo gedaan: provider maken, DI configureren, resultaatcontract volgen, tests schrijven.

Search limiters

Tijdens feedback kwam de vraag: wat als ik direct een product wil zoeken? In Magento's standaard admin search kun je wel een product zoeken, maar daarna kom je vaak alsnog op een grid. Eerst moet die grid laden, dan moet de lijst laden, dan klik je het product aan en wacht je opnieuw. QuickNav moest directer zijn.

Daarom kwamen search limiters erbij. Als je query begint met bijvoorbeeld product, category, config, block, page, rewrite, customer of order, wordt alleen die provider gebruikt.

[$firstWord, $remainder] = array_pad(
    preg_split('/\s+/', trim($query), 2),
    2,
    ''
);

if ($remainder === '' || ! isset($this->keywordMap[$keyword])) {
    return null;
}

Dus:

product bag
category bags
page about
rewrite home
customer veronica

De UI toont dat je beperkt zoekt, met een optie om de limiter te verwijderen en alsnog breed te zoeken. Dit bleek een goede middenweg: standaard breed genoeg voor beginners, maar gericht genoeg voor power users.

URL paste handling

Een sterke feature werd URL paste handling. Als je een storefront URL plakt, probeert QuickNav die via url_rewrite te herleiden naar de juiste admin edit page. Een product URL opent direct het product in admin, een categorie URL opent direct de categorie:

http://hackathon.bougie.run:7080/joust-duffle-bag.html
http://hackathon.bougie.run:7080/gear/bags.html

Hier zat een goede UX-regel achter: als iets duidelijk een URL is en binnen de store valt, maar niet gevonden wordt, toon dan een specifieke melding. Niet stilletjes alsnog de hele URL door alle providers halen.

Category drilldown

Categorie-resultaten kregen twee acties: categorie bewerken, en producten in deze categorie bekijken. Magento heeft niet echt een nette, index-backed admin deep link naar dat tweede. De standaard product grid ondersteunt niet simpelweg een category_id filter via URL params, en de category edit page heeft zijn eigen productpaneel. Daarom kwam er een kleine read-only pagina binnen de module zelf:

quicknav/category/products?category_id=N

Die pagina gebruikt een service class voor de query, zodat de logica unit-testbaar blijft zonder Block/ObjectManager gedoe. Ook dit kwam uit een praktische fout: de eerste poging om de logic direct in een Block te stoppen was lastig te testen, omdat Magento Template Blocks intern een ObjectManager bootstrap verwachten.

Scope awareness

Voor configuratie en producten kwam store-view awareness erbij. Bij een config-resultaat kun je direct kiezen tussen Default Config, website scope of store-view scope; producten kunnen direct in store-view mode geopend worden.

Belangrijk detail: die URL's worden server-side met Magento's eigen backend URL builder opgebouwd. Als Magento zelf numerieke website- of store-params verwacht, moet QuickNav niet client-side gaan gokken hoe zo'n URL eruit hoort te zien.

Personalisatie: pinned, recent en most used

Na feedback kwamen ook pinned resultaten, recent gebruikte resultaten en most used bestemmingen erbij. Dit werd bewust client-side met localStorage gedaan, per admin user:

quicknav-pinned-<userId>
quicknav-recents-<userId>
quicknav-usage-<userId>

Ook hier was performance leidend. De live-search dropdown bleef licht en snel; thumbnails werden niet tijdens elke keystroke gerenderd. Product images werden alleen gebruikt in de empty state, waar de pinned en most-used tiles staan.

Global access module

Toen er nog tijd over was, bouwde ik een ondersteunende module: BigBridge_QuickNavAccess. Daarmee werd QuickNav niet alleen beschikbaar op het dashboard, maar ook via een header-icoon en Ctrl+K / Cmd+K op elke admin pagina.

De overlay hergebruikt de bestaande QuickNav widgetlogica. De access module beheert alleen openen, sluiten, focus restore en de keyboard shortcut:

if ((event.ctrlKey || event.metaKey) && key === 'k') {
    event.preventDefault();
    this.open();
}

Na login toont de module eenmalig een hint, zodat gebruikers de shortcut ontdekken zonder documentatie te hoeven lezen.