PROJECT_INVENTORY.md

Overview

This document maps the Alps codebase structure, key components, and recent architectural changes. Use this as context when reading specific files—do not read the whole tree.

Frontend Navigation & Shell Architecture

Migration Complete: Old SideBar → shadcn Sidebar-07

Status: ✅ Complete as of 2026-05-19

Old Pattern (DEPRECATED):

<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/components/SideBar.jsx</code> - Custom sidebar component (no longer used)
Imported in 19+ page files with hardcoded ml-[250px] margins
Status switching via localStorage and manual state updates

New Pattern (CANONICAL):

<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/components/sidebar/</code> - shadcn sidebar-07 block with full backend integration
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/layout.js</code> - Wraps {children} with <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em"><ShellGate /></code> for route-based mounting
Composable architecture: AppShell → AppSidebar → {TeamSwitcher, NavMain, NavUser}
Real-time status, workspaces, notifications via Pusher + backend APIs

New Sidebar Components

| File | Purpose | Key Props/State | |---|---|---| | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/components/sidebar/app-shell.tsx</code> | Root shell + backend wiring | Fetches user, workspaces, notifications; handles status/workspace updates | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/components/sidebar/shell-gate.tsx</code> | Route-based conditional renderer | Allows: /inbox, /articles, /collections, /calls, /guides, /tickets, /reports, /workflows, /forms, /campaigns, /settings, /profile, /automation, /scribeReplica | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/components/sidebar/app-sidebar.tsx</code> | Main sidebar orchestrator | Composes TeamSwitcher, NavMain, NavUser | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/components/sidebar/team-switcher.tsx</code> | Workspace dropdown | teams[], activeIndex, onSelect, onAddTeam callbacks | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/components/sidebar/nav-main.tsx</code> | Page navigation tree | Uses next/link, usePathname() for active state; auto-opens collapsibles | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/components/sidebar/nav-user.tsx</code> | User dropdown + status switcher | 4-state radio group (online/away/busy/offline), notification badge, Account link |

Sidebar UI Primitives (Sandboxed)

All shadcn UI components live under <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/components/sidebar/ui/</code> to avoid conflicts with legacy <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/components/ui/*.jsx</code>:

<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">sidebar.tsx</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">sheet.tsx</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">dropdown-menu.tsx</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">tooltip.tsx</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">collapsible.tsx</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">avatar.tsx</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">breadcrumb.tsx</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">skeleton.tsx</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">button.tsx</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">input.tsx</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">separator.tsx</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">card.tsx</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">tabs.tsx</code>

Why sandboxed: The codebase has legacy custom UI components (Button.jsx, etc.) in <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">asset/components/ui/</code>. The new shadcn primitives needed their own namespace to avoid file collision and ensure both systems can coexist during migration.

Backend Integration (AppShell)

API calls made on mount:

          javascript
          
        

getUserData()           // User profile
getUserWorkspaces()     // Available workspaces
getNotificationUnreadCount()  // Initial unread count

Real-time updates:

Pusher subscription to <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">private-workspace-{workspaceId}-notifications</code> channel
Increments/decrements notificationCount on <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">notification.new</code> / <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">notification.read</code> events

Status mapping (bidirectional):

          javascript
          
        

// UI model: online, away, busy, offline
// Backend model: available, away, busy, out_of_office

STATUS_TO_BACKEND = {
  online: 'available',
  away: 'away',
  busy: 'busy',
  offline: 'out_of_office',
}

BACKEND_TO_STATUS = {
  available: 'online',
  away: 'away',
  busy: 'busy',
  out_of_office: 'offline',
}

Callbacks:

<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">switchWorkspace(workspaceId)</code> → updates localStorage, fires <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">alps:workspace-switched</code> event, reloads page
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">updateAgentStatus(status)</code> → calls backend, updates local state, Pusher broadcasts to team

Pages Updated (SideBar Removed)

All instances of <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">import SideBar from '@asset/components/SideBar'</code> and <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em"><SideBar /></code> removed from:

<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/articles/page.jsx</code>
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/collections/page.jsx</code>
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/forms/page.jsx</code>
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/guides/page.jsx</code>
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/campaigns/page.jsx</code> (also removed ml-[250px] margin wrapper)
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/workflows/page.jsx</code> (also removed ml-[250px] margin wrapper)
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/reports/page.jsx</code> (also removed ml-[250px] margin wrapper)
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/reports/help-center-analytics/page.jsx</code>
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/reports/performance-metrics/page.jsx</code>
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/reports/team-performance/page.jsx</code>
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/ContactsPages/ContactsView.jsx</code>
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/TicketsPages/Tickets.jsx</code> (layout changed from ml-[250px] to full-width)
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/TicketsPages/EachTicket.jsx</code> (removed from 3 return statements)
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/ContactsPages/ContactDetail.jsx</code> (removed from 3 return statements)
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/CallsPages/Calls.jsx</code>
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/CallsPages/CallDetail.jsx</code> (removed from 2 return statements)
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/InboxPages/InboxContent.jsx</code> (removed ml-[250px] dynamic spacing)
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/SettingsPages/SettingsShell.jsx</code> (removed sidebarCollapsed state and callback)
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/components/Profile.jsx</code> (removed ml-[250px] margin)

Path Aliases

Both <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/tsconfig.json</code> and <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/jsconfig.json</code> now define:

          json
          
        

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

This enables shadcn CLI to generate components under <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">@/components/sidebar/</code> correctly.

Backend

Express API

| Thing | Detail | |---|---| | Entry point | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/server.js</code> | | Port | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">process.env.PORT</code> (default 3030) | | Start (prod) | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">npm start</code> → <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">node server.js</code> | | Start (dev) | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">npm run dev</code> → <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">nodemon server.js</code> | | Config | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/config/</code> + <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">.env</code> | | Routes | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/routes/</code> - all mounted at <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">/api/v1/</code> | | Controllers | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/controllers/</code> | | Models | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/models/</code> - 17 Mongoose models (migrating to Firestore) | | Services | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">workflowEngine.js</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">imapService.js</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">emailService.js</code> | | Real-time | Socket.io (server.js) + Pusher (via frontend) | | Workers | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">worker.js</code> (Heroku one-off), <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">clock.js</code> (scheduler), <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">scheduler.js</code> (cron) | | Hosting | Heroku → migrating to Google Cloud Run | | Database | MongoDB Atlas → Firebase Firestore | | Auth | Firebase Authentication (migrating from custom JWT) |

Key env vars:

          plaintext
          
        

DB_CONNECTION              MongoDB URI (being replaced)
FIREBASE_PROJECT_ID        Firebase project ID
FIREBASE_SERVICE_ACCOUNT   Firebase Admin SDK service account JSON
JWT_SECRET / JWT_EXPIRES   (legacy, remove after auth migration)
GOOGLE_AUTH_CLIENT_ID/SECRET  (legacy, replaced by Firebase Auth)
ZEPTO_BASE_URL / ZEPTO_API_KEY  ZeptoMail email delivery
PAYSTACK_SECRET_KEY        Paystack payments
CLOUDINARY_*               File uploads
WA_PHONE_NUMBER_ID / WA_ACCESS_TOKEN  WhatsApp Cloud API
VERCEL_API / VERCEL_KEY    Custom domain provisioning
CRON_SECRET                Optional secret header for internal cron endpoints
PUSHER_APP_ID / KEY / SECRET / CLUSTER  Real-time notifications

Key Backend Files

| File | Purpose | |---|---| | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/controllers/messageController.js</code> | Conversation inbox, send message, assign, priority, status, WhatsApp webhook | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/controllers/inbox.controller.js</code> | Inbox CRUD, channel add/remove (email → imapService), workspace settings | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/controllers/auth.controller.js</code> | Firebase Auth token verification, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">protect</code> middleware | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/controllers/contact.controller.js</code> | Contact CRUD | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/routes/message.route.js</code> | Routes: /customer (public), /send, /inbox, /conversations/:id/assign\|close\|status\|labels\|priority | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/services/imapService.js</code> | Singleton IMAP polling; <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">initializeAllActive()</code> on server start | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/services/emailService.js</code> | SMTP send via nodemailer | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/utils/firestore.js</code> | Firestore <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">db</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">getDoc</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">setDoc</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">serverTimestamp</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">arrayUnion</code>, <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">arrayRemove</code> |

Firebase Firestore Collections

| Collection | Replaces | Notes | |---|---|---| | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">users</code> | User | doc ID = Firebase Auth UID | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">workspaces</code> | Workspace | | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">profiles</code> | Profile | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">domain</code> field drives *.tryalps.app | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">articles</code> | Article | | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">categories</code> | Category | | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">conversations</code> | Conversation | fields: workspaceId, inboxId, status, priority, assignedToId, labels[], customer{name,email}, lastMessageAt | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">messages</code> | Message | fields: conversationId, direction, senderType, isNote, content, read, createdAt (flat, not subcollection) | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">contacts</code> | Contact | linked to conversations | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">workflows</code> | Workflow | nodes array embedded | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">imapConfigs</code> | ImapConfig | per-workspace IMAP settings | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">inboxLabels</code> | InboxLabel | | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">playlists</code> | Playlist | | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">guides</code> | Guide | | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">supportTickets</code> | SupportTicket | | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">supportRequests</code> | SupportRequest | | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">invoices</code> | Invoice | | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">transactions</code> | Transaction | | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">emptySearches</code> | EmptySearches | |

Frontend Pages & Components

Key Frontend Files

| File | Purpose | |---|---| | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/InboxPages/DefaultView.jsx</code> | Conversation list + ChatBox layout; Pusher workspace channel | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/InboxPages/ChatBox.jsx</code> | Message thread, send reply, notes, Pusher conversation channel | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/InboxPages/UserDetails.jsx</code> | Right sidebar: contact info, priority, assign, recent convs, labels | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/InboxPages/InboxContent.jsx</code> | Wraps DefaultView, passes userData | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/services/request.js</code> | All Axios API calls - auth token from localStorage.getItem('alpsToken') | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/api/widget/widgetScript.js</code> | Full widget JS (~1992 lines) | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/api/widget/widget-content.js</code> | Widget HTML content helper | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">test-widget.html</code> | Dev test page |

Conversation Data Shape

          javascript
          
        

{
  id, workspaceId, inboxId, status, priority, assignedToId,
  labels: [],              // tags
  customer: { name, email },
  lastMessageAt,
  messages: [...],         // full array, sorted by createdAt asc
  lastMessage: { id, content, senderType, isNote, direction, read, createdAt },
  assignedTo: { id, firstName, lastName },
  unreadCount, messageCount
}

Widget Identity Model

<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-user-id</code> on script tag = widget key (inbox/channel key)
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-user-name</code> / <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">data-user-email</code> = visitor identity if host app provides it
localStorage <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">alps-visitor-{widgetKey}</code> = stored visitor identity for anonymous visitors
Pre-chat form shown when neither script attrs nor localStorage has name+email

Configuration

Subdomain Routing (*.tryalps.app)

Wildcard DNS (<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">*.tryalps.app</code>) → Vercel
Each user's <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">Profile.domain</code> = their slug
Backend CORS allows any <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">*.tryalps.app</code> origin
No subdomain routing in Next.js middleware; backend resolves identity from <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">Organization</code> header or profile slug lookup in Firestore

Firestore Indexes

<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">getInbox</code> fetches without <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">orderBy</code> (avoids composite index) and sorts in memory. When ready to deploy proper indexes: <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">firebase deploy --only firestore:indexes</code> using <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">firestore.indexes.json</code>.

Firebase Migration Status

Phase Progress:

[x] Phase 1: Firebase project setup
[x] Phase 2: Auth migration (JWT → Firebase Auth)
[x] Phase 3: Database migration (Mongoose → Firestore)
[x] Phase 4: Frontend auth update
[x] Phase 5: Server hosting (Heroku → Cloud Run)
[ ] Phase 6: Decommission MongoDB Atlas + Heroku

See <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/FIREBASESETUP.md</code> and <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/CLOUDRUN_SETUP.md</code> for details.

knowledge-base/ App (Public Help Center)

Purpose: Public-facing help center at <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">{slug}.tryalps.app</code> — no auth required, all data from Alps API.

Stack

Next.js 16 (App Router, TypeScript, Turbopack)
Tailwind CSS + @tailwindcss/typography
No Shadcn (standalone app with custom CSS vars)

Three Themes (profile.themeType)

| Theme | Style | Key files | |---|---|---| | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">nexus</code> | Developer docs (Next.js docs style) — left sidebar nav | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">components/themes/nexus/</code> | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">clarity</code> | Help center (Notion/Intercom style) — sticky nav, full-width | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">components/themes/clarity/</code> | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">prism</code> | Modern bold (Linear/Vercel style) — dark header, numbered sections | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">components/themes/prism/</code> |

API (all public, no auth)

| Endpoint | Purpose | |---|---| | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">GET /user/get-profile/:slug</code> | Workspace profile (colours, fonts, header, hero, footer, social) | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">GET /user/widget-data/:widgetKey</code> | Published categories + articles | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">PATCH /article/:id/views</code> | Track view (fire-and-forget) | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">PATCH /article/:id/upvote</code> | Upvote article | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">PATCH /article/:id/downvote</code> | Downvote article |

Key files

| File | Purpose | |---|---| | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">proxy.ts</code> | Subdomain middleware: extracts slug from host, sets <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">x-workspace-slug</code> header | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">app/layout.tsx</code> | Root layout: fetches profile, injects CSS vars, Google Fonts, favicon, GA4 | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">app/page.tsx</code> | Home: routes to NexusHome / ClarityHome / PrismHome by themeType | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">app/[categorySlug]/page.tsx</code> | Category detail page | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">app/[categorySlug]/[articleSlug]/page.tsx</code> | Article page (tracks view) | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">app/search/page.tsx</code> | Search results (client-side filter) | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">lib/api.ts</code> | fetch wrappers for all 5 endpoints | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">lib/types.ts</code> | Profile, Category, Article types | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">components/shared/ArticleVoting.tsx</code> | Client-side upvote/downvote widget | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">components/shared/SearchBar.tsx</code> | Client-side inline search with dropdown results | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">components/shared/SearchPage.tsx</code> | Full search page with URL sync |

Dev

          bash
          
        

cd knowledge-base
cp .env.example .env.local   # set NEXT_PUBLIC_DEV_SLUG
npm run dev                  # localhost:3001

AI Integration (New - May 2026)

Status: ✅ Phase 1 complete — Local Ollama + Chroma setup, AI routing in workflow engine

Infrastructure

Ollama (local LLM inference): <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">http://localhost:11434</code>
Chroma (vector database): <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">http://localhost:8000</code>
Models:

- <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">nomic-embed-text</code> (embeddings, 275MB, ~100ms per request) - <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">llama3.2:3b</code> (text generation, for future features) - <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">mistral:7b</code> (optional, better quality)

Backend Files

| File | Purpose | Status | |---|---|---| | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">services/aiService.js</code> | Ollama + Chroma client wrapper | ✅ Complete | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">controllers/ai.controller.js</code> | AI endpoints (embed, classify, route) | ✅ Complete | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">routes/ai.route.js</code> | POST /api/v1/ai/* routes | ✅ Complete | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">services/workflowEngine.js</code> | Added <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">ai_route</code> node type | ✅ Complete | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">scripts/embedConversations.js</code> | Batch export + embed conversations | ✅ Complete | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">docker-compose.yml</code> | Ollama + Chroma containers | ✅ Complete | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">AI_SETUP.md</code> | Installation & setup guide | ✅ Complete | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">AI_QUICKSTART.md</code> | 5-minute getting started | ✅ Complete | | <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">AI_TESTING.md</code> | Testing & iteration guide | ✅ Complete |

Key Features (Live)

Intelligent Inbox Routing via embedding-based similarity

- Workflow node: <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">ai_route</code> - Embed incoming message → find 3 most similar historical conversations → route to same inbox - Fallback: continues to next workflow node if no matches

AI Service Health Check: <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">GET /api/v1/ai/health</code>

Embedding Status: <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">GET /api/v1/ai/embedding-status</code> (shows % of conversations embedded)

Usage

Enable in workflow:

Create workflow node of type <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">ai_route</code>
Node automatically routes based on conversation content

Batch embed conversations (data prep):

          bash
          
        

node scripts/embedConversations.js [workspaceId]

Monitor: Activity log shows routing confidence (e.g., "routed to inbox_billing (87.3% confidence)")

AI Settings & Configuration (NEW)

Purpose

Full UI for configuring AI agent personality, training data, data access permissions, and auto-escalation rules.

New Files Created

Frontend:

<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/app/settings/alps-ai/page.jsx</code> — Route entry point
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/SettingsPages/AiAgentPage/index.jsx</code> — Main tabs component (owns data load/save + tab state)
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/SettingsPages/AiAgentPage/TrainTab.jsx</code> — Q&A, documents, websites, KB toggle
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/SettingsPages/AiAgentPage/AgentTab.jsx</code> — Avatar upload, name, persona, business description
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/SettingsPages/AiAgentPage/AccessTab.jsx</code> — Data permission toggles (conversations, contacts, location)
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/SettingsPages/AiAgentPage/EscalationTab.jsx</code> — Auto-escalation toggles + inbox selector
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/SettingsPages/AiAgentPage/components/ToggleRow.jsx</code> — Reusable toggle + label + description row
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/SettingsPages/AiAgentPage/components/QnaPanel.jsx</code> — Q&A table + inline add form
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/SettingsPages/AiAgentPage/components/DocumentsPanel.jsx</code> — File upload (.pdf/.docx/.txt) + status list
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/SettingsPages/AiAgentPage/components/WebsitesPanel.jsx</code> — URL input + crawl status list

Backend:

<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/controllers/ai.controller.js</code> — 9 new handlers: getAiSettings, updateAiSettings, addQna, deleteQna, uploadDocument, deleteDocument, addWebsite, deleteWebsite, uploadAgentAvatar
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">backend/routes/ai.route.js</code> — 9 new routes mounted under <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">/api/v1/ai/settings/*</code>

API Helpers (added to <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">frontend/asset/services/request.js</code>):

<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">getAiSettings()</code> — Load full AI configuration
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">updateAiSettings(body)</code> — Save agent/access/escalation settings
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">addAiQna(qna)</code> / <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">deleteAiQna(id)</code> — Q&A CRUD
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">uploadAiDocument(file)</code> / <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">deleteAiDocument(id)</code> — Document upload + delete
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">addAiWebsite(url)</code> / <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">deleteAiWebsite(id)</code> — Website URL CRUD
<code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">uploadAgentAvatar(file)</code> — Avatar upload

Data Storage (Firestore)

Location: <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">workspace.aiSettings</code> nested field + <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">workspaces/{id}/aitrainingitems</code> subcollection

          javascript
          
        

// workspace.aiSettings
{
  agent: { name, persona, businessDescription, profilePictureUrl },
  train: { knowledgeBaseEnabled },
  access: { conversationHistory, contacts, userLocation, deviceLocation },
  escalation: { onNoAnswer, onFrustration, onHumanRequest, escalateToInboxId },
}

// workspaces/{id}/ai_training_items (type: 'qna'|'document'|'website')
{
  type, question?, answer?, name?, url?, status, createdAt
}

Why subcollection: Training data (Q&A pairs, document metadata, website URLs) stored separately to avoid 1MB Firestore document size limit.

UI Integration

SettingsShell updates:

Added "Alps AI" menu group between "Support Configurations" and "Help Center"
New menu entry with Bot icon → navigates to <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em">/settings/alps-ai</code>
New switch case rendering <code style="font-family:ui-monospace,monospace;background:#f1f5f9;color:#dc2626;padding:0.1em 0.35em;border-radius:3px;font-size:0.875em"><AiAgentPage /></code>

Next Steps (Roadmap)

[ ] Sentiment analysis (auto-priority on angry customers)
[ ] Suggested replies (AI copilot for agents)
[ ] Conversation summarization (TL;DR button)
[ ] Knowledge base RAG (AI bot answers from KB)
[ ] Fine-tuning on real routing data (Tier 3, ~$5 via LoRA)
[ ] Production deployment (Oracle Cloud Always Free or Hetzner ~€10/mo)

Dependencies Added

          json
          
        

"chromadb": "^1.5.12"

Environment Variables

env

OLLAMA_BASE_URL=http://localhost:11434
CHROMA_URL=http://localhost:8000

Last Updated

2026-05-27: AI integration Phase 1 — Ollama + Chroma local setup, semantic inbox routing, 15 planned use cases.
2026-05-26: knowledge-base/ public help center app created (Next.js 16, 3 themes, no auth).
2026-05-19: Sidebar migration complete - old SideBar removed from 19 files, new shadcn shell (AppShell → ShellGate) in place with full backend integration (workspaces, status switching, notifications via Pusher).