Magic Agent Widget

Magic Agent Chat Widget

Plug & Play Universeel widget component — werkt op elke tenant zonder code-aanpassingen.

---

Architectuur

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│   Storefront     │────▶│  Widget Server   │────▶│  Agent Database     │
│  (Next.js)       │     │  (port 4061)     │     │  magic_agent_<t>    │
│                  │     │                  │     │                     │
│  chat-widget/    │     │  widget-loader   │     │  bot_name, colors,  │
│  index.tsx       │     │  widget-core     │     │  welcome messages   │
└─────────────────┘     └──────────────────┘     └─────────────────────┘
        │                        │
        │ data-agent=<tenant>    │ /api/widget-config/<agent>
        │ data-tenant=<tenant>   │
        ▼                        ▼
   Automatisch afgeleid      Config uit DB
   uit NEXT_PUBLIC_BASE_URL  (kleuren, naam, taal)

Componenten

Component	Locatie	Functie
Widget Server	/mnt/data/magic_omniverse/magic_agent/widget/	Express server, host widget bestanden + API
widget-loader.js	Geserveerd door widget server	Lichtgewicht loader, haalt config op, injecteert widget-core
widget-core.js	Geserveerd door widget server	Volledige chat UI (242KB)
chat-widget/index.tsx	Per tenant storefront	Next.js component, injecteert loader script
wayne-chat-widget.tsx	Per tenant backend/admin	Admin dashboard widget
Agent Database	magic_agent_<tenant> PostgreSQL	Bot configuratie (naam, kleuren, teksten)

---

Plug & Play: Hoe Het Werkt

Het widget component is universeel — exact dezelfde code op elke tenant. Configuratie komt uit twee bronnen:

1. Tenant Detectie (automatisch)

Het component leidt de tenant naam af uit de NEXT_PUBLIC_BASE_URL environment variabele:

https://jodasign.magiceverse.online → jodasign
https://brinxx.magiceverse.online   → brinxx
https://spranz.magiceverse.online   → spranz

2. Widget Configuratie (uit Agent Database)

De widget-server haalt config op via /api/widget-config/<agent>. Alles zit in de magic_agent_<tenant> database:

Instelling	Voorbeeld (JoDa Sign)
bot_name	Luke
primary_color	#fcb900
secondary_color	#0a0a0a
accent_color	#fcb900
gradient_color	#e5a600
welcome_message_nl	Hallo, ik ben Luke. Waarmee kan ik je helpen?
welcome_message_en	Hello, I am Luke. How can I help you?
welcome_message_de	Hallo, ich bin Luke. Wie kann ich Ihnen helfen?
position	bottom-right
auto_speech	false

---

Nieuwe Tenant Toevoegen

1. Agent database aanmaken

   Maak een nieuwe PostgreSQL database magic_agent_<tenant> aan en vul de widget configuratie:

   -- Bot configuratie
   INSERT INTO widget_config (key, value) VALUES
     ('agent_name', '<tenant>'),
     ('brand_name', '<Bedrijfsnaam>'),
     ('bot_name', '<Bot Naam>'),
     ('primary_color', '#hexcode'),
     ('secondary_color', '#hexcode'),
     ('accent_color', '#hexcode'),
     ('welcome_message_nl', 'Hallo! Ik ben <Bot>, waarmee kan ik je helpen?'),
     ('welcome_message_en', 'Hello! I am <Bot>, how can I help you?');

2. Widget component is al aanwezig

   Het universele chat-widget/index.tsx zit in elke tenant storefront na sync vanuit development. Geen code-aanpassingen nodig.

3. Environment variabelen checken

   Zorg dat NEXT_PUBLIC_BASE_URL correct is in de storefront .env:

   storefront/.env

   NEXT_PUBLIC_BASE_URL=https://<tenant>.magiceverse.online

   Optionele overrides:

   NEXT_PUBLIC_WIDGET_AGENT=<tenant>     # Override tenant naam
   NEXT_PUBLIC_WIDGET_LANGUAGE=nl         # Override taal (default: nl)
   NEXT_PUBLIC_WIDGET_POSITION=bottom-right  # Override positie

4. Agent registreren in widget-server

   Voeg een fallback config toe aan widget-loader.js (optioneel, alleen voor als de API niet bereikbaar is):

   '<tenant>': {
     agent_name: '<tenant>',
     brand_name: '<Bedrijfsnaam>',
     bot_name: '<Bot Naam>',
     primary_color: '#hexcode',
     secondary_color: '#hexcode'
   }

5. Testen

   Open de storefront en controleer:

   • Widget verschijnt rechtsonder
   • Kleuren kloppen
   • Bot naam is correct
   • Welkomsttekst in juiste taal

---

Admin Widget (Support Agent)

De admin widget (wayne-chat-widget.tsx) injecteert de support_agent in het Medusa admin dashboard. Dit is een apart agent profiel dat voor alle tenants hetzelfde is.

Instelling	Waarde
Agent	support_agent
Bot naam	Wayne
Positie	bottom-left
Kleur	#CF0D65 (magenta)

---

API Endpoints

Endpoint	Methode	Beschrijving
/api/widget-config/<agent>	GET	Widget configuratie (kleuren, naam, teksten)
/api/chat	POST	Chat bericht sturen naar agent
/api/bookings	GET/POST	Booking slots beheren
/health	GET	Widget server status

---

Code Sync Workflow

Het widget component zit in de storefront (niet backend). Bij code sync vanuit development:

# Sync widget naar alle tenants
SOURCE="/mnt/data/magic_omniverse/magic_commerce/magic_development"
FILE="storefront/src/modules/common/components/chat-widget/index.tsx"

for tenant in magic_brinxx magic_default magic_jodasign ...; do
  TARGET="/mnt/data/magic_omniverse/magic_commerce/$tenant"
  cp "$SOURCE/$FILE" "$TARGET/$FILE"
done

Caution

De storefront moet opnieuw gebuild worden na sync: docker compose build storefront && docker compose up -d storefront

---

Troubleshooting

Probleem	Oorzaak	Oplossing
Widget verschijnt niet	Script niet geladen	Check browser console voor [MagicWidget] logs
Verkeerde kleuren	DB config niet geladen	Check /api/widget-config/<agent> response
”MagicAgentWidget not found”	widget-core.js niet geladen	Check widget-server PM2 process
Widget op beta	Beta check in component	Normaal — widget is uitgeschakeld op beta omgevingen
Fallback config	API niet bereikbaar	Widget gebruikt hardcoded fallback uit widget-loader.js

---

QA Audit Bevindingen

Zie JoDa Sign QA Audit voor bekende issues:

• CRITICAL: 9 onbeheerde database pools (110+ connections)
• CRITICAL: Hardcoded credentials in source code
• HIGH: 7 fetch calls zonder timeout
• HIGH: Session management race conditions