# M4 Core Data Actors and Example Scenarios

Status: Working draft  
Date: 2026-02-25  
Owner: Technical Lead

## 1) Core data actors
1. `Tenant`: staffing company boundary and data isolation root.
2. `User`: human identity that signs in.
3. `TenantMembership`: user role/context inside one tenant.
4. `Business`: client account served by the tenant.
5. `BusinessMembership`: maps users to a business with role/status (`owner`, `manager`, `approver`, `viewer`).
6. `Vendor`: supplier account that can fulfill staffing demand.
7. `VendorMembership`: maps users to a vendor with role/status (`owner`, `manager`, `scheduler`, `viewer`).
8. `Workforce/Staff`: worker profile used for assignment and attendance.
9. `StakeholderType`: typed category (`buyer`, `operator`, `vendor_partner`, `workforce`, `partner`, `procurement_partner`).
10. `StakeholderProfile`: typed actor record inside a tenant.
11. `StakeholderLink`: relationship between stakeholder profiles.

## 1.1 Current schema coverage (today)
Current Data Connect handles this only partially:
1. `Business.userId` supports one primary business user.
2. `Vendor.userId` supports one primary vendor user.
3. `TeamMember` can represent multiple users by team as a workaround.

This is why we need first-class membership tables:
1. `business_memberships`
2. `vendor_memberships`

Without those, client/vendor user partitioning is indirect and harder to enforce safely at scale.

## 2) Minimal actor map

```mermaid
flowchart LR
  T["Tenant"] --> TM["TenantMembership (global tenant access)"]
  U["User"] --> TM
  T --> B["Business"]
  T --> V["Vendor"]
  U --> BM["BusinessMembership"]
  BM --> B
  U --> VM["VendorMembership"]
  VM --> V
  U --> S["Workforce/Staff"]
  T --> SP["StakeholderProfile"]
  ST["StakeholderType"] --> SP
  SP --> SL["StakeholderLink"]
  B --> O["Orders/Shifts"]
  V --> O
  S --> O
```

## 3) Scenario A: Legendary Event Staffing
Context:
1. Tenant is `Legendary Event Staffing and Entertainment`.
2. Business is `Google Mountain View Cafes`.
3. Legendary uses its own workforce, and can still route overflow to approved vendors.

Actor mapping (text):
1. Tenant: `Legendary Event Staffing and Entertainment` (the company using KROW).
2. User: `Wil` (ops lead), `Maria` (Google client manager), `Omar` (Google procurement approver), `Jose` (vendor scheduler), `Ana` (worker).
3. TenantMembership:
4. `Wil` is `admin` in Legendary tenant.
5. `Maria` is `member` in Legendary tenant.
6. `Omar` is `member` in Legendary tenant.
7. `Jose` is `member` in Legendary tenant.
8. `Ana` is `member` in Legendary tenant.
9. BusinessMembership:
10. `Maria` is `manager` in `Google Mountain View Cafes`.
11. `Omar` is `approver` in `Google Mountain View Cafes`.
12. VendorMembership:
13. `Jose` is `scheduler` in `Legendary Staffing Pool A`.
14. `Wil` is `owner` in `Legendary Staffing Pool A`.
15. Business: `Google Mountain View Cafes` (client account under the tenant).
16. Vendor: `Legendary Staffing Pool A` (or an external approved vendor).
17. Workforce/Staff: `Ana` is a staff profile in workforce, linked to certifications and assignments.
18. StakeholderType: `buyer`, `operator`, `vendor_partner`, `workforce`, `procurement_partner`.
19. StakeholderProfile:
20. `Google Procurement` = `buyer`.
21. `Legendary Ops` = `operator`.
22. `FoodBuy` = `procurement_partner`.
23. StakeholderLink:
24. `Google Procurement` `contracts_with` `Legendary Ops`.
25. `Legendary Ops` `sources_from` `Legendary Staffing Pool A`.
26. `Google Procurement` `reports_through` `FoodBuy`.

```mermaid
sequenceDiagram
  participant Tenant as "Tenant (Legendary)"
  participant BizUser as "Business user (Maria/Omar)"
  participant Ops as "Ops user (Wil)"
  participant VendorUser as "Vendor user (Jose)"
  participant Staff as "Workforce/Staff (Barista Ana)"
  participant StakeRel as "StakeholderLink"

  BizUser->>Ops: "Create staffing request"
  Ops->>Tenant: "Create order under tenant scope"
  Ops->>StakeRel: "Resolve business-to-vendor/workforce relationships"
  Ops->>VendorUser: "Dispatch role demand"
  VendorUser->>Staff: "Confirm worker assignment"
  Staff-->>Ops: "Clock in/out and complete shift"
  Ops-->>BizUser: "Invoice/report generated with audit trail"
```

## 4) Scenario B: Another tenant (external vendor-heavy)
Context:
1. Tenant is `Peakline Events`.
2. Business is `NVIDIA Campus Dining`.
3. Peakline primarily fulfills demand through external approved vendors.

Actor mapping (text):
1. Tenant: `Peakline Events` (another staffing company using KROW).
2. User: `Chris` (operations coordinator), `Nina` (client manager), `Sam` (vendor manager), `Leo` (worker).
3. TenantMembership:
4. `Chris` is `admin` in Peakline tenant.
5. `Nina` is `member` in Peakline tenant.
6. `Sam` is `member` in Peakline tenant.
7. `Leo` is `member` in Peakline tenant.
8. BusinessMembership:
9. `Nina` is `manager` in `NVIDIA Campus Dining`.
10. VendorMembership:
11. `Sam` is `manager` in `Metro Staffing LLC`.
12. Business: `NVIDIA Campus Dining` (client account under the tenant).
13. Vendor: `Metro Staffing LLC` (approved external vendor for this tenant).
14. Workforce/Staff: `Leo` is a workforce profile fulfilled through Metro Staffing for assignment and attendance.
15. StakeholderType: `buyer`, `operator`, `vendor_partner`, `workforce`, `procurement_partner`.
16. StakeholderProfile:
17. `NVIDIA Procurement` = `buyer`.
18. `Peakline Ops` = `operator`.
19. `FoodBuy Regional` = `procurement_partner`.
20. StakeholderLink:
21. `NVIDIA Procurement` `contracts_with` `Peakline Ops`.
22. `Peakline Ops` `sources_from` `Metro Staffing LLC`.
23. `NVIDIA Procurement` `reports_through` `FoodBuy Regional`.

```mermaid
sequenceDiagram
  participant Tenant as "Tenant (Peakline Events)"
  participant BizUser as "Business user (Nina)"
  participant Ops as "Ops user (Chris)"
  participant VendorUser as "Vendor user (Sam)"
  participant Staff as "Workforce/Staff (Vendor worker)"

  BizUser->>Ops: "Request recurring event staffing"
  Ops->>Tenant: "Create recurring order"
  Ops->>VendorUser: "Dispatch required roles"
  VendorUser->>Staff: "Provide available workers"
  Staff-->>Ops: "Attendance and completion events"
  Ops-->>BizUser: "Settlement + performance reports"
```

## 5) Why this model scales
1. New stakeholders can be added through `StakeholderType` and `StakeholderProfile` without changing core order/shift tables.
2. Business and vendor user partitioning is explicit through membership tables, not hidden in one owner field.
3. Multi-tenant isolation stays strict because all critical records resolve through `Tenant`.
4. Legendary and non-Legendary operating models both fit the same structure.

## 6) Industry alignment (primary references)
1. Google Cloud Identity Platform multi-tenancy:
- https://docs.cloud.google.com/identity-platform/docs/multi-tenancy
2. AWS SaaS tenant isolation fundamentals:
- https://docs.aws.amazon.com/whitepapers/latest/saas-architecture-fundamentals/tenant-isolation.html
3. B2B organization-aware login flows (Auth0 Organizations):
- https://auth0.com/docs/manage-users/organizations/login-flows-for-organizations
4. Supplier-side multi-user management patterns (Coupa Supplier Portal):
- https://compass.coupa.com/en-us/products/product-documentation/supplier-resources/for-suppliers/coupa-supplier-portal/set-up-the-csp/users/manage-users
