HUB (User-facing) Integration Guide

This guide is for the HUB (member-facing) UI team. It explains how to wire the new evaluation features into a member’s flow — viewing their own results, exploring fit against a target role, and comparing with peers.

Backend service: evaluation (port 9103, gateway-proxied).
Auth: same Bearer JWT used elsewhere. The endpoints respect the caller’s persona.

1. Endpoints

The two endpoints are identical to what Admin uses. See Admin UI integration for full request/response payloads. HUB-relevant differences are:

Endpoint HUB use case
POST /evaluation/{id}/team-match “How well do I fit this role/team?” — the Match Me screen
POST /evaluation/compare “How compatible am I with my colleague / team-mate?”

2. Member-Facing Screens

Screen 1 — My Results → “Fit for this role”

After a member completes their evaluation:

  1. Show the existing workstyle 16-dimension overview (no change).
  2. Add a “Roles you might fit” section under it.
    • For each role the member can browse, call POST /evaluation/{id}/team-match { roleId }.
    • Display a horizontal card list: role title, combined score (large), category badge.
  3. Tap a card → role detail page.

Screen 2 — Role Detail

Per-role page:

  • Hero: role title + team name + combined score badge.
  • “Why we matched you” section — render the roleMatch.breakdown[]:
    • For industry/function/skill/studyMajor (set match): show percentageMatch as a progress bar with the candidate’s intersecting items highlighted.
    • For professionalYears/educationLevel (threshold): show ✓ Met / ✗ Not met based on percentageMatch === 1.
  • “Workstyle fit” section — the existing 16-dim chart, scoped to this team.
  • Adjust weighting is not surfaced to members in HUB — keep roleWeight at default 50.

Screen 3 — Compare with a Peer

Use case: “I want to see how I’d team up with X” (e.g. mentorship match, working group selection).

Flow:

  1. Member taps “Compare with…” on another member’s profile.
  2. Both members must have completed evaluations; if not, show a “They haven’t completed their evaluation yet” empty state.
  3. Default mode: MUTUAL (member-to-member is symmetric — that’s what users expect).
  4. Display:
    • Big mutual score + category badge.
    • “How you complement each other” — list dimensions where one side scores high and the other low.
    • “Where you align” — list dimensions where both scores are similar.
  5. Optionally surface a tabbed view to switch to PAIRWISE (“If you led a team of one, how would they fit?”) — but keep MUTUAL as the primary read.

3. UX Guidelines

  • Privacy: the breakdown reveals candidate experience/goal data. Only render it for the current member’s own role-fit view, never for a third-party member’s evaluation.
  • Scoring is not gospel: add a tooltip explaining “This is a guidance score based on your evaluation answers.” The category badge should be the primary visual; the numeric score is secondary.
  • Performance: keep team-match calls lazy — only compute when the section scrolls into view. Cache for the session (SWR/react-query) and invalidate after the member edits their experience or goals.

4. Score Categories — Member-friendly Copy

Category Range Copy
low < 33 “Limited overlap — different strengths”
medium 33–65 “Moderate fit”
high ≥ 66 “Strong match”

5. Error Handling

Same as Admin (see Admin UI integration). Specifically for HUB:

  • 404 on team-match → quietly hide the card; the role probably no longer exists.
  • 400 "no answers yet" on compare → “X hasn’t completed their evaluation”.
  • Network failures → silent retry on next mount; never block the rest of the screen.

6. Sample API Wiring (TypeScript / fetch)

type Mode = 'PAIRWISE' | 'SIMULATED_TEAM' | 'MUTUAL';

export async function getTeamMatch(evaluationId: string, opts?: { roleId?: number; roleWeight?: number }) {
  const res = await fetch(`${API_BASE}/evaluation/${evaluationId}/team-match`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
    body: JSON.stringify(opts ?? {}),
  });
  if (!res.ok) throw new Error(`team-match failed: ${res.status}`);
  return res.json();
}

export async function compareEvaluations(idA: string, idB: string, mode: Mode = 'MUTUAL') {
  const res = await fetch(`${API_BASE}/evaluation/compare`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
    body: JSON.stringify({ evaluationIdA: idA, evaluationIdB: idB, mode }),
  });
  if (!res.ok) throw new Error(`compare failed: ${res.status}`);
  return res.json();
}

7. Roll-out Checklist

  • Endpoints reachable from the HUB build’s API base.
  • Member’s persona is correctly bridged (user.id numeric present on the persona doc), otherwise role match returns null.
  • Loading skeletons + empty states ready.
  • i18n strings for category copy in all supported locales.
  • Analytics events on every team-match and compare invocation (so we can tune roleWeight defaults later).
next Introduction