Admin Dashboard Integration

The Admin Dashboard is an internal tool used by TEEI staff for programme administration, user management, and compliance operations. It uses Astro 5 + React + Tailwind CSS, with its own RBAC system separate from CSR Cockpit.

Prerequisites

@teei/chat-widget installed (see Integration Guide)
@astrojs/react configured in admin/astro.config.mjs (it is — React is used for AnnotationOverlay and other islands)
RAG Worker running at https://knowledge-api.theeducationalequalityinstitute.org
Admin Dashboard running locally on port 4426

Layout file

All Admin Dashboard pages use admin/src/layouts/AdminLayout.astro. Add the widget there for global coverage.

Admin RBAC to knowledge role mapping

The Admin Dashboard has its own role system. Map these to the knowledge widget’s role hierarchy:

const ADMIN_ROLE_MAP: Record<string, string> = {
  viewer:          'staff',   // Read-only staff access
  cert_issuer:     'staff',   // Can issue certificates — staff content
  buddy_admin:     'staff',   // Manages buddy matching — staff content
  skills_admin:    'staff',   // Manages skills academy — staff content
  education_admin: 'staff',   // Manages education programmes — staff content
  content_editor:  'admin',   // Can edit platform content — admin content
  super_admin:     'admin',   // Full access
};

This maps to the knowledge role hierarchy:

staff — sees public + volunteer + employee + staff content
admin — sees everything including admin-only knowledge

Step-by-step installation

Step 1: Open admin/src/layouts/AdminLayout.astro.

Step 2: Add imports at the top of the frontmatter, alongside the existing AnnotationOverlay import:

---
// Existing imports
import { AnnotationOverlay } from '../components/annotations/AnnotationOverlay';
import { getAdminSession } from '../lib/admin/auth';

// Add:
import { ChatProvider, ChatWidget } from '@teei/chat-widget';
import '@teei/chat-widget/styles';

const runtimeEnv = Astro.locals.runtime?.env;
const session = await getAdminSession(Astro, runtimeEnv);
---

Step 3: Add the role mapping in the frontmatter, after the session is resolved:

---
// After session resolution...

const ADMIN_ROLE_MAP: Record<string, string> = {
  viewer:          'staff',
  cert_issuer:     'staff',
  buddy_admin:     'staff',
  skills_admin:    'staff',
  education_admin: 'staff',
  content_editor:  'admin',
  super_admin:     'admin',
};

// session.role is the admin RBAC role
const knowledgeRole = session
  ? (ADMIN_ROLE_MAP[session.role] ?? 'staff')
  : 'public'; // Unauthenticated users (login page) fall through to public
---

Step 4: Add the widget before </body>, after the existing AnnotationOverlay:

  <!-- Existing: Annotation overlay (dev-only) -->
  <AnnotationOverlay client:load transition:persist />

  <!-- TEEI Knowledge Assistant -->
  {session && (
    <ChatProvider
      client:idle
      apiUrl="https://knowledge-api.theeducationalequalityinstitute.org"
      platform="admin"
      userRole={knowledgeRole}
      language="en"
    >
      <ChatWidget
        greeting="Hi! I can help with programme admin, user management, reporting, and compliance procedures. What do you need?"
      />
    </ChatProvider>
  )}

</body>

Note the {session && ...} guard — the widget only renders when a session exists. This excludes the login page automatically.

Step 5: Verify the build:

cd teei-astro/admin
npm run typecheck
npm run build

Step 6: Verify the widget renders:

curl -I http://localhost:4426/
curl -I http://localhost:4426/

By default, the {session && ...} guard prevents the widget from appearing on the login page. If you explicitly want it on the login page (e.g., “Help, I can’t log in”), remove the session guard and use userRole="public":

<ChatProvider
  client:idle
  apiUrl="https://knowledge-api.theeducationalequalityinstitute.org"
  platform="admin"
  userRole={session ? knowledgeRole : 'public'}
  language="en"
>
  <ChatWidget />
</ChatProvider>

Admin-specific knowledge content

Admin staff ask different questions than managers or employees. Content tagged for the admin platform in Vectorize is sourced from:

docs/src/content/docs/en/admin-guide/ — programme administration procedures
docs/src/content/docs/en/platforms/admin/ — admin dashboard usage guides

Ensure these directories have content ingested before deploying the widget to Admin. Run the ingestion scripts:

cd teei-knowledge
node scripts/ingest.mjs --platform admin --dir docs/src/content/docs/en/admin-guide

Verification checklist

npm run typecheck exits 0
npm run build exits 0
curl -I http://localhost:4426/ returns 200
Chat FAB visible on the main dashboard at 1440px
Chat FAB NOT visible on the login page (session guard is working)
Role mapping: super_admin session → admin role in widget context
Role mapping: viewer session → staff role in widget context
Panel opens and returns relevant admin-focused answers
No console errors in browser DevTools

Gotchas

lucide-react icons, not Phosphor: The Admin Dashboard uses lucide-react for icons. The chat widget ships its own inline SVG icons — they do not depend on either icon library. No icon configuration is needed.

Tailwind CSS global styles: The Admin Dashboard loads Tailwind’s tailwind.css globally. The chat widget CSS is scoped to .teei-chat-widget — Tailwind’s preflight reset does not conflict with it. If you notice unexpected styling in the widget panel (fonts, borders), check that Tailwind’s base styles are not leaking through. The fix is to add all: initial to .teei-chat-widget in your override CSS.

noindex,nofollow pages: The Admin Dashboard sets noindex,nofollow on all pages (see AdminLayout.astro). This is correct for an internal tool. The chat widget does not affect SEO.

AnnotationOverlay z-index: The annotation overlay uses z-index 9994. The chat widget uses z-index 9999. They do not conflict. The annotation FAB sits at bottom: 24px, right: 24px — the same position as the chat widget. Adjust the annotation FAB position or the chat widget position to prevent overlap:

/* In admin/src/styles/admin.css */
/* Move annotation FAB up to make room for chat widget */
.ann-fab {
  bottom: 88px; /* 56px (chat FAB height) + 8px gap + 24px original offset */
}

Admin Dashboard Integration

Admin Dashboard Integration

Prerequisites

Layout file

Admin RBAC to knowledge role mapping

Step-by-step installation

Widget on the login page

Admin-specific knowledge content

Verification checklist

Gotchas