Magic Agent — Ecosysteem

Magic Agent — Ecosysteem

Product Multi-tenant AI agent platform voor B2B e-commerce.

---

Wat is Magic Agent?

Magic Agent is een multi-tenant AI agent platform voor B2B e-commerce. Klanten krijgen een eigen AI assistent die via WhatsApp, webchat en (straks) email/voice communiceert. De agent beantwoordt vragen, zoekt producten, maakt offertes en escaleert naar mensen wanneer nodig.

Dit is ons product. Het moet plug & play werken voor elke tenant.

---

Kritieke Regels

Danger

Deze regels gelden ALTIJD, zonder uitzondering.

1. GEEN hardcoded tenant namen — alles dynamisch uit DB of env vars
2. GEEN hardcoded poorten — uit agent registry of config
3. GEEN hardcoded credentials — alles via .env, NOOIT in code
4. GEEN wijzigingen aan tenant-specifieke code — fix het in de shared codebase
5. NOOIT direct op production — test lokaal eerst
6. Altijd backup VOOR wijziging — geen uitzonderingen
7. Bij twijfel: STOP en VRAAG

---

Ecosysteem Overzicht

/mnt/data/magic_omniverse/magic_agent/
├── agents-portal/          ← agents.magiceverse.online (React + Vite)
├── flowbuilder2/           ← FlowBuilder UI (React + ReactFlow)
├── widget/                 ← Chat widget (vanilla JS, plug & play)
├── backend/                ← Shared agent backend logic
├── escalation-server/      ← Human takeover system
├── webhook-server/         ← Incoming webhook handler
├── magic_agent_<tenant>/   ← Per-tenant agent code
├── agents/                 ← Agent registraties/configs
├── n8n-workflows/          ← N8N workflow exports
├── sql/                    ← Database schemas + migrations
└── init-db/                ← Database initialization scripts

---

Databases

Per-tenant Agent Database: magic_agent_<tenant>

Bevat per tenant: bot configuratie (naam, kleuren, welkomstteksten), conversation history, session management, flow definitions.

Caution

Elke tenant heeft een eigen database. NOOIT databases mixen of cross-tenant queries doen.

Portal Database: magic_agents_portal

Centrale database: users, sessions, OTP codes, agent registry.

Commerce Database: magic_b2b_<tenant>

Producten, klanten, offertes, orders. De agent LEEST hieruit, schrijft er NIET naar.

---

Poorten

Service	Poort	Beschrijving
Widget Server	4061	Chat widget hosting + config API
Agents Portal	11080	agents.magiceverse.online
FlowBuilder 2	11006	Flow editor UI
Escalation Server	varies	Human takeover
Per-tenant agents	11001-11099	Individuele agent APIs

---

Widget (Plug & Play)

Het widget is universeel — exact dezelfde code op elke tenant.

1. Storefront laadt widget-loader.js met data-agent=<tenant>
2. Loader haalt config op via /api/widget-config/<agent> (kleuren, naam, teksten uit DB)
3. Loader injecteert widget-core.js met de config

Niet per tenant wijzigen: widget-loader.js, widget-core.js, chat-widget/index.tsx

Wel per tenant: Database records in magic_agent_<tenant> (bot_name, colors, welcome messages)

Zie Chat Widget documentatie voor de volledige guide.

---

Agents Portal (agents.magiceverse.online)

Eigenschap	Waarde
Tech Stack	React 18 + TypeScript + Vite
Styling	Tailwind CSS + shadcn/ui
Theme	Light/white (zoals portal.magiceverse.nl)
Font	Geist Sans + Geist Mono
Primary Color	#EA357D (magenta)
Layout	Sidebar navigatie (shadcn dashboard stijl)
Auth	OTP via WhatsApp + Email

Design Regels

Do: shadcn/ui componenten, Tailwind utilities, CSS variabelen, Lucide icons, Skeleton loaders, empty states met actie.

Don’t: Poppins font, custom CSS, inline styles, AI slop (3-column grids, icon-circle cards), alert()/confirm(), console.log in productie.

---

Nieuwe Tenant Aanmaken

1. Database: CREATE DATABASE magic_agent_<tenant>
2. Schema: Run init-db/ scripts
3. Widget config: INSERT bot_name, colors, welcome messages
4. Agent registry: INSERT in magic_agents_portal.agent_registry
5. Agent code: Kopieer template uit magic_agent_default_agent/
6. PM2: Start agent process
7. Flows: Kopieer standaard welkom-flow
8. Testen: Widget laden, chat testen, flow testen

---

Code Sync Regels

Shared code (widget, portal, flowbuilder): Ontwikkel centraal, sync naar alle tenants, git commits.

Per-tenant code (magic_agent_<tenant>/): NIET syncen, elke tenant heeft eigen logic.

NOOIT syncen: .env, credentials, tenant-specifieke config, conversation history.

---

PM2 Services

Process	Beschrijving
magic-widget-server	Widget hosting (port 4061)
flow-builder-2	FlowBuilder UI (port 11006)
flow-api	Flow backend
agents-portal	Portal UI + API (port 11080)
escalation-server	Escalatie systeem
magic-agent-<tenant>	Per-tenant agent

---

Git Workflow

Commit format: feat: / fix: / refactor: / style: / docs: / chore:

Branches: master (production), feature/<naam>, fix/<naam>

---

Bekende Issues (QA Audit 2026-03-27)

Issue	Ernst	Status
9 onbeheerde DB pools	CRITICAL	Open
Hardcoded credentials	CRITICAL	Open
7 fetch calls zonder timeout	HIGH	Open
Session race conditions	HIGH	Open
FlowBuilder niet multi-user	MEDIUM	In progress
Widget brand_slug hardcoded	MEDIUM	Fixed

Zie JoDa Sign QA Audit voor het volledige rapport.