---
title: "Partner Portal Governance"
slug: partner-governance
section: Portals
group: Partner Portal
status: stable
description: "How partner authority, visibility, and lifecycle phases are governed across the ecosystem"
last-updated: 2026-10-07
---

# Partner Portal Governance

How partner authority, visibility, and lifecycle phases are governed across the ecosystem

> **Partner Organization Taxonomy**
>
> This page covers the Recruiter category of Partner Organizations. For the canonical taxonomy covering both categories (Employer/Host and Recruiter), shared governance, entry flows, finance, and API surface, see the Partner Organizations reference page.

## Partner Lifecycle Model

This section is the recruiter-side depth on the agreement state machine. The full state machine, approver requirements, probation 50% quota cut, 15-minute auto-expiry job, and 10-character reason rule are documented canonically in Partner Agreements → Lifecycle & State Machine . The states below are the same record on the recruiter side; only the side-effects differ.

> **Architectural Boundary**
>
> Partner Portal does not own business authority. All enforcement, quotas, and compliance controls are centralized in Globus. Globus decides. Partner Portal reflects.

### Lifecycle Phases (Recruiter View)

Recruiter-side side-effects of each agreement state:

| State | Recruiter-Side Side-Effect |
| --- | --- |
| draft | No portal access. No applicant submissions accepted. |
| active | Portal access enabled. Quota counter live. Bulk upload enabled (if permitted). Reservations allowed within autonomy level. |
| probation | Effective quota cut to 50% of allocation. Reservations enhanced-reviewed. Audit verbosity raised. Status visible in portal. |
| suspended | Portal becomes read-only. New submissions and reservations blocked. Existing applicants continue under sponsor control. |
| expired | Auto-flipped within 15 minutes of endDate. Portal access revoked. Any still-open reservation holds continue to age and release at their hold expiry (hold window `holdDurationDays`, default 7 days, resolved through the rule-library cascade). |
| terminated | Portal access revoked. Records retained for compliance audit. |

The visual below shows the same states as the agreement state machine on the canonical page.

Active — portal enabled, quota live 
Setup / Probation — restricted but recoverable 
Suspended / Expired / Terminated — access revoked 
## Partner Onboarding Lifecycle

Before a partner (external or internal) can recruit applicants, they must be onboarded through a structured process managed by the sponsor. Internal partner organizations follow the same onboarding flow but may authenticate via sponsor SSO and have different RBAC configuration:

### Partner Agreement Structure (Recruiter Side)

The full agreement model — shared spine, host vs. recruiter extensions, structured knobs vs. narrative terms, and the side-by-side field map — is documented canonically in Partner Agreements → Agreement Model . This section enumerates the recruiter-relevant fields and the recruiter-only extensions that ride on top of the shared spine.

Recruiter Agreement Fields

> **Typed Extension Record: recruiter_agreement_extension**
>
> The recruiter-specific fields above (intake submission cap, portal role assignments, external/internal sponsor marker, autonomy tier detail, bulk-upload entitlement) live on a thin recruiter_agreement_extension row keyed 1:1 to the shared partner_agreements row. The shared spine carries lifecycle, scope, quotas linkage, and audit; the extension carries only what recruiters genuinely need beyond the shared core. Field-by-field definitions are in Partner Agreements → Typed Extension Records .

> **Structured vs. Narrative**
>
> Country restrictions, job-type restrictions, quota, and scope are structured knobs read by guards. Narrative terms live as freeform JSONB and are read by humans, not by guards. See Structured Knobs vs. Narrative Terms . Note the host-side creation-flow difference: new host agreements take their legal content from a published Agreement Library entry linked at creation (engine_agreement_code), not from freeform terms — recruiter agreements are unchanged and keep freeform terms JSONB. See Agreements Engine → Host Agreement Library Linkage .

> **Canonical Portal Copy**
>
> Partner-portal status banners, lifecycle chips, and agreement-editor copy are specified in Partner Agreements → Portal Copy & Label Alignment . Recruiter-facing surfaces should render exactly what that table prescribes — one label set, one reason-code vocabulary, no portal-side rewording.

> **No Recruiter Operating Agreement**
>
> The operating-agreement concept is host-only. Recruiters do not have an operating-agreement predicate; their authorization is fully expressed by the agreement record (active status, in-window endDate, scope, quota, restrictions). See Operating Agreement (Host-Only) .

### Recruiter Enforcement Mechanics

Guard preconditions, atomic quota counter, reservation TTLs, and the hold-age escalation ladder (hold_warn_hours / hold_cut_hours / hold_freeze_hours, defaults 3 / 5 / 8) are described in Partner Agreements → Enforcement & Quota Mechanics . Recruiter-specific applications:

## Recruitment Phase (Interactive)

During intake and placement, partners actively participate in the recruitment process. The following actions may be available depending on agreement terms and role permissions:

All actions during the recruitment phase are governed by five enforcement layers:

See Quota Model & Capacity Controls for full definitions of quota types and enforcement details.

## Post-SEVIS Phase (Read-Only Milestone Visibility)

After DS-2019 issuance and SEVIS actions, partners transition from interactive participants to read-only observers. They maintain visibility into applicant progress but can no longer take operational actions.

> **Partners Don't Drop Off After DS-2019**
>
> Partners remain operationally informed throughout the applicant lifecycle. Read-only milestone visibility ensures partners can track outcomes for the applicants they recruited without requiring sponsor staff to manually relay status updates.

### Milestone Visibility

Partners can see the following milestones for applicants they recruited:

### Partner Restrictions

Recruiter restrictions split into two groups: structured agreement-level restrictions enforced by the guard layer on every action, and post-SEVIS authority restrictions that hold regardless of agreement state.

Structured Agreement Restrictions (Guard-Enforced)

Post-SEVIS Authority Restrictions

## Governance Principle

Partners remain operationally informed throughout the full applicant lifecycle, but authority remains centralized in Globus at every phase. The partner's role transitions from active participant to informed observer — never to decision-maker.

> **Core Governance Rule**
>
> Globus decides. Partner Portal reflects. This principle applies uniformly across the recruitment phase, the SEVIS transition, and the post-program lifecycle. There is no phase in which a partner gains autonomous authority over sponsor-controlled processes.

| Phase | Partner Role | Authority |
| --- | --- | --- |
| Recruitment | Active participant | Submit applicants within agreement scope |
| Placement | Active participant | Nominate candidates, reserve job order positions |
| Visa / SEVIS | Transition point | None — sponsor-only SEVIS operations |
| Arrival | Read-only observer | View milestone status only |
| Active Program | Read-only observer | View milestone status only |
| Completion | Read-only observer | View final outcome only |

## Partner Autonomy Decision Framework

The ecosystem defines how much operational autonomy partners receive on the A–D scale (canonical: Restrictions & Autonomy). Both sides use the same A–D framing; the recruiter-side reading of each level is described below.

> **This Is a Strategic Decision, Not a Technical One**
>
> The architecture supports all four levels below. But the sponsor must decide which level each partner class operates at — and that decision should be made before building partner-facing features beyond recruitment.

### Autonomy Levels

> **Architecture Supports All Levels**
>
> The modular design (RBAC + quotas + agreement scoping + workflow engine) means the system can support different autonomy levels for different partner classes simultaneously. A camp recruitment partner might operate at Level A while a regional Teach partner operates at Level C.

## Performance & Risk Scoring

Sponsors must monitor partner quality over time. Performance scoring ties directly into the Partner Agreement model — a partner with declining quality metrics may have their agreement downgraded, placed on probation, or suspended entirely.

### Monitored Metrics (Recruiter Slice of the 10-Metric Model)

The full 10-metric performance model (5 shared, 2 recruiter-only, 3 host-only) and the Critical / Warning / Acceptable tiering live on the canonical page at Partner Agreements → Performance & Adherence . Recruiters are scored on the 5 shared metrics plus 2 recruiter-only metrics (7 total).

| # | Metric | Origin | Recruiter Read |
| --- | --- | --- | --- |
| 1 | Submission Quality | Shared | Rate of submitted applicants that pass intake review without rework. Picks up upstream signals like document quality and pre-screening discipline. |
| 2 | Compliance Document Health | Shared | Currency of partner-side compliance documents (pending / approved / expiring / expired). |
| 3 | Reservation Discipline | Shared | Hold conversion vs. expiry rate against the agreement's TTL policy. |
| 4 | Time-to-Action | Shared | Median time from sponsor request to recruiter response on review items. |
| 5 | Audit Hygiene | Shared | Guard denials per 1k actions. High denial rate signals scope or quota drift. |
| 6 | Visa Outcome Rate | Recruiter-only | Visa issuance vs. denial vs. no-show on recruiter-attributed applicants. |
| 7 | Pipeline Throughput | Recruiter-only | Quota utilization at season midpoint vs. season end. |

> **Recommendation, Not Verdict**
>
> Tiered metrics produce a status recommendation. Downgrade transitions (probation, suspension, termination) still require a non-empty reason and write an audit entry. The system never autonomously downgrades an agreement.

### Partner Status Model

> **Org lifecycle vs agreement lifecycle**
>
> “Partner status” here refers to the agreement lifecycle (the state of the partner's active agreement record), not the organization-lifecycle notion of whether the partner exists in the network. DS-2019 issuance, quota, and portal access are all gated by the agreement lifecycle below. The organization's own lifecycle state and history are read with `GET /api/partner-orgs/:id/lifecycle` (`partners.view`; 404 `NOT_FOUND` for an unknown organization). It returns `hostOrgId`, `currentState`, `terminatedAt` and an `audit` list (oldest first) of `fromState`, `toState`, `reason`, `occurredAt` plus the actor's name, email and role. State changes go through `POST /api/partner-orgs/:id/transition` (`partners.manage`).

Performance metrics produce status recommendations that ride on top of the canonical agreement state machine ( draft → active → probation → suspended → expired → terminated ):

> **Status Transitions Are Audited**
>
> Manual status transitions record the acting user and an audit row; probation, suspension and termination also require a non-empty reason. Activation and automatic expiry do not take a reason. The system never autonomously downgrades an agreement — recommendations from the metrics engine still go through a human approver.

**Admin route refusals.** `POST /api/admin/partners/organizations/:orgId/calculate-metrics` (`partners.read` scope plus the `partners.performance.view` permission; optional `seasonId` and `programId` in the body) returns 404 `PARTNER_ORG_NOT_FOUND` for an unknown organisation. `POST /api/admin/partners/organizations/:orgId/status-change` (`partners.manage`) takes `status`, `reason` (at least 10 characters), `reasonCategory`, `notes` and `confirmation_token`; an empty `status` returns 400 `MISSING_STATUS`, and a `reasonCategory` outside `non-compliance`, `voluntary_withdrawal`, `contract_expiration` and `other` returns 400 `INVALID_REASON_CATEGORY`. A category is required when the new status is `suspended` or `terminated` (in which case it can stand in for a short reason). These errors use the `error.code` envelope.

## Bulk Applicant Upload

Partners operating recruitment networks need to submit candidates at scale. Individual form entry is not operationally viable. The bulk upload capability is essential for partner productivity and is the primary mechanism for the Partner Invite Trigger described in Direct vs Partner Entry.

### Upload Workflow

Each upload is quota-checked — if remaining quota is less than the number of valid rows, the entire batch is rejected / Attribution (Partner ID, Agreement ID) is auto-applied to every row and cannot be edited by the partner / Duplicate detection prevents re-inviting applicants who already exist in the system / Upload history and error reports are retained for audit
> **Invitation Links Are Also Supported**
>
> In addition to CSV upload, partners can generate unique invitation links for individual candidates. These links carry pre-tagged partner attribution and program-specific context. See White-Label Application Links for details.

## Bulk Operations Architecture

*Status: design spec, largely not built. The built path is `POST /api/admin/partners/organizations/:orgId/bulk-invite` (`routes/partners/invites.ts`), which takes a `rows` JSON array, processes it inline in the request and returns 201 with the result; insufficient quota rejects the whole batch (409 `BATCH_QUOTA_EXCEEDED`). There is no background job queue, SSE or polling progress, row or size cap, cooldown, daily limit, queue-depth 429 or Redis upload lock.*

The built `POST /api/admin/partners/organizations/:orgId/bulk-invite` route requires `partners.manage`, plus the `partner.applicants.write` partner-user capability and the enforcement guard (recruitment and placement phases only), and is audited as `partner.invite.bulk`. Body: `programId`, `seasonId`, `rows` (at least one), optional `brandId` and `fileName`.

Partners operating large recruitment networks may submit hundreds of candidates per upload. The bulk operations architecture defines how the system processes these uploads at scale without blocking the UI, overwhelming downstream services, or creating data integrity issues.

> **Uploads Are Asynchronous**
>
> Bulk uploads are never processed synchronously in the request cycle. Every upload is enqueued as a background job, validated row-by-row, and results are made available asynchronously. The partner sees real-time progress in the UI while the job runs.

### Upload Lifecycle

Every bulk upload follows a defined lifecycle from file receipt to completion:

Terminal states: Complete (all rows processed), Partial (some rows failed), Failed (system error or quota exceeded)

### Rate Limiting & Constraints

Rate limits protect the system from being overwhelmed by concurrent uploads:

| Constraint | Limit | Rationale |
| --- | --- | --- |
| Max rows per file | 500 | Prevents oversized payloads; partners can split across multiple uploads |
| Max concurrent uploads per partner | 1 | Prevents race conditions on quota counters and duplicate detection |
| Max file size | 5 MB | Prevents memory pressure during parsing |
| Upload cooldown | 60 seconds between uploads | Prevents rapid-fire submissions that bypass validation feedback |
| Daily upload limit per partner | 10 uploads / 24 hours | Prevents abuse; escalation available for high-volume partners |
| Global queue depth | 100 pending jobs | Back-pressure mechanism; new uploads return 429 when queue is full |

### Validation Queue Behavior

Validation is performed row-by-row within the background job. The system supports partial success — valid rows are processed even if other rows fail:

Each row is validated independently: required fields, email format, nationality, program eligibility / Duplicate detection checks email + program + season against existing applicants and other rows in the same batch / Rows failing validation are collected into an error report with: row number, field name, error code, and human-readable message / Valid rows proceed to processing immediately after validation passes (streaming pipeline, not batch-then-process) / If remaining quota is insufficient for all valid rows, the system processes rows up to the quota limit and marks remaining rows as quota-exceeded
> **Partial Success Is the Default**
>
> The system does not reject an entire batch because some rows are invalid. Valid rows are always processed. The error report clearly separates successful rows from failed rows with specific reasons for each failure.

### Real-Time Progress Tracking

Partners see real-time progress for each upload in the Partner Portal UI:

Progress updates are delivered via Server-Sent Events (SSE) or polling with a 5-second interval. The upload history page shows all past uploads with their final status and downloadable error reports.

### Concurrent Upload Handling

Only one upload per partner may be actively processing at any time:

If a partner uploads while a previous upload is still processing, the new upload is rejected with HTTP 409 and a message indicating the in-progress job ID / The partner can cancel a queued (not yet processing) upload and submit a new one / Once an upload enters the Processing state, it cannot be cancelled — it must run to completion / Different partners can upload simultaneously without interference — concurrency control is per-partner, not global / The system uses a distributed lock (Redis SETNX with TTL) keyed by partner_org_id to enforce single-upload-at-a-time
### Quota Reservation During Processing

Quota must be managed carefully during batch processing to prevent over-allocation:

> **Quota Is Never Over-Consumed**
>
> The soft reservation mechanism ensures that concurrent uploads from different partners (or the same partner across agreements) cannot exceed total available quota. See Quota Model for full quota enforcement details.

### Retry & Idempotency

The system must handle retries gracefully without creating duplicate records:

| Scenario | Behavior |
| --- | --- |
| Job worker crashes mid-processing | Job is retried from the last checkpoint. Already-processed rows are skipped via idempotency key (upload_id + row_number). |
| Partner re-uploads the same file | Duplicate detection catches rows that already exist. New rows are processed. Error report notes duplicates. |
| Network timeout during upload | Partner can check upload status by job ID. If the file was received, processing continues. If not, they re-upload. |
| Email delivery fails for an invite | Email is retried independently via the communications queue (P8). Applicant record is still created. |
| Quota changes during processing | Each row checks quota at processing time. If quota is exhausted mid-batch, remaining rows are marked quota-exceeded. |

## Suspension & Offboarding Lifecycle

*Status: partly design spec. Terminating an agreement (`terminateAgreement`, `partnerAgreementEngine.ts`) only flips the status, freezes the agreement's quotas and emits the event and notification; the 48-hour reservation grace period and the 30-day draft auto-discard described below are not implemented.*

When a partner is suspended, terminated, or their agreement expires, there are in-flight applications that must be handled. This section defines the operational mechanics of partner offboarding — what happens to applicants, data, and pipeline records.

> **Applicants Are Never Abandoned**
>
> Regardless of partner status change, every in-flight applicant must have a clear owner. The system automatically reassigns orphaned applicants to the sponsor operations team to ensure continuity.

### In-Flight Application Handling Matrix

What happens to applications at each lifecycle stage when the partner's status changes:

| Applicant Stage | On Suspension | On Termination | On Expiry |
| --- | --- | --- | --- |
| Draft (incomplete) | Frozen. Partner cannot edit. Sponsor ops can resume or discard. | Auto-discarded after 30-day hold. | Frozen during grace period. Auto-discarded after. |
| Submitted (under review) | Continues processing under sponsor control. Partner loses edit access. | Continues processing under sponsor. Attribution preserved. | Continues processing. No interruption. |
| Approved (pre-placement) | Remains in matching pool. Sponsor takes ownership of placement. | Remains in matching pool. Sponsor takes ownership. | Remains in matching pool. No change. |
| Reserved (position held) | Reservation continues. Sponsor manages confirmation. | Reservation continues. Sponsor manages confirmation. | Reservation continues. No change. |
| Placed (confirmed) | Placement continues. Post-SEVIS lifecycle unaffected. | Placement continues. Post-SEVIS lifecycle unaffected. | Placement continues. No change. |
| In Program (active) | No impact on active participants. | No impact on active participants. | No impact on active participants. |

### Applicant Reassignment Rules

When a partner loses access, applicant ownership must transfer seamlessly:

### Reservation Release Behavior

Held reservations on job order positions are handled based on the type of status change:

On Suspension: Active reservations are frozen. The sponsor can confirm or release them individually. No auto-release. / On Termination: All unconfirmed reservations are released after a 48-hour grace period for sponsor review. Positions become available on the job orders for other partners. / On Expiry: Reservations follow the standard hold policy. If the hold timer expires, they release normally. No special behavior. / Confirmed placements are never affected by partner status changes. Once confirmed, the placement belongs to the program lifecycle.
### Data Handoff Procedures

Data access changes immediately upon partner status change:

| Data Type | Partner Access After Offboarding | Sponsor Access |
| --- | --- | --- |
| Applicant Records | No access (API returns 403) | Full read/write access retained |
| Upload History | No access | Full access. Error reports preserved. |
| Quota Usage Data | No access | Historical data retained for reporting |
| Performance Metrics | No access | Metrics preserved for audit and future decisions |
| Partner Agreement | No access | Agreement record archived with full history |
| Audit Trail | No access | Complete audit trail retained permanently |

### Pipeline Cleanup Automation

Scheduled jobs resolve orphaned records and clean up the pipeline after partner offboarding:

### Notification Flows

Multiple stakeholders are notified when a partner's status changes:

| Recipient | On Suspension | On Termination | On Expiry |
| --- | --- | --- | --- |
| Partner Admin | Immediate email: access suspended, reason, next steps | Immediate email: agreement terminated, data retention policy | 30-day warning, 7-day warning, expiry confirmation |
| Partner Users | Next login shows suspension notice | Next login shows termination notice | No direct notification (admin is responsible) |
| Affected Applicants | No notification (transparent to applicants) | No notification (sponsor takes over seamlessly) | No notification |
| Sponsor Ops Team | Dashboard alert + email: partner suspended, N applicants reassigned | Dashboard alert + email: partner terminated, N applicants reassigned | Dashboard alert: partner agreement expired, N applicants in pipeline |
| Sponsor Admin | Summary report of impact | Summary report of impact | Renewal reminder 60 days before expiry |

### Grace Period Rules

Different offboarding triggers have different grace periods:

### Re-Activation Path

A suspended partner can be reinstated if the underlying issues are resolved:

> **Terminated Partners Cannot Be Re-Activated**
>
> Termination is permanent. If a previously terminated partner needs to resume operations, a new Partner Organization and Partner Agreement must be created. Historical records from the terminated entity are retained but not linked to the new organization.

## Partner Document Center

Partners may need to upload and manage documents beyond applicant-specific files. The Partner Document Center provides a structured location for organizational documents that are governed by the Partner Agreement.

| Document Type | Purpose | Managed By |
| --- | --- | --- |
| Marketing Materials | Recruitment collateral approved by sponsor | Partner uploads, Sponsor reviews |
| Recruitment Reports | Periodic intake and pipeline summaries | Partner uploads |
| Insurance Confirmations | Proof of required insurance coverage | Partner uploads, Sponsor validates |
| Country Compliance Documents | Local regulatory compliance evidence | Partner uploads, Sponsor reviews |
| Partner Agreement (signed) | Executed contract for audit reference | Sponsor uploads |
| Training Certifications | Proof of completed sponsor training | System-generated or Partner uploads |

Documents in the Partner Document Center are scoped to the Partner Organization and visible to all users within that organization (subject to their role). Sponsor staff can access any partner's documents within their brand scope. Documents are version-controlled — uploading a new version preserves the previous version for audit.

> **Document Center Is Not a File Share**
>
> The Document Center stores governance-relevant documents only. It is not a general-purpose file sharing system. Applicant-specific documents (passport, background check, etc.) live on the applicant record in the Applicant Portal, not in the Partner Document Center.

**Storage.** `partner_documents` backs the Document Center with one row per uploaded version (`document_type`, `file_name`, `file_url`, `version`, `previous_version_id`, `uploaded_by`, `notes`, `is_active`, optional `agreement_id`).

## Portal Authentication

The Partner Portal uses a two-layer authentication model: an identity provider handles “who is this person?” and Globus handles “what can they do?” These are separate, non-overlapping concerns.

### Authentication Flow

> **Identity Is External, Authorization Is Globus**
>
> The identity provider only answers “is this a real person?” Globus answers “what can they do?” by resolving the email to an organization, role, and agreement. If a user authenticates successfully but Globus does not recognize their email, they see the Unlinked Account screen — not an error.

## User Management

Partner organizations manage their own team members through the Partner Portal. User management is self-service for Partner Admins, with Globus enforcing role boundaries and scope limits.

### Portal User Roles

| Role | Permissions | Managed By |
| --- | --- | --- |
| Partner Admin | Full portal access. Invite/remove team members, manage organization settings, view all applicants and quotas, upload documents. | Sponsor (initial), then self-service |
| Recruiter | Create and manage applicants, upload documents, view quota utilization, browse job orders and available capacity (if enabled). Cannot manage team or org settings. | Partner Admin |
| Read-Only | View applicant status, milestones, quota dashboards, and documents. Cannot create, edit, or upload. | Partner Admin |
| Finance | View payment status, fee summaries, and financial reports. Cannot modify applicant or quota data. | Partner Admin |

### User Lifecycle

Partner-portal user acceptance route (portal auth, no staff permission; audited as `partner_user.portal_accepted`):

- `PATCH /api/partner/me/users/accept`: the `X-Partner-User-Email` header is required (400 `BAD_REQUEST`). Marks the matching active partner user in the caller's organization as accepted (`acceptedAt`); 404 `NOT_FOUND` if there is none, and a repeat call returns `alreadyAccepted: true` with the original `acceptedAt`.

## Operational Command Center

The Partner Portal dashboard has been redesigned as an Operational Command Center — a premium, recruiter-first workspace that puts the daily recruitment workflow front and center. Governance and compliance panels remain accessible via a secondary Admin tab, but the primary view is optimized for pipeline management, candidate attention, and placement velocity.

> **Recruitment-First Dashboard**
>
> Recruitment IS the daily job for partners. The Command Center leads with a live pipeline hero, open opportunities, candidates needing attention, and a placement scoreboard — the panels recruiters interact with every day. Governance panels (Agreement Status, Quota Utilization) are demoted to a compact Admin tab, accessible but never competing for daily attention.

### Recruitment Panels (Primary View)

The primary dashboard tab displays recruitment-focused panels in a responsive card grid. Each card is draggable, collapsible, and animates with smooth framer-motion transitions. The layout defaults to recruitment-optimized ordering for new users.

Hero Panel

Live Pipeline Overview

Full-width hero panel showing real-time applicant counts by lifecycle stage: Draft → Submitted → Reviewed → Matched → Placed → On-Program → Completed. Each stage is a clickable segment that drills into the filtered applicant list. The hero includes a sparkline trend for total pipeline volume over the last 30 days, a “stuck” indicator highlighting stages with stalled applicants (no movement in 7+ days), and a color-coded health bar summarizing overall pipeline flow.

### Admin & Governance (Secondary Tab)

Governance and compliance panels are moved to a secondary “Admin” tab within the Command Center. This keeps them accessible for periodic review without competing for daily attention on the primary recruitment view. The Admin tab can also be rendered as a compact sidebar strip on wide screens (1440px+), showing condensed status indicators alongside the recruitment panels.

> **Governance Panels Are Accessible, Not Primary**
>
> The Admin tab ensures partners can always review their agreement status, quota health, and compliance posture. On wide screens, a compact sidebar strip surfaces key status indicators (agreement status chip, quota progress bar) without requiring a tab switch. This design keeps governance visible but never blocks the recruitment workflow.

### Recruitment Performance KPIs

The Performance Metrics panel is enhanced with recruitment-specific KPIs that give partners actionable insight into their recruitment efficiency and pipeline health. Metrics update in near-real-time and include trend indicators comparing the current period to the previous period.

| KPI | Definition | Visualization |
| --- | --- | --- |
| Pipeline Velocity | Average number of days an applicant spends in the pipeline from submission to placement. Lower is better. | Trend line (30-day) |
| Match Conversion Rate | Percentage of submitted candidates who are successfully matched to a job order. Measures sourcing quality. | Percentage gauge |
| Time-to-Placement | Median calendar days from applicant submission to confirmed placement. Broken down by program type. | Bar chart by program |
| Placement Rate | Percentage of recruited applicants who reach the Placed status within the current agreement period. | Progress ring |
| Candidate Drop-off Rate | Percentage of applicants who enter the pipeline but withdraw or are rejected before placement. | Funnel chart |
| Approval Rate | Percentage of submitted applicants approved on first review (no resubmission required). | Percentage with trend |
| Active Pipeline Size | Total number of applicants currently in active pipeline stages (submitted through matched). | Counter with sparkline |
| Partner Ranking | Anonymized percentile ranking among partners in the same tier, based on composite performance score. | Percentile badge |

> **KPI Context Matters**
>
> Each KPI is shown with period-over-period trend arrows (up/down/flat) and a contextual tooltip explaining what “good” looks like. Partners can drill into any KPI to see the underlying applicant-level data. KPIs that fall below tier thresholds are highlighted with an amber or red indicator to prompt corrective action.

### Premium UX Interaction Model

The Command Center is designed as a premium, recruiter-friendly workspace with A-grade UX. Every interaction is polished: cards animate smoothly, layouts are personalized, and the dashboard feels like a tool built for power users who live in it daily.

### Personalization & Defaults

Dashboard layout preferences are stored per user and restored on every login. New users receive a recruitment-optimized default layout that surfaces the most impactful panels first.

interface DashboardPreferences

userId: string;

layoutVersion: number;

activeTab: "recruitment" | "admin";

cardOrder: string[]; // ordered card IDs for the recruitment tab

collapsedCards: string[]; // card IDs in collapsed state

adminSidebarExpanded: boolean; // wide-screen sidebar strip preference

lastModified: string; // ISO timestamp

> **Personalization Is Per-User, Not Per-Org**
>
> Each user within a partner organization has their own dashboard layout. This ensures that a recruiter's daily view is not disrupted by an admin changing their layout. Org-level default overrides are a future consideration but not part of the initial release.

## Agreement Activation

Partner agreements follow a structured activation workflow. An agreement must be fully activated before the partner can begin recruiting. Activation ensures all prerequisites are met and the partner is properly configured in Globus.

### Activation Workflow

> **Agreement Must Be Active Before Recruitment**
>
> Partners cannot submit applicants, reserve job order capacity, or access recruitment features until their agreement is in the Active state. The portal enforces this by checking the agreement status on every bootstrap call. Draft, pending, or expired agreements block all write operations.

## Partner Organization Profile

Each partner organization maintains a profile that represents their company within the ecosystem. Globus stores the canonical record; the Partner Portal provides the UX for partners to view and maintain their information. Profile data is used across the system for attribution, reporting, and communication routing.

> **Globus Owns the Record**
>
> The partner organization profile is a Globus-managed entity. Partners can update certain fields through the portal, but Globus validates, stores, and serves the canonical version. Sponsor staff can view and override any partner profile field.

### Profile Fields

| Field | Editable By | Description |
| --- | --- | --- |
| Company Name | Sponsor only | Legal name of the partner organization. Set during onboarding. |
| Display Name | Partner Admin | Friendly name shown in portal UI and communications. |
| Company Description | Partner Admin | Brief description of the organization and its recruitment focus. |
| Website URL | Partner Admin | Partner company website. Validated for format on save. |
| Primary Contact Name | Partner Admin | Main point of contact for sponsor communications. |
| Primary Contact Email | Partner Admin | Email for operational communications. Must match a portal user. |
| Primary Contact Phone | Partner Admin | Phone number for urgent communications. |
| Recruitment Regions | Partner Admin | Countries and regions where the partner actively recruits. |
| Specialization Areas | Partner Admin | Program types or industries the partner specializes in (e.g., hospitality, agriculture). |
| Origin Type | Sponsor only | Whether the partner is External (third-party) or Internal (sponsor staff). Set at creation. |
| Logo | Partner Admin | Organization logo displayed in portal header and reports. |

Governance inheritance (a child organization inheriting `agreement`, `contacts` or `documents` from its parent) is managed with `PATCH /api/admin/partners/organizations/:id/governance-inheritance` (`partners.manage`; body `field` and `enabled`) and, for the parent link, `PATCH /api/admin/partners/organizations/:id/parent`. Both return 422 `GOVERNANCE_INHERITANCE_PARENT_FIELD_EMPTY` when inheritance would be ON for a field the parent has not populated (enabling with no parent linked returns the same code with a null `parentOrganizationId`; linking a parent while a flag is ON checks every ON flag). A `field` outside `agreement`, `contacts`, `documents` returns 422 `GOVERNANCE_INHERITANCE_UNKNOWN_FIELD`, with the allowed names in `details.allowed`.

## Notification System

The Partner Portal notification system keeps partners informed about events relevant to their recruitment pipeline and organizational status. All notification triggers originate from Globus-driven events — the portal renders and delivers them but does not generate the underlying triggers.

> **Notification Triggers Are Globus Events**
>
> Every notification displayed in the Partner Portal is triggered by a Globus event (applicant status change, quota threshold breach, agreement expiration, etc.). The portal subscribes to these events and renders notifications. Partners cannot create custom notification triggers.

### Notification Types

| Notification Type | Delivery | Description |
| --- | --- | --- |
| Applicant Status Change | In-app + Email | Triggered when an applicant moves between lifecycle stages (e.g., submitted → approved, placed → on-program). |
| Quota Threshold Warning | In-app + Email | Triggered when quota utilization reaches configurable thresholds (e.g., 80%, 90%, 100%). |
| Agreement Expiration Alert | In-app + Email | Sent at 60, 30, 14, and 7 days before agreement expiry. Critical alert at 3 days. |
| Document Attention Needed | In-app | Triggered when a partner-level document requires upload, renewal, or has been rejected by sponsor review. |
| Team Activity | In-app | Notifications when team members are added, removed, or change roles within the organization. |
| Reservation Expiring | In-app + Email | Sent when a held position reservation is approaching its expiration deadline. |
| Bulk Upload Complete | In-app | Triggered when an asynchronous bulk upload job finishes with success, partial, or failure status. |
| Performance Status Change | In-app + Email | Triggered when the partner’s performance status changes (e.g., active → probation). |

In-app notifications appear in a notification center accessible from the portal header. The notification center displays a badge count of unread items and supports mark-as-read, dismiss, and click-to-navigate actions.

### Notification Preferences

Partners can configure which notifications they receive via email. In-app notifications for critical events (agreement expiration, performance status changes) cannot be disabled.

## Settings & Preferences

The Partner Portal settings page provides user-facing configuration options. Settings are scoped to the individual user or the organization level. Organization-level configuration that affects quotas, agreement terms, or program access is managed exclusively by Globus and is not editable from the settings page.

> **Settings vs. Governance Configuration**
>
> The settings page controls user experience preferences (display, notifications, security). Governance configuration (quotas, agreement scope, program permissions) is Globus-managed and read-only in the portal. Partners cannot modify their own operational boundaries.

### Settings Modules

## Export & Reporting

Partners can export data from the portal for offline analysis and reporting. All exports are scoped to the partner's own applicants and agreement data — no cross-partner data is ever included.

> **Data Isolation in Exports**
>
> Exported data is strictly scoped to the partner's own applicants within their active agreement. Partners cannot export data belonging to other partners, and Globus enforces this scoping server-side. Export requests that attempt to access out-of-scope data are rejected with an authorization error.

### Available Exports

| Export | Format | Included Fields |
| --- | --- | --- |
| Applicant Pipeline List | CSV | Applicant name, email, nationality, program, season, current status, submission date, last updated, placement (if placed) |
| Quota Utilization Summary | CSV / PDF | Quota type, allocated amount, consumed amount, remaining, utilization percentage, trend over time |
| Recruitment Performance Report | PDF | Total applicants submitted, approval rate, average time-to-placement, placement success rate, performance score, comparison to prior seasons |
| Reservation Status Report | CSV | Job order ID, position title, host name, reservation date, hold expiration, status (held/confirmed/expired/released) |
| Activity Log Export | CSV | Timestamp, event type, user, applicant (if applicable), description, source system |

## Full Activity Log

Beyond the Command Center's recent activity widget, the Partner Portal provides a dedicated activity log page with full filtering and search capabilities. The activity log reflects Globus events scoped to the partner's data and provides a comprehensive audit trail of all actions and events.

> **Log Reflects Globus Events**
>
> The activity log displays events generated by Globus, filtered to the partner's scope. Partners see events for their own applicants, team members, and organizational actions. Internal sponsor actions (compliance decisions, SEVIS operations) are not visible to partners.

### Event Types

| Event Type | Description | Filterable |
| --- | --- | --- |
| Applicant Created | A new applicant record was created (individual or via bulk upload) | Yes |
| Status Changed | An applicant moved between lifecycle stages | Yes |
| Document Uploaded | A document was uploaded to an applicant record or the Document Center | Yes |
| Reservation Made | A position was reserved on a job order | Yes |
| Reservation Released | A reservation expired or was manually released | Yes |
| Placement Confirmed | An applicant placement was confirmed by the sponsor | Yes |
| Team Member Action | A team member was invited, activated, deactivated, or removed | Yes |
| Bulk Upload Completed | A bulk upload job finished processing | Yes |
| Quota Threshold Reached | A quota utilization threshold was crossed | Yes |
| Agreement Status Change | The partner agreement status changed (activated, expiring, expired) | Yes |

The activity log supports filtering by date range, event type, user (which team member performed the action), and applicant (filter events for a specific applicant). All filters can be combined. Results are paginated and sortable by timestamp.

## Advanced Search & Filtering

The Partner Portal provides search and filtering capabilities across the applicant pipeline, enabling partners to quickly find specific applicants or narrow their view to a relevant subset. All search and filter operations are scoped to the partner's own applicants — Globus enforces data isolation server-side.

> **Data Isolation Is Server-Enforced**
>
> Search and filter results only include applicants attributed to the partner's organization and active agreement. Globus enforces this scoping at the API level. There is no client-side filtering of cross-partner data — the data never leaves Globus.

### Filter Dimensions

## Applicant Detail View

When a partner clicks into an individual applicant, the detail view presents all information the partner is authorized to see. The level of detail and available actions depend on the applicant's current lifecycle phase and the partner user's role.

> **Required contract: Dynamic Field Surface Spec**
>
> The recruiter summary card and the recruiter applicant profile are two of the named partner surfaces (recruiter.summary, recruiter.profile) defined by the Dynamic Field Surface Spec . Beyond the hardcoded sections listed below, the profile view must include an “Additional Information” section that auto-renders any Workflow Studio field tagged for the surface — using the field's authored label. Audience filtering comes from the step-level data_scope plus the platform PII registry — there is no per-field redaction enum and no partner_visibility predicate; both were explicitly rejected and are recorded in DEPRECATED_DATA_ACCESS_TERMS (shared/contracts/dataAccessContract.ts). New Studio fields must appear on the matching surface without a code change. Hosts have parallel surfaces; see Host Portal → Dynamic Applicant Data Rendering .

### Detail View Sections

### Available Actions by Phase

| Lifecycle Phase | Available Actions | Access Level |
| --- | --- | --- |
| Draft | Edit personal info, upload documents, submit application, discard draft | Read-Write |
| Submitted / Under Review | View status, view documents (no edits). Cannot modify after submission. | Read-Only |
| Approved (Pre-Placement) | View approval details, nominate for positions, request reservations | Limited Write |
| Placed | View placement details, view host information, view timeline | Read-Only |
| In Program | View milestone updates (arrival, check-ins). No operational actions. | Read-Only |
| Completed / Withdrawn | View final status and outcome. Record is archived. | Read-Only |

> **Hidden from Partners**
>
> The applicant detail view intentionally excludes: internal staff notes and processing comments, compliance decision rationale, other partners' data or competing candidates, SEVIS-specific technical details, and sponsor-internal flags. These are restricted to Globus staff views.

## Document Expiration Visibility

The Partner Portal surfaces expiration status for partner-level organizational documents (insurance certificates, compliance filings, training certifications). This section covers partner organization documents — not individual applicant documents, which are managed through the applicant record.

> **Partner Org Documents vs. Applicant Documents**
>
> Partner organization documents (insurance, certifications, agreements) are managed in the Partner Document Center and governed by this section. Individual applicant documents (passport, background check, medical clearance) live on the applicant record and are managed through the Applicant Portal. These are separate systems with separate expiration tracking.

### Expiration Warning Thresholds

| Days Until Expiry | Warning Level | Portal Behavior |
| --- | --- | --- |
| 30 days | | Document shows an informational expiration countdown badge. No action required yet. |
| 14 days | | Document highlighted with warning indicator. Notification sent to Partner Admin. |
| 7 days | | Document flagged as urgent. Repeated notifications. Action Items panel updated. |
| Expired | | Document marked as expired. Globus may restrict recruitment operations until renewed. |

> **Enforcement Is a Globus Decision**
>
> The portal surfaces document expiration warnings and status indicators, but the decision to restrict partner operations when documents expire is made by Globus. The partner does not self-manage compliance. If Globus determines that an expired document blocks recruitment, the portal reflects that restriction — the partner cannot override it.

## Reservation Rules & Reservation Extension Workflow

Partners can reserve positions on approved job orders for their applicants. Reservations are time-limited holds that prevent other partners from claiming the same position. All reservation business rules — hold durations, Reservation Extension limits, and expiration behavior — are enforced by Globus. The Partner Portal provides the UX for requesting and viewing reservations.

> **Reservation Extension ≠ Program Extension**
>
> Reservation Extension (this section) extends the time-limited hold a partner has on a job position. It has no effect on SEVIS or program duration. Program Extension is a separate concept that extends a participant’s DS-2019 duration (see Applicant Lifecycle ).

> **All Reservation Rules Are Globus-Enforced**
>
> Partners cannot modify hold durations, extend reservations beyond allowed limits, or prevent automatic expiration. The portal provides the interface; Globus enforces the business logic. Reservation rules may vary by program, season, or partner performance tier.

### Hold Durations

| Reservation Type | Default Hold Duration | Max Reservation Extensions | Expiration Behavior |
| --- | --- | --- | --- |
| Reservation hold (job order or staff host) | 7 days (`holdDurationDays`, rule-library cascade) | 2 (`maxHoldExtensions`) | Position is automatically released back to the job order’s available pool. |

### Reservation Extension Request Workflow

When a partner needs additional time to confirm a reservation, they can request a Reservation Extension through the portal. Reservation Extensions are subject to availability and Globus approval:

## Partner Documentation Hub (Planned)

Partners will have access to a self-help documentation hub built into the Partner Portal (PP-F6). The documentation hub provides comprehensive guides for every portal feature, searchable from a clean landing page with feature cards — similar to developer documentation sites like Peach Payments. This reduces partner support load by giving partners on-demand access to instructions for every portal capability.

> **Planned for Phase 2 — PP-F6**
>
> The Partner Documentation Hub is tracked as PP-F6 in the roadmap, depending on PP-F1 (Portal Foundation). See the Delivery Overview for full task details and timeline.