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

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.