docs/frontend_architecture.md

Frontend Architecture

Last Updated: 2026-03-08

---

Two Products, Two Different Tools

The project has two distinct frontend surfaces with different constraints:

Surface	Tool	Why
Chatbot widget	Preact + Shadow DOM	Embeddable, 3KB, no host-site conflicts
Admin panel	React (Vite + shadcn/ui)	Standalone SaaS, rich UI ecosystem needed

---

Chatbot Widget — Preact + Shadow DOM

Why Not React

The widget gets embedded in clients' websites via a <script> tag. If the host site also uses React (a common case), two React instances on the same page cause conflicts — state, events, and CSS bleed between them. React has no built-in isolation mechanism.

Why Preact

• 3KB gzipped (React is ~45KB). Third-party scripts must be small.
• 100% React-compatible API — same useState, useEffect, JSX, component model. Writing Preact IS writing React syntax.
• Bundled inline (IIFE format) — no shared global. Zero conflict with host's React, Vue, Angular, jQuery, or any framework.
• Real-world data: a widget case study went from 36KB (React) → 5.9KB (Preact) with identical functionality.

Why Shadow DOM

Shadow DOM is a native browser API that creates a fully isolated DOM tree:

• Host site CSS cannot leak into the widget
• Widget CSS cannot leak into the host site
• Browser support: 96%+ globally

Combined with Preact, the widget is self-contained — paste one <script> tag on any site (WordPress, Flask, Vue, plain HTML, Shopify, Webflow) and it works.

Packaging

• Build tool: Vite (outputs IIFE bundle)
• Output: single JS file, self-executing when loaded
• Shadow root attached to a custom element (<smart-chatbot>)

Known Caveats

1. Content Security Policy (CSP) Security-hardened sites (banks, enterprise SaaS) may block external scripts via HTTP headers. Shadow DOM cannot override CSP. Fix: client adds your domain to their script-src whitelist (one line of config on their end). Typical SME clients (restaurants, shops, law firms) never have strict CSP.

2. z-index stacking context The widget container lives in the host page's regular DOM. If the host page applies transform, filter, or will-change on a parent element, it creates a stacking context that can render the widget behind page elements. Fix: offer an iframe fallback mode (total isolation) for clients who report this issue.

3. Mobile apps (Kotlin / Java / Swift) These load the widget via WebView (renders a URL). Whether the widget is Preact or React is completely invisible to native code — WebView just needs a URL. No special changes needed for mobile integration.

---

Admin Panel — React (Vite + shadcn/ui)

Why React (not Vue or Svelte)

The admin panel is a standalone SaaS web app (not embedded anywhere). Different constraints apply:

• Ecosystem: Complex admin UIs need data tables, file uploaders, date pickers, charts. React has the largest component ecosystem — everything is already built.
• shadcn/ui: Copy-paste component library built on Radix UI primitives + Tailwind. Components are owned (not npm dependencies), fully customizable. Best fit for a branded admin panel.
• Career value: Admin panel work is visible in a portfolio. React is the market standard for SaaS dashboards.
• Vue 3 has a gentler learning curve but a smaller ecosystem. Svelte has great performance but ~10x fewer enterprise components. Neither is worth the tradeoff for a complex admin surface.

Deployment

• Separate repo from the FastAPI backend
• Deployed independently (Netlify / Vercel)
• Connects to FastAPI via REST API (CORS configured per-tenant)
• Build: Vite

Onboarding flow

Monireach provisions a new client → gives them the admin panel URL + API key → owner registers and starts configuring → clicks "Publish" when ready → widget on their site goes live.

Scope (Step 10)

• System prompt / persona editor per tenant
• Knowledge base CRUD (upload, edit, delete documents)
• Theme/branding configurator (colors, fonts, widget position, bot name, logo, avatar)
• Go Live toggle: is_active flag — widget inactive until owner publishes; returns "not available" state to end users while inactive
• Test mode: owner chats with bot privately before publishing (mode: "test" | "live" flag — only owner sees it)
• Conversation history viewer
• Dashboard: message volume, response quality scores, feedback (thumbs up/down), top queries, RAG failure detection
• Validation mode toggle (async | sync) per tenant
• LLM provider config (per-tenant API key, provider selection)
• Auth: Google OAuth + 2FA (authenticator app) for SME admins
• Reference UX: ADA Support admin panel — streamlined for SMEs + Khmer market, not a 1:1 clone

Future scope (post Step 10)

• Handoff to live agent — escalation when chatbot can't answer; routes conversation to human agent in real time; requires presence/availability logic and notification (email, Telegram, etc.)
• Messaging platform integration — same chatbot on Telegram, WhatsApp, and other platforms; all RAG/prompt/KB logic identical, only I/O channel changes; one config drives both website widget and messaging apps simultaneously

---

Preact = React for Learning Purposes

Since Preact's API is identical to React:

• Building the widget in Preact teaches React syntax
• Building the admin panel in React reinforces the same patterns
• Both projects together = legitimate React/Preact experience to discuss in interviews

For AI Engineering interviews, depth on React internals is not expected. Ability to build a component-based UI and discuss state management patterns is sufficient.