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

docs(m4): reconcile roadmap CSVs with target schema

Browse Source
This commit is contained in:
zouantchaw
2026-02-25 10:50:13 -05:00
parent f4f002b41b
commit b2833b02af
3 changed files with 256 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGELOG.md
View File

@@ -21,3 +21,6 @@
| 2026-02-24 | 0.1.16 | Added M4 target schema blueprint doc with first-principles modular model, constraints, and migration phases. |
| 2026-02-24 | 0.1.17 | Added full current-schema mermaid model relationship map to the M4 target schema blueprint. |
| 2026-02-24 | 0.1.18 | Updated schema blueprint with explicit multi-tenant stakeholder model and phased RBAC rollout with shadow mode before enforcement. |
| 2026-02-24 | 0.1.19 | Added customer stakeholder-wheel mapping and future stakeholder extension model to the M4 schema blueprint. |
| 2026-02-25 | 0.1.20 | Added roadmap CSV schema-reconciliation document with stakeholder capability matrix and concrete schema gap analysis. |
| 2026-02-25 | 0.1.21 | Updated target schema blueprint with roadmap-evidence section plus attendance/offense, stakeholder-network, and settlement-table coverage. |

160
docs/MILESTONES/M4/planning/m4-roadmap-csv-schema-reconciliation.md Normal file
View File

@@ -0,0 +1,160 @@
# 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 stakeholder profile/link model for buyer/operator/partner/sector relationships.
3. Attendance history is not first-class (check in/out only inside `applications`).
4. No offense policy, offense event, or enforcement action tables.
5. Finance is coarse (invoice + recent payment), missing line items, payment runs, remittance artifact model.
6. Sensitive bank fields are currently modeled directly in `accounts` (`accountNumber`, `routeNumber`).
7. Many core workflow fields are JSON (`orders.assignedStaff`, `orders.shifts`, `shift.managers`, `assignment.managers`).
8. 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. `stakeholder_types`
4. `stakeholder_profiles`
5. `stakeholder_links`
6. `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
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.

96
docs/MILESTONES/M4/planning/m4-target-schema-blueprint.md
View File

@@ -1,7 +1,7 @@
# M4 Target Schema Blueprint (Command-Ready)
Status: Draft for team alignment
Date: 2026-02-24
Date: 2026-02-25
Owner: Technical Lead
## 1) Goal
@@ -36,6 +36,49 @@ flowchart LR
V --> O
```
## 1.2 Stakeholder wheel mapping (current baseline)
The stakeholder labels from the customer workshop map to schema as follows:
1. Buyer (Procurements):
- Buyer users inside a business/client account.
- Schema anchor: `users` + `tenant_memberships` + `team_members` (procurement team scope).
2. Enterprises (Operator):
- Tenant operator/admin users running staffing operations.
- Schema anchor: `tenants`, `team_members`, command-side permissions.
3. Sectors (Execution):
- Operational segments or business units executing events.
- Schema anchor: `teams`, `team_hubs`, `team_hud_departments`, `roles`.
4. Approved Vendor:
- Supplier companies approved to fulfill staffing demand.
- Schema anchor: `vendors`, `workforce`, `vendor_rates`, `vendor_benefit_plans`.
5. Workforce:
- Individual workers/staff and their assignments.
- Schema anchor: `staffs`, `staff_roles`, `applications`, `assignments`, `certificates`, `staff_documents`.
6. Partner:
- External integration or service partner (future).
- Schema anchor: `stakeholder_profiles` extension path + scoped role bindings.
Rule:
1. Start with baseline stakeholders above.
2. Add new stakeholders via extension tables and role bindings, not by changing core scheduling and finance tables.
## 1.3 Future stakeholder expansion model
To add stakeholders later without breaking core schema:
1. Add `stakeholder_types` (registry).
2. Add `stakeholder_profiles` (`tenant_id`, `type`, `status`, `metadata`).
3. Add `stakeholder_links` (relationship graph across stakeholders).
4. Bind permissions through `role_bindings` with scope (`tenant`, `team`, `hub`, `business`, or specific resource).
## 1.4 Roadmap CSV evidence snapshot
Evidence source:
1. `docs/MILESTONES/M4/planning/m4-roadmap-csv-schema-reconciliation.md`
What the exports confirmed:
1. The product is multi-party and multi-tenant by design (client, operator, vendor, workforce, procurement, partner, dashboard).
2. Attendance and offense enforcement are core business workflows, not side features.
3. Finance requires more than invoices (payment runs, remittance, status history, dispute/audit trace).
4. Compliance requires asynchronous verification and requirement templates by tenant/business/role.
## 2) First-principles rules
1. Every critical write must be server-mediated and transactional.
2. Tenant boundaries must be explicit in data and queries.
@@ -171,6 +214,33 @@ Rules:
1. Every command write emits a domain event.
2. Idempotency scope: `(actor_uid, route, idempotency_key)`.
## 4.9 Attendance, Timesheets, and Offense Governance
Tables:
1. `attendance_events` (append-only: clock-in/out, source, correction metadata)
2. `attendance_sessions` (derived work session per assignment)
3. `timesheets` (approval-ready payroll snapshot)
4. `timesheet_adjustments` (manual edits with reason and actor)
5. `offense_policies` (tenant/business scoped policy set)
6. `offense_rules` (threshold ladder and consequence)
7. `offense_events` (actual violation events)
8. `enforcement_actions` (warning, suspension, disable, block)
Rules:
1. Attendance corrections are additive events, not destructive overwrites.
2. Offense consequences are computed from policy + history and persisted as explicit actions.
3. Manual overrides require actor, reason, and timestamp in audit trail.
## 4.10 Stakeholder Network Extensibility
Tables:
1. `stakeholder_types` (buyer, operator, vendor, workforce, partner, future types)
2. `stakeholder_profiles` (tenant-scoped typed profile)
3. `stakeholder_links` (explicit relationship graph between profiles)
Rules:
1. New stakeholder categories are added by data, not by schema rewrites to core workflow tables.
2. Permission scope resolves through role bindings plus stakeholder links where needed.
3. Scheduling and finance records remain stable while stakeholder topology evolves.
## 5) Target core model (conceptual)
```mermaid
@@ -196,6 +266,11 @@ erDiagram
STAFF ||--o{ APPLICATION : applies
SHIFT_ROLE ||--o{ ASSIGNMENT : allocates
WORKFORCE ||--o{ ASSIGNMENT : executes
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
STAFF ||--o{ CERTIFICATE : has
STAFF ||--o{ STAFF_DOCUMENT : uploads
@@ -207,10 +282,16 @@ erDiagram
ORDER ||--o{ INVOICE : billed_by
INVOICE ||--o{ RECENT_PAYMENT : settles
TENANT ||--o{ ACCOUNT_TOKEN_REF : payout_method
INVOICE ||--o{ INVOICE_LINE_ITEM : details
PAYMENT_RUN ||--o{ PAYMENT_ALLOCATION : allocates
INVOICE ||--o{ PAYMENT_ALLOCATION : receives
PAYMENT_RUN ||--o{ REMITTANCE_DOCUMENT : publishes
ORDER ||--o{ DOMAIN_EVENT : emits
SHIFT ||--o{ DOMAIN_EVENT : emits
ASSIGNMENT ||--o{ DOMAIN_EVENT : emits
STAKEHOLDER_TYPE ||--o{ STAKEHOLDER_PROFILE : classifies
STAKEHOLDER_PROFILE ||--o{ STAKEHOLDER_LINK : relates
```
## 6) Command write boundary on this schema
@@ -234,6 +315,8 @@ flowchart LR
4. `workforce`: unique active `(vendor_id, staff_id)`.
5. `team_members`: unique `(team_id, user_id)`.
6. `accounts` (or token ref table): unique primary per owner.
7. `attendance_events`: unique idempotency tuple (for example `(assignment_id, source_event_id)`).
8. `offense_rules`: unique `(policy_id, trigger_type, threshold_count)`.
## 7.2 Indexes
1. `orders (tenant_id, status, date)`.
@@ -243,6 +326,9 @@ flowchart LR
5. `assignments (workforce_id, shift_id, role_id, status)`.
6. `verification_jobs (subject_id, type, status, created_at)`.
7. `invoices (business_id, vendor_id, status, due_date)`.
8. `attendance_events (assignment_id, event_time, event_type)`.
9. `offense_events (staff_id, occurred_at, offense_type, status)`.
10. `invoice_line_items (invoice_id, line_type, created_at)`.
## 8) Data type normalization
1. Monetary: `Float -> DECIMAL(12,2)` (or integer cents).
@@ -271,11 +357,13 @@ flowchart TD
- run RBAC in shadow mode"]
P2 --> P3["Phase 3: Scheduling normalization
- remove order JSON workflow fields
- add order_schedule_rules and shift_managers"]
- add order_schedule_rules and shift_managers
- add attendance and offense base tables"]
P3 --> P4["Phase 4: Command rollout
- command writes on hardened schema
- emit domain events + idempotency
- enforce RBAC for command routes"]
- enforce RBAC for command routes
- add finance settlement tables for payment runs and remittance"]
P4 --> P5["Phase 5: Read migration + cleanup
- migrate frontend reads as needed
- enforce RBAC for sensitive reads
@@ -289,6 +377,8 @@ flowchart TD
4. Core transaction invariants enforced by schema constraints.
5. Command API contracts mapped to new normalized tables.
6. RBAC is in shadow mode with decision logs in place (not hard-blocking yet).
7. Attendance and offense tables are ready for policy-driven command routes.
8. Finance settlement tables (`invoice_line_items`, `payment_runs`, `payment_allocations`) are available.
## 12) Full current model relationship map (all models)