Evolving Contacts into an Operational Responsibility and Scope Model for MSP/MSSP Workflows

[fabicarvano]

Evolving Contacts into an Operational Responsibility and Scope Model for MSP/MSSP Workflows
Context
For MSPs and MSSPs, customer contacts are much more than a simple address book.
They often represent important operational responsibilities, such as:

• technical contact;
• billing contact;
• administrative contact;
• local site contact;
• approver;
• device owner or user;
• security or infrastructure contact.
  As the platform evolves, having these contacts structured consistently becomes increasingly important.
  Breeze already has a solid contact foundation today, with functions such as:
• Technical;
• Billing;
• Escalation;
• Administration;
• Local;
• After Hours;
• Customer Portal.
  The proposal is not to replace this model, but to evolve it while preserving the existing contacts, names, and functions.
  Proposal
  The idea would be to organize contacts around three simple concepts:
  Contact
  ↓
  Responsibility
  ↓
  Scope

Examples:
John Smith
→ Responsibility: Technical
→ Scope: Entire organization

Mary Jones
→ Responsibility: Technical
→ Scope: Device Group "Servers"

Robert
→ Responsibility: Local Contact
→ Scope: Rio de Janeiro Site
→ optionally related to specific assets within that site

Susan
→ Responsibility: Approver
→ Scope: Device Group "Critical Servers"

The available scopes could follow the hierarchy Breeze already has:
Organization
↓
Site
↓
Device Group
↓
Specific Device

And, where appropriate, support multiple selections.
Preserve Everything That Already Exists
A key point would be to avoid losing or invalidating any existing contact data.
Existing contacts and functions could simply be redistributed into the new model automatically.
Current example:
John
Function: Technical

Would become:
John
Responsibility: Technical
Scope: Entire organization

Another example:
Jose
Function: Administration

Would become:
Jose
Responsibility: Administration
Scope: Entire organization

In other words, we keep:

• the contact;
• the function name;
• the current meaning;
  and only add the concept of where that responsibility applies.
  The user could then refine the scope later.
  For example:
  Technical
  → Entire organization

could be changed to:
Technical
→ São Paulo Site
→ Servers Device Group

So this would be an additive evolution, not a replacement of the existing model.
Some Existing Functions Could Gain More Context
Local Contact
Today, we only know that a person is "Local".
With the new model, we could know:
Local Contact
→ Rio de Janeiro Site
→ optionally related to specific assets within that site

That makes the information much more useful for an MSP operation.
After Hours
It is also not enough to know that someone is an "After Hours" contact.
Eventually, we need to know:
After Hours
→ for which site
→ for which device group
→ or for which specific assets

The actual scheduling and activation logic can be evolved separately later.
Escalation
Escalation probably deserves its own Escalation Plan concept rather than putting all escalation logic directly into the contact record.
A future escalation plan could define levels such as:
N1
→ N2
→ Management
→ Emergency
→ Crisis

and reference the contacts already registered and structured in the contact model.
Approvers
Approval responsibilities may also need more context.
For example:
Carlos
→ Responsibility: Approver
→ Type: Financial
→ Scope: Entire organization

or:
John
→ Responsibility: Approver
→ Type: Technical
→ Scope: Device Group "Production Servers"

This avoids creating many separate responsibilities such as:

• Technical Approver;
• Financial Approver;
• Administrative Approver.
  Instead, we keep one responsibility:
  Approver

and add the necessary context.
Why This Matters Beyond Contacts
The main benefit is that this could turn the contact model into a reusable operational foundation for other Breeze capabilities.
Escalation Plans
A future escalation plan could use the existing contact data directly:
Incident
→ identify applicable contact
→ N1
→ N2
→ Management
→ Emergency
→ Crisis

Without having to register the same people again in another module.
Playbooks
A playbook could dynamically resolve:
Technical Responsible
Approver
Local Contact
Security Responsible

based on the organization, site, device group, or device involved.
This avoids hard-coding individual names inside automations.
Service Delivery
Existing Service Delivery capabilities could use this structure to understand who is responsible for:

• an organization;
• a site;
• a device group;
• a specific device.
  Future SOPs
  This model could also become a foundation for future operational SOPs.
  For example:
  SOP: Critical Incident

1. Validate the incident
2. Contact the Technical Responsible
3. Request approval from the applicable Approver
4. If there is no response, invoke the Escalation Plan

The SOP would not need to say:
"Call John"

It could say:
"Contact the Technical Responsible"

Breeze would then resolve the correct person using:
Contact

• Responsibility
• Scope

If John leaves the company and Peter takes over, only the contact assignment needs to change.
There would be no need to edit every SOP, playbook, or workflow that depends on that responsibility.
Why This Is Relevant for MSP/MSSP Operations
In an MSP/MSSP operation, knowing:
who is responsible for what

is as important as knowing:
which device belongs to the customer

Breeze already has a strong structure for assets.
It also already has a contact foundation.
The opportunity is to connect those two worlds.
Today:
Customer
├── Contacts
│
└── Infrastructure
├── Sites
├── Device Groups
└── Devices

The evolution would be:
Contact
↓
Responsibility
↓
Scope
↓
Operational Workflows

This could allow multiple future capabilities to reuse the same information instead of each module creating its own way of defining contacts and responsibilities.
Questions for Maintainer Feedback
I would like to understand whether this direction fits the current Breeze model.
Some key questions:

1. Does it make sense to evolve the existing contact functions into a Responsibility + Scope model instead of introducing a separate operational-contact concept?
2. Is Organization → Site → Device Group → Device the appropriate hierarchy for these scopes?
3. Would assigning Entire Organization as the initial scope for existing contact functions be a reasonable way to preserve current behavior?
4. Does it make sense to keep Escalation Plan logic separate and have it consume this structured contact model later?
5. Could this contact structure become a reusable foundation for Playbooks, Service Delivery, approvals, and future SOPs?
   The immediate goal would be relatively simple:
   make the existing contact foundation more structured and operational without breaking or losing any existing contact data.

The long-term benefit would be to create a common operational contact model that multiple parts of Breeze could reuse.

[ToddHebebrand]

Thanks for this, @fabicarvano. The direction fits, and more of it is already in place than the proposal assumes, so most of my notes are about anchoring it to what's on main.

What exists today: contacts are first-class rows in contacts (apps/api/src/db/schema/contacts.ts), org-scoped, with an optional site_id pin enforced by a composite same-org FK. The functions you listed are the roles text[] column, validated against CONTACT_ROLES (apps/api/src/services/contacts/types.ts: billing, technical, escalation, admin, site, after_hours, portal). "Local" in the UI is the site role. The original design already names your next step: docs/superpowers/specs/onboarding-signup/2026-08-09-organization-contacts-design.md (around line 278) defers a contact_roles(contact_id, org_id, role, is_primary) child table, populated by unnest(roles), until something needs it. A scoped responsibility is that child table plus a scope. So on Q1: yes, evolve contacts rather than adding a separate operational-contact concept.

Who reads roles today. Each of these needs a defined meaning once roles carry a scope:

• Caller verification: requesterAuthorized (apps/api/src/services/callerVerification/access.ts) only lets an org-level, site-less contact holding an authorizer role approve a disable_user. That's a security gate. A site- or group-scoped admin must never become an authorizer, so the spec should state that this consumer reads org-scope rows only.
• Report series recipients match on roles (apps/api/src/services/reportSeries/recipients.ts).
• Account readiness counts an org-level billing contact (apps/api/src/services/orgAccountReadiness.ts), and the billing compatibility projection reads the billing role (apps/api/src/services/contacts/compat.ts).
• Portal login linking reads roles (apps/api/src/services/contacts/loginLink.ts).

On your questions:

Q2, hierarchy: org, site and device group, yes, with one caveat. It isn't a strict tree: device_groups.site_id is nullable (apps/api/src/db/schema/devices.ts), and dynamic groups change membership over time. So the spec needs a resolution rule for when a device matches an org row, a site row and a group row for the same responsibility. I'd say most specific wins (group, then site, then org), returning every match at that level. Multiple selections are just multiple rows.

Leave device-level scope out of v1. Real devices have no contact link today. The only ones are manual_assets.assigned_contact_id and the OS-reported devices.last_user string. #5905 proposes devices.primary_contact_id for "who uses this machine", which is a different relationship from "who is responsible for it". Let that land on its own first.

Q3, migration: org scope is right for site-less contacts only. A contact with site_id set already means "this person, at this site", so its roles should migrate as site-scoped. Otherwise the backfill quietly widens every site contact to the whole org, which is exactly the caller-verification problem above.

Q4, escalation: agreed, keep it off the contact record. Note that there's already an escalation model: escalation_policies (apps/api/src/db/schema/alerts.ts), partner- or org-owned, whose steps target notification channels and staff users (apps/api/src/services/delivery/escalationExecution.ts). A future "notify the customer's after-hours contact" step should extend that rather than add a second Escalation Plan concept. That's a later spec.

Q5, reuse: yes, that's the reason to do it. The operator recipe library already treats contacts as task targets (docs/superpowers/specs/ai-mcp/2026-09-17-operator-recipe-library-design.md), so "resolve the technical contact for this device" is a natural input there later.

What I'd change:

• Hold Approver for now. Roles get added when something reads them. The customer approval gate in Customer approval step for work exceeding budget/estimate or after-hours #4617 is still in design, and that spec is the place to add approver and its type.
• Name a v1 consumer. A scope model nothing reads is easy to get subtly wrong. My suggestion: a read-only "who to contact" panel on the device and site pages, driven by the resolver, plus scope-aware matching for report-series recipients. Both are low risk and exercise the resolution rule.
• One place to edit. Responsibilities are edited in the org record's Contacts card (apps/web/src/components/organizations/record/OrganizationRecordPage.tsx). Site, group and device pages can show the resolved result read-only, but shouldn't grow a second editor.
• One source of truth. Once contact_roles exists it owns roles. Keep contacts.roles as a projection the service updates in the same transaction, the way services/contacts/compat.ts keeps the legacy billing and site jsonb in sync, and move readers over gradually. CSV import, the API and the AI tools all write roles today, so the spec should name each writer.

Tenancy notes for the spec:

• This is customer data, not config, so partner-wide-first doesn't apply (the reasoning is in the header comment of contacts.ts).
• The new table is shape 1 with org_id NOT NULL: one row per contact, role and scope target.
• Use typed nullable site_id and device_group_id columns with a CHECK that at most one is set, rather than an id array or jsonb. Arrays can't carry FKs, and jsonb is excluded from tenant export.
• Make each reference a composite (x, org_id) FK, DEFERRABLE INITIALLY IMMEDIATE.
• Say what deleting a site or group does to a scoped responsibility, since a silent cascade would drop it.
• RLS policies go in the migration that creates the table, plus entries in the org cascade order, the org merge registry and the export policy registry.

Next step: if you want to take it on, write it up as a spec PR under docs/superpowers/specs/onboarding-signup/, next to the original contacts design. Cover the table, the backfill, the resolution rule, what each existing consumer does with scope, and the v1 consumer, and we'll review it there.

Status: good fit; spec PR next.