Skip to main content

​
Partner Portal docs — open questions and UI flags

Raised while writing the operator-facing Partner Portal guides (docs/operators/partners/*). Everything below was observed in the running app against seeded partner data, not inferred from code alone unless noted. Nothing here blocks publishing the guides. Items marked Blocking are places where the published docs state something the product team should confirm, or where the guides deliberately stay vague because the intended behavior is unclear.

​
Naming and audience

​
1. “Partner Portal” is three different products — Blocking

The phrase currently maps to three unrelated things: The new guides use Partner Portal for the live /partners module, because that is what the docs request asked for, and they carry an explicit “two things both called partners” note. Confirm this is the name we want in the knowledge base, or give the module a distinct public name before the guides go out to customers.

​
2. Partners have no login, so several requested articles do not apply — Blocking

The docs request asked for partner account creation, login, and logout walkthroughs. None exist for this surface:
  • There is no Partner Portal login. Operators arrive through the CRM marketplace session; signing out means signing out of the CRM.
  • Referral partners never open /partners. They receive links and emailed reports only.
  • Partner records are created in the CRM (or by a CRM workflow after a sign-up form submission), never in Funding Machine.
The guides document this as the actual behavior. If a partner-facing login is planned, the audience framing in overview.mdx will need rewriting.

​
Copy and UI issues worth fixing

​
3. Operator-facing copy names an internal env var, and says “GHL”

The Launch readiness panel renders, to operators:
Scheduled sync is off (GHL_AFFILIATE_SYNC_ENABLED). Manual Refresh still works; the hourly cron no-ops.
Two problems. It exposes a deployment variable name and the word “cron” to customers, and VISION.md locks user-facing copy to “CRM” rather than GHL. Suggested operator wording: “Automatic hourly sync is off for this account. Refresh from CRM still works.” The variable name belongs in an admin-only detail, if anywhere. Source: convex/prospecting/affiliateReadiness.ts. This is the one item the guides route around: troubleshooting.mdx tells operators to read the readiness panel but does not quote this line.

​
4. Admin-only controls are invisible rather than disabled

A non-admin operator sees no Settings tab, no Send report button, no Partner reporting defaults card, and no edit control on the referral link — with nothing on screen saying those exist or who can reach them. Anyone following a screenshot-led guide will conclude the docs are wrong. The guides label every admin-only feature. A short in-product line (“Reporting and enrollment are managed by account admins”) would close the gap.

​
5. “Enroll in campaign” is one label for two different actions

  • Overview empty state → the button switches to the Settings tab.
  • Settings tab card → the button performs the enrollment.
Suggest renaming the first to “Set up enrollment” or “Go to enrollment”.

​
6. Enrollment setup status badges are internal vocabulary

Step statuses read Selected, Observed in CRM data, and Manual CRM step. The distinction is real and worth keeping, but “Observed in CRM data” is engineering phrasing. Something like “Confirmed in your CRM” and “Do this in your CRM” would land better. The explanatory footnote is currently doing work the badges should do themselves.

​
7. The same measure has two names

The directory stat card is Applicants & clients (“Contacts with ≥1 recorded commission”); the record KPI for the same figure is Applicants referred. Pick one.

​
8. Truncation markers are unexplained in-product

5+ on stat cards, ≥ in the readiness counts, and 4+ on record KPIs all mean “this is a floor, not a total”. Nothing on screen says so. The guides explain it in three places, which suggests a tooltip would be cheaper.

​
9. The Feedback widget overlaps table content

The account-wide Feedback pill is fixed to the bottom-right and sits over the last partner row’s open affordance at common window sizes. Visible in the captured screenshots, which keep it because it is real UI.

​
Behavior we could not verify live

Local verification ran against a self-contained backend with seeded partner, commission, and payout data. These paths need a real CRM-connected account:

​
Facts stated in the guides that need a product owner’s confirmation

  1. Pending partner status is documented as “signed up but not yet approved or enrolled in a campaign”. Status text passes through from the CRM, so confirm that reading is right for our campaign configuration.
  2. Partner since is documented as the date the partner record was created in the CRM. Confirm operators should not read it as an agreement date.
  3. Weekly PDF is recommended as the default reporting cadence. That matches the shipped default; confirm it is also the recommendation we want in print.
  4. 15% / commission rates are deliberately not mentioned. Rates live in the CRM campaign and vary per account, so the guides point at the CRM instead.

​
Stale internal documentation

docs/design/partner-module.md still describes and indexes app/admin/partners/* (list, detail, useAffiliatePartners.ts, PartnerReportingSettingsCard.tsx). Those files do not exist — FUND-2046 consolidated the admin surface onto the operator /partners route with isAdmin gating. Worth a follow-up edit so the next person reading that design note does not go looking for a route that is gone.