Krow-workspace/docs/MILESTONES/M4/planning/m4-roadmap-csv-schema-reconciliation.md

# M4 Roadmap CSV Schema Reconciliation

Status: Draft for implementation alignment  
Date: 2026-02-25  
Owner: Technical Lead

## 1) Why this exists
We reviewed the original product-roadmap exports to confirm that the target schema can support all stakeholder lanes as the platform grows.

This avoids two failure modes:
1. Building command APIs on top of a schema that cannot represent required workflows.
2. Hard-coding today's customer setup in a way that blocks future staffing companies.

## 2) Inputs reviewed
All 13 roadmap exports from `/Users/wiel/Downloads`:
1. `KROW App – Roadmap - Business App_ Google, Nvidia.csv`
2. `KROW App – Roadmap - Client_ Google, Nvidia.csv`
3. `KROW App – Roadmap - Compass- The Operator.csv`
4. `KROW App – Roadmap - Employee App.csv`
5. `KROW App – Roadmap - Features.csv`
6. `KROW App – Roadmap - FoodBuy- Procurement.csv`
7. `KROW App – Roadmap - KROW Dashboard.csv`
8. `KROW App – Roadmap - Offenses.csv`
9. `KROW App – Roadmap - Partner.csv`
10. `KROW App – Roadmap - Roadmap.csv`
11. `KROW App – Roadmap - Sectors_ BA, Flik ( The executors).csv`
12. `KROW App – Roadmap - The Workforce_ Employees.csv`
13. `KROW App – Roadmap - Vendor_ Legendary (Staffing).csv`

Parsed signal:
1. 983 non-empty task lines.
2. 1,263 planning rows with task/status/priority/reference signals.

## 3) What the roadmap is clearly asking for
Cross-file recurring capabilities:
1. Multi-party org model: client, operator, vendor, procurement, workforce, partner, sector execution.
2. Orders and shift operations: recurring events, assignment, coverage, schedule management.
3. Attendance and policy enforcement: clock-in/out, no-show, tardiness, cancellation, offense ladders.
4. Compliance and document verification: certifications, insurance, legal docs, renewals, risk alerts.
5. Finance and settlement: invoice lifecycle, disputes, remittance, payment history, aging, payroll/earnings.
6. Reporting and prediction: dashboards, KPI, forecasting, scenario planning.

Repeated examples across many sheets:
1. `Vendor Onboarding`, `Service Locations`, `Compliance`, `Certifications`.
2. `All Invoices (Open/Pending/Overdue/Paid...)`, `Payment Summary`, `Remittance Advice Download`.
3. Offense progression rules in `Offenses.csv` and `Employee App.csv` (warning -> suspension -> disable/block).

## 4) Stakeholder capability matrix (from roadmap exports)

| Stakeholder lane | Org network | Orders and shifts | Attendance and offense | Compliance docs | Finance | Reporting |
|---|---|---|---|---|---|---|
| Client (Google, Nvidia) | Yes | Yes | Partial (visibility) | Yes | Yes | Yes |
| Vendor (Legendary) | Yes | Yes | Yes | Yes | Yes | Yes |
| Workforce (Employee app) | Limited | Yes | Yes | Yes | Earnings focus | Limited |
| Operator (Compass) | Yes | Yes | KPI visibility | Yes | Yes | Yes |
| Procurement (FoodBuy) | Yes | KPI/SLA focus | KPI/SLA focus | Yes | Yes | Yes |
| KROW Dashboard | Cross-entity | Cross-entity | Cross-entity risk | Cross-entity | Cross-entity | Heavy |
| Partner | Basic | Basic | Minimal | Yes | Basic | Basic |

Implication:
1. This is a multi-tenant, multi-party workflow platform, not a single-role CRUD app.
2. Schema must separate party identity, party relationships, and role-based permissions from workflow records.

## 5) Reconciliation against current Data Connect schema

What already exists and is useful:
1. Core scheduling entities: `orders`, `shifts`, `shift_roles`, `applications`, `assignments`.
2. Workforce entities: `staffs`, `workforce`, `staff_roles`.
3. Financial entities: `invoices`, `recent_payments`, `vendor_rates`.
4. Compliance entities: `documents`, `staff_documents`, `certificates`.

Current structural gaps for roadmap scale:
1. No tenant boundary key on core tables (`tenant_id` missing).
2. No first-class business user partitioning table (`business_memberships` missing).
3. No first-class vendor user partitioning table (`vendor_memberships` missing).
4. No first-class stakeholder profile/link model for buyer/operator/partner/sector relationships.
5. Attendance history is not first-class (check in/out only inside `applications`).
6. No offense policy, offense event, or enforcement action tables.
7. Finance is coarse (invoice + recent payment), missing line items, payment runs, remittance artifact model.
8. Sensitive bank fields are currently modeled directly in `accounts` (`accountNumber`, `routeNumber`).
9. Many core workflow fields are JSON (`orders.assignedStaff`, `orders.shifts`, `shift.managers`, `assignment.managers`).
10. Money still uses float in critical tables.

Connector boundary gap:
1. 147 Data Connect mutation operations exist.
2. 36 of those are high-risk core workflow mutations (`order`, `shift`, `shiftRole`, `application`, `assignment`, `invoice`, `vendor`, `business`, `workForce`, `teamMember`, `account`).

## 6) Target schema additions required before full command rollout

### 6.1 Tenant and stakeholder graph
1. `tenants`
2. `tenant_memberships`
3. `business_memberships`
4. `vendor_memberships`
5. `stakeholder_types`
6. `stakeholder_profiles`
7. `stakeholder_links`
8. `role_bindings` (scoped to tenant/team/hub/business/vendor/resource)

### 6.2 Attendance and timesheet reliability
1. `attendance_events` (append-only clock-in/out/NFC/manual-corrected)
2. `attendance_sessions` (derived per shift role assignment)
3. `timesheets` (approval state and pay-eligible snapshot)
4. `timesheet_adjustments` (manual corrections with audit reason)

### 6.3 Offense and policy enforcement
1. `offense_policies` (per tenant or per business)
2. `offense_rules` (threshold and consequence ladder)
3. `offense_events` (who, what, when, evidence)
4. `enforcement_actions` (warning, suspension, disable, block-from-client)

### 6.4 Compliance and verification
1. `verification_jobs`
2. `verification_reviews`
3. `verification_events`
4. `compliance_requirements` (per role, tenant, business, or client contract)

### 6.5 Finance completeness
1. `invoice_line_items`
2. `invoice_status_history`
3. `payment_runs`
4. `payment_allocations`
5. `remittance_documents`
6. `account_token_refs` (tokenized provider refs, no raw account/routing)

## 7) Minimal target relationship view

```mermaid
erDiagram
  TENANT ||--o{ TENANT_MEMBERSHIP : has
  BUSINESS ||--o{ BUSINESS_MEMBERSHIP : has
  VENDOR ||--o{ VENDOR_MEMBERSHIP : has
  USER ||--o{ BUSINESS_MEMBERSHIP : belongs_to
  USER ||--o{ VENDOR_MEMBERSHIP : belongs_to
  TENANT ||--o{ STAKEHOLDER_PROFILE : has
  STAKEHOLDER_PROFILE ||--o{ STAKEHOLDER_LINK : links_to

  TENANT ||--o{ BUSINESS : owns
  TENANT ||--o{ VENDOR : owns
  BUSINESS ||--o{ ORDER : requests
  VENDOR ||--o{ ORDER : fulfills
  ORDER ||--o{ SHIFT : expands_to
  SHIFT ||--o{ SHIFT_ROLE : requires
  SHIFT_ROLE ||--o{ APPLICATION : receives
  APPLICATION ||--o{ ASSIGNMENT : becomes

  ASSIGNMENT ||--o{ ATTENDANCE_EVENT : emits
  ASSIGNMENT ||--o{ TIMESHEET : settles
  OFFENSE_POLICY ||--o{ OFFENSE_RULE : defines
  ASSIGNMENT ||--o{ OFFENSE_EVENT : may_trigger
  OFFENSE_EVENT ||--o{ ENFORCEMENT_ACTION : causes

  ORDER ||--o{ INVOICE : bills
  INVOICE ||--o{ INVOICE_LINE_ITEM : contains
  PAYMENT_RUN ||--o{ PAYMENT_ALLOCATION : allocates
  INVOICE ||--o{ PAYMENT_ALLOCATION : receives
  PAYMENT_RUN ||--o{ REMITTANCE_DOCUMENT : publishes
```

## 8) First-principles rules we should lock now
1. Every command-critical table includes `tenant_id`.
2. High-risk writes go through command APIs only.
3. Money uses exact numeric type (or integer cents), never float.
4. Core workflow state is relational and constrained, not JSON blobs.
5. Every irreversible state change has append-only audit event rows.

## 9) Decision
This roadmap evidence supports continuing with the target architecture direction (command boundary + multi-tenant schema), but we should add attendance/offense/settlement/stakeholder-graph tables before full command rollout on mission-critical flows.