LynkedUpPro_CRM/docs/superpowers/specs/2026-05-29-demo-data-coherence-design.md

Demo Data Coherence & Simulation Depth — Design Spec

Date: 2026-05-29 Branch: revamp Goal: Turn the CRM's mock data into one coherent fake roofing company ("LynkedUp Pro Roofing") that works as both a live sales demo (believable, no empty/broken views, numbers that feel real) and an investor pitch (breadth, depth, analytics wow). Coherence end-to-end is the wow: drilling from any dashboard KPI lands on the exact records that compose it.

Approach: A — Canonical-company foundation, then layer up. Analytics are computed from the canonical data (with one curated exception: purely-visual long-range trend lines).

---

1. Canonical identity (foundation)

Problem (from audit): the same people exist under three incompatible ID schemes, so cross-module lookups silently fail; Owner #2 has two names; admins have placeholder names; subcontractor tasks reference non-existent ids (owner_001, ADM01).

Decision: unify on the MOCK_USERS scheme (already used by auth and projects):

• Owners: own_001 (Justin Johnson), own_002 (Diana Reeves)
• Admins: a1 (Adam Admin), a2 (Amanda Manager), a3 (Arthur Director)
• Field agents / canvassers: e1–e5 (Frank Agent, Fiona Field, Fred Flyer, Felicity Fast, Felix Fixer)
• Sales reps / personnel: p1 (Jesus Gonzales), p2 (Sarah Sales)
• Contractor: con_001 (Mike Contractor); Subcontractors: sub_001–sub_005

Changes:

• Remap orgMembers[].userId: owner_001→own_001, owner_002→own_002, FA00N→eN, ADM0N→aN. Keep orgMembers[].roleKey as the org-role taxonomy (OWNER/ADMIN/SALES_REP/CANVASSER/SUBCONTRACTOR).
• Reconcile names/emails: own_002 = Diana Reeves everywhere; admins = real names (not "Admin One/Two/Three"); Justin's email consistent (justin@lynkeduppro.com).
• Remap subcontractor-task references: assignedBy/actorId/senderId owner_001→own_001, ADM01→a1; correct the denormalized *Name strings to match.
• Add a resolvePerson(id) selector in the store (returns { id, name, email, role, avatar? } from a single merged index) so every module resolves people the same way.

Acceptance: no reference to owner_001/FA0*/ADM0* as an id anywhere; every userId/assignedBy/teamMembers[].userId/ownerId/contractorId/subcontractorIds[] resolves via resolvePerson/the relevant collection; own_002 shows one name across all screens.

---

2. Coherence fixes (the four approved tiers)

2a. Feature-breaking data

• Leads List page: seed the store's leads array (currently useState([])) with ~28–35 records in the page's shape (firstName/lastName, phones[], urgency, status, leadSource, canvasserName, createdByName, createdAt, stormSource). Source = the existing storm-attribution leads, expanded. Page must never show the empty state on load.
• Subcontractor access: add login user records for sub_002–sub_005 (type subcontractor) so each subcontractor's tasks/notifications are reachable. Keep existing task ownership.
• Task → project association: every subcontractor task points to a project whose address matches the task location (residential roofing/electrical tasks → residential projects, not the commercial facade/hotel projects). Fix STATUS_CONFIG/STATUS_STYLES to include On Hold.

2b. Financial coherence

• proj_008: reduce paid invoices so paid ≤ committedCost (52,000) and ≤ actualCost (44,500).
• proj_005: set committedCost to the breakdown's real sum 28,850 (work was committed; stored total was stale); verify variance/margin recompute.
• Completed projects (proj_002, proj_010): paid invoices ≤ actualCost (no overpay vs spend).
• proj_004: fix the contingency line where committed < actual; keep it as the deliberate over-budget case.
• Missing budgetBreakdown: add coherent breakdowns to proj_006, 008, 009, 010, 011, 012 — allocated sums to budget, committed sums to committedCost, actual sums to actualCost, committed ≥ actual per line.

2c. Pipeline / Kanban

• Add a structured numeric value (estimate) to every kanban lead (not just signed+), so a pipeline $ total and weighted funnel can be computed.
• Fix Complete-stage leads (kl_034–038): real actualCost and completionPct: 100.
• Re-anchor the hardcoded "today" (KanbanCard.jsx:14) — derive from a single DEMO_TODAY constant (= a fixed recent date) used app-wide, or Date.now(); dates stay ordered and not-future relative to it.
• Populate stormSource: true on storm-canvassed leads so the wired badge shows.
• kl_044 (Signed) gets a project record or moves to a pre-signed stage.

---

3. Five–six fully-threaded scenario projects (real-world spread)

Instead of one hero, 6 projects are threaded end-to-end across modules, each representing a distinct real-world case. Every thread shares consistent identities, addresses, and dates from lead → project → subcontractor task → invoices/payments → commission.

#	Project	Scenario it demonstrates	Thread highlights
proj_001	Roof Replacement (active, healthy)	Storm-driven win, on track	Storm lead (Frank/e1 canvasses) → Jesus/p1 closes → active project, Carlos/sub_001 electrical task → progress invoices → commission accrues
proj_004	Interior Reno (over budget)	Problem job / margin loss	Scope-creep change orders → costs exceed budget → at-risk health → owner sees negative net profit
proj_007	Commercial Roof (large, active)	Big commercial, multi-phase	Payment schedule by phase, multiple subs, larger commission
proj_008	Foundation (88%, healthy)	Near-complete, healthy	Most milestones done, final invoices pending, payout imminent
proj_010	Parking Lot (completed)	Closed-won, full lifecycle	Lead won months ago → completed → all invoices paid → commission paid out
proj_011	Facade/Disputed	Disputed / on-hold	Dispute timeline, paused payments, low health score

Each thread requires: a matching lead (pipeline stage consistent with project status; stormSource where relevant), at least one subcontractor task (address-matched), invoices + paymentSchedule that reconcile with actualCost, a commission config + (for completed) payout, and consistent team/owner/dates.

---

4. Deeper project detail tables

Every project carries the full coherent set so no tab is empty: budgetBreakdown, changeOrders, rfis, riskLog, issueLog, activityTimeline, milestones, invoices, paymentSchedule, documents, teamMembers. Thin/empty arrays get realistic content sized to the project's status and scenario.

---

5. Broader pipeline + leaderboard

• More leads spread realistically across stages with $ values and storm attribution.
• Canvasser leaderboard stats derive from the leads each agent sourced (knocks → leads → won), so the leaderboard ties to the pipeline.

---

6. Computed analytics (investor wow)

Add a src/data/selectors.js (pure functions over store arrays) deriving:

• Pipeline: total value, weighted value by stage, conversion funnel counts, win rate.
• Revenue/profit: total contract value, gross/net profit, margin — summed from projects (matching OwnerProjectDetail's own formulas).
• Commission: total accrued/paid by rep, by project.
• Subcontractor performance: tasks by sub, on-time %, total paid.
• Storm attribution: leads/revenue traced to storm events.

Wire these into the owner/admin dashboards (OwnerSnapshot, Dashboard, leaderboard) replacing hardcoded figures, so KPIs tie out with detail screens. Curated exception: purely-visual long-range trend charts (e.g., 12-month revenue line) where no daily source data exists — these stay hand-authored and are labeled as illustrative.

Acceptance: the owner dashboard's headline revenue/profit/pipeline numbers equal the sums of the underlying project/lead records (verified by a quick selector unit check).

---

Components / files touched

• src/data/mockStore.jsx — identity remap, leads seed, financial fixes, breakdowns, threaded scenarios, sub logins, deeper tables, pipeline values. This file is large (~6,950 lines); changes are additive/surgical, not a rewrite.
• src/data/selectors.js — new, computed analytics.
• Dashboards/components consuming analytics: src/pages/owner/OwnerSnapshot.jsx, src/pages/Dashboard.jsx, leaderboard page, src/components/kanban/KanbanCard.jsx (date anchor), SubcontractorTasksPage.jsx/TaskViewModal.jsx (On Hold styling).

Out of scope (YAGNI)

• No backend/persistence changes (mock store only).
• No new routes/pages beyond what exists.
• No visual redesign of components — data + selectors + minimal wiring only.
• The dormant project.margin field stays but is made honest; not wired into new UI.

Build sequencing

1. Canonical identity + resolvePerson (everything depends on it).
2. Financial coherence + missing breakdowns (so projects reconcile).
3. Feature-breaking fixes (leads seed, sub logins, task↔project).
4. Threaded scenarios (lead↔project↔task↔invoice↔commission).
5. Pipeline breadth + leaderboard.
6. selectors.js + dashboard wiring.
7. Verify build + spot-check reconciliation.

Verification

• npm run build clean after each major step.
• Reconciliation spot-checks: dashboard revenue == Σ project contract values; pipeline total == Σ lead values; a threaded scenario navigable lead→project→task→invoice→commission with consistent names/dates.
• Dev run: Leads page non-empty; each subcontractor login sees their tasks; no "Unknown"/empty owner labels.