Skip to content
TEEI Knowledge Hub

WBP Portal Integration

WBP Portal Integration

The Women Buddy Program (WBP) Portal is an Astro 5 + Turso application serving two audiences: buddies (volunteer mentors) and participants (programme participants). Both use the same role: volunteer.

Prerequisites

  • @teei/chat-widget installed (see Integration Guide)
  • @astrojs/react configured in wbp-portal/astro.config.mjs
  • RAG Worker running at https://knowledge-api.theeducationalequalityinstitute.org
  • WBP Portal running locally on port 4424

Layout structure

The WBP Portal has two primary layout contexts:

LayoutPathAudience
Buddy layoutwbp-portal/src/layouts/BuddyLayout.astroVolunteer buddies
Participant layoutwbp-portal/src/layouts/ParticipantLayout.astroProgramme participants

Both layouts use the same userRole="volunteer" — they differ only in the content they can access on their respective dashboards, not in knowledge permissions.

If a unified layout (e.g., PortalLayout.astro) wraps both, add the widget there once.

Step-by-step installation

Step 1: Identify the layout files in use:

Terminal window
find wbp-portal/src/layouts -name "*.astro" | sort

Step 2: Open the buddy layout (BuddyLayout.astro). Add the import at the top of the frontmatter:

---
// Existing imports
import { getVolunteerSession } from '../lib/auth';


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


const session = await getVolunteerSession(Astro);
---

Step 3: Add the widget before </body>:

  <!-- TEEI Knowledge Assistant — Buddy -->
  <ChatProvider
    client:idle
    apiUrl="https://knowledge-api.theeducationalequalityinstitute.org"
    platform="wbp"
    userRole="volunteer"
    language="en"
  >
    <ChatWidget
      greeting="Hi! I can help you with buddy matching, session guides, programme tracks, and anything else about the WBP Portal. What do you need?"
    />
  </ChatProvider>


</body>

Step 4: Repeat for the participant layout (ParticipantLayout.astro):

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


  <!-- TEEI Knowledge Assistant — Participant -->
  <ChatProvider
    client:idle
    apiUrl="https://knowledge-api.theeducationalequalityinstitute.org"
    platform="wbp"
    userRole="volunteer"
    language="en"
  >
    <ChatWidget
      greeting="Hi! I can help you navigate the programme, find your buddy, and understand what to expect next. What would you like to know?"
    />
  </ChatProvider>

Step 5: Verify the build:

Terminal window
cd teei-astro/wbp-portal
npm run typecheck
npm run build

Step 6: Verify the widget renders:

Terminal window
curl -I http://localhost:4424/
curl -I http://localhost:4424/buddy/login

Open http://localhost:4424/ and log in. The chat FAB should appear in the bottom-right corner on authenticated pages.

Exclude the login page

Do not show the widget on the login page — unauthenticated users landing on the login page should not see the widget (it creates visual noise and the session context is unavailable).

In the buddy layout:

---
const path = Astro.url.pathname;
const isLoginPage = path === '/buddy/login' || path === '/login';
---


{!isLoginPage && (
  <ChatProvider
    client:idle
    apiUrl="https://knowledge-api.theeducationalequalityinstitute.org"
    platform="wbp"
    userRole="volunteer"
    language="en"
  >
    <ChatWidget />
  </ChatProvider>
)}

Multilingual considerations

WBP participants may prefer Ukrainian or Norwegian. If the portal stores a preferred language in the session, pass it to the widget:

---
const session = await getVolunteerSession(Astro);
const lang = session?.preferredLanguage ?? 'en'; // 'en' | 'uk' | 'no'
---


<ChatProvider
  client:idle
  apiUrl="https://knowledge-api.theeducationalequalityinstitute.org"
  platform="wbp"
  userRole="volunteer"
  language={lang}
>
  <ChatWidget />
</ChatProvider>

The RAG Worker’s embedding model (bge-m3) supports Ukrainian natively. Answers will be generated in the language of the query when Ukrainian content is available in the vector index.

Widget positioning

The WBP Portal uses a bottom navigation bar on mobile. To avoid the chat FAB overlapping the bottom nav, use position="bottom-right" (default) and add bottom padding to the FAB via CSS override:

/* In wbp-portal/src/styles/global.css */
@media (max-width: 767px) {
  .teei-chat-widget .teei-chat-fab {
    bottom: 72px; /* Above the bottom nav bar */
  }
  .teei-chat-widget .teei-chat-panel {
    bottom: 72px; /* Panel floats above nav too */
  }
}

Verification checklist

  • npm run typecheck exits 0
  • npm run build exits 0
  • curl -I http://localhost:4424/ returns 200
  • curl -I http://localhost:4424/buddy/login returns 200
  • Chat FAB visible on authenticated dashboard at 1440px
  • Chat FAB NOT visible on the login page
  • Chat FAB visible at 375px mobile (above bottom nav if present)
  • Panel opens and accepts a question
  • Streamed response received without console errors

Gotchas

Session cookie domain: The WBP Portal runs on wbp.theeducationalequalityinstitute.org. The RAG Worker must allow this origin in ALLOWED_ORIGINS. It is already included in the default configuration.

Turso connection in middleware: The WBP Portal queries Turso for session validation. The chat widget makes separate requests to the RAG Worker (Cloudflare D1). These are independent — do not confuse them.

Bottom nav overlap on mobile: WBP Portal uses a bottom navigation pattern. The widget FAB sits at bottom: 24px by default. If this overlaps the bottom nav, apply the CSS override shown above.