Refactor to extensions (#426)

Signed-off-by: Trevor Grant <[email protected]>

Author: rawkintrevo

webapp/packages/webui/README.md

@@ -1,37 +1,49 @@
-# React + Vite
+# Gofannon Web UI
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+This package contains the front-end for the Gofannon web application. It uses Vite and React, and is designed to be the foundation for downstream distributions that may add their own extensions and configuration.
 
-Currently, two official plugins are available:
+## Card extension system
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+The home page tiles are implemented as **card extensions**. Each card implements a minimal interface (see `src/extensions/cards/types.js`) and is registered in a central registry (`src/extensions/cards/cardRegistry.js`). Built-in cards live in `src/extensions/cards/builtInCards.js` and are registered automatically, but additional cards can be added at runtime by calling `registerCard` or by supplying registrars through `window.__CARD_EXTENSION_REGISTRARS__`.
 
-## React Compiler
+### Configuration-driven ordering and visibility
 
-The React Compiler is enabled on this template. See [this documentation](https://react.dev/learn/react-compiler) for more information.
+Default card ordering and enablement are defined in `src/extensions/cards/config/defaultCardsConfig.js`. Configuration is merged in `src/extensions/cards/config/configLoader.js`, which layers the defaults with optional overrides from:
 
-Note: This will impact Vite dev & build performances.
+- `VITE_CARD_CONFIG_OVERRIDES` (JSON string)
+- `CARD_CONFIG_OVERRIDES` (JSON string when running in Node contexts)
+- `window.__CARD_CONFIG_OVERRIDES__` (object provided by the embedding page)
 
-## Configuring the Application
+Overrides can disable cards (`enabled: false`), change order (`order`), or add metadata such as `group`. New cards registered by extensions can supply their own defaults and be controlled by these overrides without modifying the OSS codebase.
 
-The application name and other settings can be configured through the shared configuration package (`@gofannon/config`).
+## How external distributions can extend the UI
 
-### Application Name
+External code can add cards and configuration without changing this repository by:
 
-To change the name displayed in the UI (e.g., "Gofannon WebApp"), add an `app.name` property to your configuration object. The UI will automatically use this name for the header and the browser tab title.
+1. Providing a registrar function (e.g., `window.__CARD_EXTENSION_REGISTRARS__ = [({ registerCard }) => registerCard({...})];`).
+2. Supplying configuration overrides through the supported environment variables or globals documented above.
+3. Building images or bundles that include additional extension modules and set the desired config at runtime.
+
+## Application configuration
+
+The shared configuration package (`@gofannon/config`) still provides environment-specific values such as API endpoints and theme settings. The card registry builds on top of this by keeping presentation cards configuration-driven and extension-aware.
 
-For example, in your configuration file:
-```json
-{
-  "app": {
-    "name": "My Custom AI Platform"
-  },
-  "...": "..."
-}
-```
 
+## Development
 
-## Expanding the ESLint configuration
+Install dependencies and start the development server from the `webapp` root:
+
+```bash
+pnpm install
+pnpm dev --filter webui
+```
+If you want to exercise the UI against the local API instead of mocks, run the FastAPI user-service in another terminal:
+```bash
+cd packages/api/user-service
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+```
 
-If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and [`typescript-eslint`](https://typescript-eslint.io) in your project.
+The API defaults to a local environment with permissive CORS. Adjust environment variables in a `.env` file in `packages/api/user-service` if you need to point at external services. Refer to the repository root README for broader project setup instructions.

webapp/packages/webui/src/extensions/cards/builtInCards.jsx

@@ -0,0 +1,78 @@
+import ChatIcon from '@mui/icons-material/Chat';
+import CodeIcon from '@mui/icons-material/Code';
+import SmartToyIcon from '@mui/icons-material/SmartToy';
+import ApiIcon from '@mui/icons-material/Api';
+import WebIcon from '@mui/icons-material/Web';
+
+export const builtInCards = [
+  {
+    id: 'chat',
+    title: 'Start Chatting',
+    description: 'Chat with AI models powered by LiteLLM',
+    buttonText: 'Open Chat',
+    icon: <ChatIcon />, 
+    iconColor: 'primary.main',
+    buttonColor: 'primary',
+    defaultOrder: 1,
+    onAction: ({ navigate }) => navigate('/chat'),
+  },
+  {
+    id: 'create-agent',
+    title: 'Create New Agent',
+    description: 'Define tools and behavior for a new AI agent',
+    buttonText: 'Start Agent Creation',
+    icon: <CodeIcon />, 
+    iconColor: 'secondary.main',
+    buttonColor: 'secondary',
+    defaultOrder: 2,
+    onAction: ({ navigate }) => navigate('/create-agent'),
+  },
+  {
+    id: 'saved-agents',
+    title: 'View Saved Agents',
+    description: 'Browse and manage your previously created agents',
+    buttonText: 'Browse Agents',
+    icon: <SmartToyIcon />, 
+    iconColor: 'success.main',
+    buttonColor: 'success',
+    defaultOrder: 3,
+    onAction: ({ navigate }) => navigate('/agents'),
+  },
+  {
+    id: 'deployed-apis',
+    title: 'View Deployed APIs',
+    description: 'Browse all agents deployed as REST endpoints.',
+    buttonText: 'Browse APIs',
+    icon: <ApiIcon />, 
+    iconColor: 'info.main',
+    buttonColor: 'info',
+    defaultOrder: 4,
+    onAction: ({ navigate }) => navigate('/deployed-apis'),
+  },
+  {
+    id: 'create-demo',
+    title: 'Create Demo App',
+    description: 'Build a web UI that uses your deployed agents.',
+    buttonText: 'Create Demo',
+    icon: <WebIcon />, 
+    iconColor: 'warning.main',
+    buttonColor: 'warning',
+    defaultOrder: 5,
+    onAction: ({ navigate }) => navigate('/create-demo'),
+  },
+  {
+    id: 'demo-apps',
+    title: 'View Demo Apps',
+    description: 'View and manage your saved demo applications.',
+    buttonText: 'View Demos',
+    icon: <WebIcon />, 
+    iconColor: 'secondary.light',
+    buttonColor: 'secondary',
+    defaultOrder: 6,
+    onAction: ({ navigate }) => navigate('/demo-apps'),
+  },
+];
+
+export const registerBuiltInCards = (registerCard) => builtInCards.forEach((card) => registerCard(card));
+
+export default registerBuiltInCards;

webapp/packages/webui/src/extensions/cards/cardRegistry.js

@@ -0,0 +1,101 @@
+import { registerBuiltInCards } from './builtInCards';
+import loadCardsConfig from './config/configLoader';
+
+const cardRegistry = new Map();
+const externalRegistrars = [];
+let initialized = false;
+let externalApplied = false;
+
+export const registerCard = (card) => {
+  if (!card || !card.id) {
+    throw new Error('Card registration requires a valid id');
+  }
+
+  if (cardRegistry.has(card.id)) {
+    console.warn(`Overwriting existing card registration for id: ${card.id}`);
+  }
+
+  const normalizedCard = {
+    buttonColor: 'primary',
+    iconColor: 'inherit',
+    ...card,
+  };
+
+  cardRegistry.set(card.id, normalizedCard);
+  return normalizedCard;
+};
+
+export const registerExternalCardRegistrar = (registrar) => {
+  if (typeof registrar === 'function') {
+    externalRegistrars.push(registrar);
+  }
+};
+
+const applyExternalRegistrars = () => {
+  if (externalApplied) return;
+
+  const windowRegistrars =
+    typeof window !== 'undefined' && Array.isArray(window.__CARD_EXTENSION_REGISTRARS__)
+      ? window.__CARD_EXTENSION_REGISTRARS__
+      : [];
+
+  [...windowRegistrars, ...externalRegistrars].forEach((registrar) => {
+    try {
+      registrar({ registerCard });
+    } catch (error) {
+      console.warn('Failed to apply card registrar', error);
+    }
+  });
+
+  externalApplied = true;
+};
+
+export const ensureCardRegistryInitialized = () => {
+  if (initialized) return;
+
+  registerBuiltInCards(registerCard);
+  applyExternalRegistrars();
+  initialized = true;
+};
+
+export const listCards = (cardConfig = loadCardsConfig()) => {
+  ensureCardRegistryInitialized();
+
+  const configMap = new Map(
+    (cardConfig.cards || []).map((card, index) => [card.id, { defaultOrder: index, ...card }]),
+  );
+
+  const cards = Array.from(cardRegistry.values())
+    .filter((card) => {
+      const settings = configMap.get(card.id);
+      if (settings && settings.enabled === false) {
+        return false;
+      }
+      return true;
+    })
+    .map((card) => {
+      const settings = configMap.get(card.id) || {};
+      return {
+        ...card,
+        group: settings.group || card.group,
+        order: settings.order ?? settings.defaultOrder ?? card.defaultOrder ?? Number.MAX_SAFE_INTEGER,
+      };
+    })
+    .sort((a, b) => {
+      const orderDiff = (a.order ?? 0) - (b.order ?? 0);
+      if (orderDiff !== 0) return orderDiff;
+      return a.title.localeCompare(b.title);
+    });
+
+  return cards;
+};
+
+export const getCardById = (cardId) => cardRegistry.get(cardId);
+
+export const clearCardRegistry = () => {
+  cardRegistry.clear();
+  initialized = false;
+  externalApplied = false;
+};
+
+export default cardRegistry;

webapp/packages/webui/src/extensions/cards/config/configLoader.js

@@ -0,0 +1,53 @@
+import defaultCardsConfig from './defaultCardsConfig';
+
+const normalizeCards = (config) => ({ cards: Array.isArray(config?.cards) ? config.cards : [] });
+
+export const mergeCardsConfig = (baseConfig, overrideConfig) => {
+  const base = normalizeCards(baseConfig);
+  const override = normalizeCards(overrideConfig);
+
+  const mergedMap = new Map(base.cards.map((card) => [card.id, { ...card }]));
+  override.cards.forEach((entry) => {
+    if (!entry?.id) return;
+    const current = mergedMap.get(entry.id) || {};
+    mergedMap.set(entry.id, { ...current, ...entry });
+  });
+
+  return { cards: Array.from(mergedMap.values()) };
+};
+
+export const parseCardsConfigOverride = (rawValue) => {
+  if (!rawValue) return { cards: [] };
+
+  try {
+    if (typeof rawValue === 'string') {
+      return JSON.parse(rawValue);
+    }
+
+    if (typeof rawValue === 'object') {
+      return rawValue;
+    }
+  } catch (error) {
+    console.warn('Unable to parse card configuration override. Falling back to defaults.', error);
+  }
+
+  return { cards: [] };
+};
+
+const resolveOverrideCandidates = () => {
+  const fromWindow = typeof window !== 'undefined' ? window.__CARD_CONFIG_OVERRIDES__ : undefined;
+  const envOverride = import.meta?.env?.VITE_CARD_CONFIG_OVERRIDES;
+  const nodeEnvOverride = typeof process !== 'undefined' ? process.env?.CARD_CONFIG_OVERRIDES : undefined;
+
+  return [envOverride, nodeEnvOverride, fromWindow].filter((value) => value !== undefined);
+};
+
+export const loadCardsConfig = () => {
+  const overrides = resolveOverrideCandidates()
+    .map(parseCardsConfigOverride)
+    .reduce((currentConfig, parsedOverride) => mergeCardsConfig(currentConfig, parsedOverride), { cards: [] });
+
+  return mergeCardsConfig(defaultCardsConfig, overrides);
+};
+
+export default loadCardsConfig;

webapp/packages/webui/src/extensions/cards/config/defaultCardsConfig.js

@@ -0,0 +1,12 @@
+const defaultCardsConfig = {
+  cards: [
+    { id: 'chat', order: 1, enabled: true },
+    { id: 'create-agent', order: 2, enabled: true },
+    { id: 'saved-agents', order: 3, enabled: true },
+    { id: 'deployed-apis', order: 4, enabled: true },
+    { id: 'create-demo', order: 5, enabled: true },
+    { id: 'demo-apps', order: 6, enabled: true },
+  ],
+};
+
+export default defaultCardsConfig;

webapp/packages/webui/src/extensions/cards/types.js

@@ -0,0 +1,20 @@
+/**
+ * @typedef {Object} CardActionContext
+ * @property {(path: string) => void} navigate - Function used by cards to change routes.
+ */
+
+/**
+ * @typedef {Object} CardExtension
+ * @property {string} id - Globally unique card identifier.
+ * @property {string} title - Display name shown to users.
+ * @property {string} description - Short description of the card purpose.
+ * @property {React.ReactElement} icon - Icon element rendered on the card.
+ * @property {string} buttonText - Text shown in the action button.
+ * @property {string} [buttonColor] - Optional button color (Material UI palette key).
+ * @property {string} [iconColor] - Optional icon color (Material UI palette key).
+ * @property {(context: CardActionContext) => void} onAction - Handler invoked when the user activates the card.
+ * @property {string} [group] - Optional grouping label to cluster cards.
+ * @property {number} [defaultOrder] - Default ordering hint for the registry.
+ */
+
+export {};