---
title: "Staff Ratio Intelligence"
slug: staff-ratio-intelligence
section: Placement & Matching
status: stable
description: "Real-time, site-level visibility into the balance between active host staff / supervisors and placed participants — with automated operational signals when a safe ratio limit is breached"
last-updated: 2026-10-07
---

# Staff Ratio Intelligence

Real-time, site-level visibility into the balance between active host staff / supervisors and placed participants — with automated operational signals when a safe ratio limit is breached

> **Intelligence, Not Control**
>
> This engine never blocks a placement, throttles intake, or alters the placement flow. It computes the active staff-to-participant ratio per host and raises threshold-based flags when configurable limits are crossed, so teams can act before a site becomes dangerously understaffed. Hard enforcement (blocking a placement that would breach a ratio) is explicitly out of scope — see Enforcement (Future Option).

> **Related Pages**
>
> This is the supervision-ratio sibling of Workforce Capacity Intelligence (which measures position demand vs. applicant supply, not staffing ratios). Both are observational engines that publish signals; neither enforces. For volume controls that do enforce limits, see Quota Model & Capacity Controls . Participant counts originate from confirmed placements ; staff counts originate from host supervisor contacts .

## What It Does

The Staff-to-Participant Ratio Intelligence Engine gives sponsor compliance and operations teams forward-looking, site-level visibility into how well each host is staffed relative to the participants placed there. It sits within the Season / Operational Intelligence layer of Globus, alongside Workforce Capacity Intelligence.

Calculates the real-time staff-to-participant ratio per host, scoped by site, program, and season / Detects ratio breaches using configurable, database-driven threshold rules / Automatically publishes a structured STAFF_RATIO_BREACH_DETECTED, STAFF_RATIO_BREACH_ESCALATED or STAFF_RATIO_BREACH_RESOLVED event when a breach is detected, worsens or clears / Surfaces understaffing signals in dashboards and executive reporting / Maintains a complete audit trail of every ratio-breach lifecycle
## What It Does Not Do

> **Explicit Boundaries**
>
> The Ratio Intelligence Engine is not a control mechanism. It is an intelligence layer.

By default does not block a placement (an optional per-rule enforcePlacementBlock flag, off by default, rejects a placement that would reach critical with 422 STAFF_RATIO_CRITICAL) / Does not throttle intake or recruitment / Does not auto-assign or hire staff on the host's behalf / Does not measure position demand vs. applicant supply (that is Workforce Capacity Intelligence) / Does not enforce quota limits (that is the Quota Model)
## Core Concepts

### Staff / Supervisor Supply

The number of active staff / supervisor contacts a host has on record for a given scope. Only contacts flagged active and carrying a supervising role count toward supply. Supply is scoped by:

Host / Site / Program / Season
Derived from: partner_contacts (contact_type = supervisor).

### Placed Participant Count

The number of participants currently placed at the host for the same scope. Every placement except cancelled and withdrawn ones counts (status NOT IN cancelled, withdrawn).

Derived from: placements (status not cancelled or withdrawn).

> **Why placements, not job-order positions**
>
> This engine measures supervision load against real people on-site, so it counts confirmed placements, not reserved or open positions. The position-side demand/supply math (positions vs. placement-ready applicants) belongs to Workforce Capacity Intelligence → Capacity Gap . The two engines read different sources and answer different questions.

### The Ratio

Ratio = Active Staff ÷ Placed Participants

Surfaced for humans as participants-per-staff (e.g. a ratio of 0.125 displays as 8:1). Threshold rules are expressed as a maximum number of participants per staff member.

value
## Threshold Rules

Thresholds are database-driven and scopeable per brand, program, or host — never hardcoded constants. Rules are stored in staff_ratio_rules and evaluated by the Rules Engine , mirroring the capacity_gap_rules pattern. The narrowest matching scope wins (host overrides program overrides brand overrides global).

| Rule | Condition | Severity |
| --- | --- | --- |
| scenario | condition | |

_(row above is a template, repeated for each data row)_

## Auto-Publish Events

When a threshold is crossed, Globus automatically publishes a structured event into the Event Outbox. No human clicking refresh. No manual dashboard monitoring.

> **Auto-Publish Is a Signal, Not an Action**
>
> Auto-publish creates awareness and structured action. It does not block any placement, does not alter intake, and does not modify placement state. It broadcasts an operational signal into the system.

Example Event Payload

eventType / STAFF_RATIO_BREACH_DETECTED / host / Lakeside Camp Co. / site / Lakeside Camp / program / Camp Counselor / season / 2026 / staff / participants / ratio / 14:1 / threshold / 12:1 / severity / HIGH
### Event Lifecycle

Ratio-breach events follow a structured lifecycle. The system avoids duplicate alerts by tracking the state of each open breach record — directly mirroring the CAPACITY_IMBALANCE sub-state model.

### Event Handling

Because Globus already uses an event outbox + worker pattern, published events are processed cleanly by downstream consumers. The n8n Automation Layer handles most notification routing.

## Processing Flow

The engine recalculates on every relevant data change. The full processing sequence:

> **No Blocking, No Throttling**
>
> This flow is purely observational. It publishes intelligence. It does not gate or delay any placement, applicant, or host action.

## Dashboard Signals

### Staffing Ratio Panel

Each host displays a site-level staffing ratio panel showing real-time staff, participants, and ratio:

| Site | Staff | Participants | Ratio | Status |
| --- | --- | --- | --- | --- |
| site | staff | participants | ratio | |

_(row above is a template, repeated for each data row)_

### Executive View

Executive dashboards surface aggregated ratio data across the entire sponsor portfolio:

## Lifecycle Management

Each breach is tracked as a lifecycle entity. The system avoids alert fatigue through structured state management.

Breach Record Fields

Avoid duplicate event publishing (idempotent) / Publish escalation only if severity increases / Publish resolution event when ratio returns to within range / Version each state change with timestamp
## Data Model

The engine relies on four primary data structures. Two are existing source entities (placements and host supervisor contacts); two are new (the computed snapshot view and the threshold-rule table). All scoping references the shared system_lookups taxonomy to keep host / site / program / season identifiers consistent.

name
## Audit Vocabulary

A new scoped staff_ratio.* action family is appended to the Audit Logging Contract and rendered in the real-time Audit Console. Every breach lifecycle transition and every rule change writes through recordAudit() after the success response, consistent with the existing dotted-and-scoped vocabulary.

| Action | Entity type | When it fires |
| --- | --- | --- |
| a | e | w |

_(row above is a template, repeated for each data row)_

## Permissions (RBAC)

Access to staff-ratio intelligence follows the RBAC model .

View Access

Program Managers / Operations / Executive / Compliance
Rule Modification

Requires staff_ratio.rules.manage permission

Supervisor Contact Modification

Requires partners.manage permission

**API key scope.** The `/api/staff-ratio/*` routes also accept an API key. The scope `staff_ratio.read` maps to the permissions `staff_ratio.view`, `staff_ratio.rules.manage` and `staff_ratio.adjust`. The four `GET` routes (`balance`, `rules`, `snapshots`, `breaches`) accept that scope and need `staff_ratio.view`; rule create, update and delete accept `staff_ratio.read` or `admin.write` and need `staff_ratio.rules.manage`; `POST /api/staff-ratio/recalculate` accepts the same scopes and needs `staff_ratio.adjust`.

## Design Principles

## Enforcement (Future Option)

> **Enforcement is explicitly out of scope**
>
> This engine is observational by design. Hard-blocking a placement that would breach a ratio is not part of this surface and must not be implied by any consumer of its signals. A future enforcement option could, if a sponsor opts in, gate the placement-confirm path on a critical ratio — but that would be a separate control surface (analogous to the difference between Workforce Intelligence and the Quota Model enforcement ), owned by the placement runtime, and would need its own spec, RBAC, and override path.

## Strategic Impact

The Staff-to-Participant Ratio Intelligence Engine extends Globus from a record-keeping ERP into an operational intelligence platform for participant supervision and duty-of-care.

> **Sponsor Intelligence, Not CRM Reporting**
>
> This aligns directly with the layered architecture, event outbox model, zero-hardcode philosophy, season-based program model, and multi-brand sponsor structure. Visibility before understaffing becomes a crisis — not controls that frustrate teams.