Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(m4): add core data actors with two example scenarios

Browse Source
This commit is contained in:
zouantchaw
2026-02-25 10:58:25 -05:00
parent b2833b02af
commit 3dc3b306ea
1 changed files with 82 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
docs/MILESTONES/M4/planning/m4-core-data-actors-scenarios.md Normal file
View File

@@ -0,0 +1,82 @@
# 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. `Vendor`: supplier account that can fulfill staffing demand.
6. `Workforce/Staff`: worker profile used for assignment and attendance.
7. `StakeholderType`: typed category (`buyer`, `operator`, `vendor_partner`, `workforce`, `partner`).
8. `StakeholderProfile`: typed actor record inside a tenant.
9. `StakeholderLink`: relationship between stakeholder profiles.
## 2) Minimal actor map
```mermaid
flowchart LR
T["Tenant"] --> TM["TenantMembership"]
U["User"] --> TM
T --> B["Business"]
T --> V["Vendor"]
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.
```mermaid
sequenceDiagram
participant Tenant as "Tenant (Legendary)"
participant Biz as "Business (Google Cafes)"
participant Ops as "User + TenantMembership (Ops Lead)"
participant Staff as "Workforce/Staff (Barista Ana)"
participant Link as "StakeholderLink"
Biz->>Ops: "Create staffing request"
Ops->>Tenant: "Create order under tenant scope"
Ops->>Link: "Resolve business-to-vendor/workforce relationships"
Ops->>Staff: "Assign qualified worker"
Staff-->>Ops: "Clock in/out and complete shift"
Ops-->>Biz: "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.
```mermaid
sequenceDiagram
participant Tenant as "Tenant (Peakline Events)"
participant Biz as "Business (NVIDIA Dining)"
participant Ops as "User + TenantMembership (Coordinator)"
participant Vendor as "Vendor (Metro Staffing)"
participant Staff as "Workforce/Staff (Vendor worker)"
Biz->>Ops: "Request recurring event staffing"
Ops->>Tenant: "Create recurring order"
Ops->>Vendor: "Dispatch required roles"
Vendor->>Staff: "Provide available workers"
Staff-->>Ops: "Attendance and completion events"
Ops-->>Biz: "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. Multi-tenant isolation stays strict because all critical records resolve through `Tenant`.
3. Legendary and non-Legendary operating models both fit the same structure.