Overview
Client Portals is a standalone, licensable product. Each client gets a subdomain at <slug>.clientportals.vip — a private Cloudflare Pages site gated by a passphrase. The portal shell handles chrome (nav, footer, auth, theme) and exposes a feedback and ticketing API hosted at api.clientportals.vip.
The shell is deliberately a single vanilla JS file with no dependencies. Any HTML page becomes a portal page with one script tag.
Module catalog
Runtime script
Served from https://api.clientportals.vip/portal-shell.js. Drop one script tag into any portal page:
<script src="https://api.clientportals.vip/portal-shell.js"></script>
The script reads configuration from window.PORTAL_CONFIG (required) and inserts the nav and footer synchronously. Auth is enforced immediately on load before any page content renders.
The runtime file in the repo lives at services/feedback-api/portal-shell.js. After any change, sync and restart on ArcHelm:
cp ~/projects/the-grid/services/feedback-api/portal-shell.js \ ~/portal-feedback-api/portal-shell.js bash ~/restart-api.sh
PORTAL_CONFIG reference
Define window.PORTAL_CONFIG in a portal.config.js file loaded before the portal-shell script tag. Every chrome page (account, tickets, feedback) must also include portal.config.js or auth will fail.
// portal.config.js
window.PORTAL_CONFIG = {
tenant: 'fortknox',
clientName: 'Fort Knox',
wordmark: 'Fort Knox',
feedbackKey: 'fk-fortknox-fbk-8v1j6q',
ticketKey: 'fk-fortknox-tkt-1n8p5r',
themeKey: 'fk-theme',
authKey: 'fk_fortknox_auth',
clientId: '178b6350-95c4-4697-b29e-52387b443328',
};
| Field | Type | Required | Description |
|---|---|---|---|
| tenant | string | required | Slug used by the feedback API. No hyphens — strip them (beyond-sleep becomes beyondsleep). |
| clientName | string | required | Full client display name shown in the Account dropdown. |
| feedbackKey | string | required | x-api-key for /pins feedback endpoints. Issued per tenant in portal-feedback-api/.env. |
| themeKey | string | required | localStorage key for theme preference. Must be unique per client. Convention: <tenant>-theme. |
| authKey | string | required | sessionStorage key set by gate.html on login. Must be unique. Convention: <tenant>_auth. |
| wordmark | string | optional | Nav display name. Defaults to clientName. |
| ticketKey | string | optional | x-api-key for /tickets endpoints. Omit if tickets module is not active. |
| clientId | string (UUID) | optional | Surface client UUID. Required for review-share.js reviewer link generation. |
| heroImage | string (URL) | optional | Hero image on the portal index page. Defaults to the shared stock photo. |
| allowSignup | boolean | optional | Renders a "Request access" flow on gate.html. Defaults to false. |
Toolbar rules
The feedback toolbar appears on inner (content) pages when feedbackKey is set. It is always suppressed on chrome pages.
| Page type | data-toolbar attribute | Toolbar |
|---|---|---|
| gate.html | No portal-shell script | Never |
| account, tickets, feedback | data-toolbar="off" | Never |
| index, viewer, custom content | Omit attribute | When feedbackKey is set |
Pages in subdirectories (strategy/, docs/) also need data-index and data-gate attributes on the portal-shell script tag, otherwise nav and auth redirect to the wrong paths.
TypeScript package
The @arcgrid/portal-shell package at packages/portal-shell/ provides typed config, a validation helper, and a programmatic scaffold wrapper.
import { createPortalConfig, PORTAL_PAGE_TYPES } from '@arcgrid/portal-shell'
const config = createPortalConfig({
tenant: 'fortknox',
clientName: 'Fort Knox',
feedbackKey: 'fk-fortknox-fbk-8v1j6q',
themeKey: 'fk-theme',
authKey: 'fk_fortknox_auth',
})
// throws if required fields are missing or tenant contains hyphens
Key exports: PortalConfig interface, createPortalConfig(), scaffoldKeys(), PORTAL_PAGE_TYPES, TOOLBAR_RULES, CHROME_PAGES.
Scaffold a portal
Always scaffold from the template — never build from scratch.
bash scripts/new-portal.sh <slug> "Client Name" ["Eyebrow Text"]
This copies all template pages, generates a portal.config.js with fresh API keys, and creates a wrangler.toml. After scaffolding:
clients/<slug>/portal/gate.html and replace CHANGEME.~/portal-feedback-api/.env TENANT_KEYS, then run bash ~/restart-api.sh.<slug>-portal.npx wrangler pages deploy clients/<slug>/portal --project-name <slug>-portal --branch main<slug>.clientportals.vip to <slug>-portal.pages.dev.Deploy
Always deploy from ArcHelm, not from a local machine. Always verify the branch before deploying:
git branch --show-current npx wrangler pages deploy clients/<slug>/portal \ --project-name <slug>-portal \ --branch main
After deploying, run the post-deploy checklist: gate passphrase, toolbar presence on content pages, toolbar absence on chrome pages, theme persistence, account page loads without redirect.
Run python3 scripts/audit-portal.py <slug> to catch THEME-KEY, CFG-ORDER, and CHROME-NO-CFG flags before and after any migration.