LynkedUp Pro Roofing — Demo Build: Master Scope & Rationale

Date: 2026-05-29 · Branch: revamp This doc = the single "what we're doing and why." Detailed specs live in docs/superpowers/specs/, step-by-step plans in docs/superpowers/plans/, and the subagent rules in the execution protocol. This is the map above all of them.

1. Vision

Turn the CRM's mock data and screens into one coherent fake roofing company ("LynkedUp Pro Roofing", Plano TX) that works as BOTH:

a live sales demo to roofing-company prospects — believable, no empty/broken views, numbers that feel real at a glance, a continuous story you can walk; and
an investor pitch — breadth, depth, and analytics that impress.

Guiding principle — coherence is the wow. When a prospect drills from a dashboard KPI into the exact records that compose it, and from a project into the lead that created it and the subcontractor working it, and every name/number/date ties out — that is what sells. So we optimize for end-to-end internal consistency over surface polish, and we compute analytics from the data (not hardcode them) so they can never drift.

Audiences → implications: dual sales+investor means everything must be coherent AND deep. No tab may be empty; every entity must trace to the others.

2. Status snapshot

✅ Phase 1 — Data Foundation (DONE, reviewed APPROVED): canonical identity (one id scheme), realistic Texan roster with unified LUP-#### employee ids, reconciling project financials, seeded Leads page, reachable subcontractor logins, address-matched tasks, kanban lead values, and a per-role login picker. 14 commits, build clean.
⏳ Phases 2–7 below are planned/in-design.

3. The work — phase by phase (What · Why · Key decisions)

Phase 2 — Unify lead↔project + routing/naming

What: A won kanban lead (stages Signed/In-Progress/Complete) becomes a first-class project sharing the SAME rich detail page as owner projects. Clean routes: everything won lives at /owner/projects/:id (and /admin/projects, /emp/fa/projects); pre-sale leads stay at /…/leads/:id (a lighter view). Unified human-meaningful ids (e.g. PRJ-2026-014). Kanban cards/links and the project list point at the unified route. Why: Today there are two parallel data models and two detail pages for the same concept (a job): the projects array + OwnerProjectDetail (2,086 lines, 10 tabs, owner-only) vs KANBAN_PROJECT_DATA + LeadProjectPage (1,159 lines, thinner). That's why "lead pages don't match project pages" and routes feel inconsistent. Unifying makes the rich detail page, lifecycle, estimates, and analytics apply to won leads for free — one entity, one UI, no duplication to keep coherent. Key obstacles (from code exploration): no join key exists between kl_* and proj_* (no shared id/address/FK); field-name mismatches (estimatedAmount↔budget, completionPct↔completionPercentage, workTimeline↔activityTimeline, invoice/RFI/CO date-field names differ); won leads lack teamMembers/riskLog/issueLog/paymentSchedule/contractorId/commission config; the commission engine needs contractorId/salesRepId+orgMembers; projects UI is owner-only so admin/field-agent need a projects route too; 4 navigation call-sites to update (LeadInfoDrawer, OwnerProjectList ×3). Id blast-radius is contained to mockStore.jsx but proj_* has inbound FKs from tasks/schedule/subcontractor data that must migrate together. Decisions made: Unify (won lead IS a project). /owner/projects/:id + PRJ-####. Pre-sale leads show a lighter subset of the same page.

Phase 3 — Kanban/pipeline depth + analytics

What: All four kanban-data priorities — (1) realistic lead details (names, values, notes, dates), (2) rich per-lead project data matching the project detail, (3) coherent stage distribution + working pipeline total & conversion funnel, (4) storm attribution on leads. Plus the 10 threaded demo-case projects (storm-win, insurance-backed up-scope→approved, up-scope→declined, down-scoped, multi-revision, over-budget, commercial, near-complete, completed, disputed) and a computed selectors.js analytics layer wired into owner/admin dashboards so KPIs tie out with detail screens. Why: The pipeline must look like a busy real company (investor breadth), and a salesperson must be able to demo any scenario (sales). Computed analytics guarantee the dashboard never contradicts the records a prospect drills into.

Phase 4 — Project lifecycle + inspections + estimates

What: Make the existing PROJECT PROGRESSION bar interactive: a state machine (Lead → Damage Inspection Scheduled → Damage Verified → Scope Approved → Contract Signed → Work In Progress → Work Complete · Awaiting Inspection → Final Inspection → [Issues→Rework loop] → Completed → Final Payment Received) with progress % correctly tied to the stage. Two inspection touchpoints recorded with who did them: pre-sale Damage Verification (internal, name+role per project) and post-work Final Inspection by an external examiner (we store name + contact so they can be re-contacted, feedback, and issues[] each with description/note/photos/status; re-inspection keeps every round). A claimed-vs-verified scope-variance model with a visible badge (e.g. "Reported ~$200 → Verified $15,400"). An estimate-versions section per project (v1 from claim → v2 verified → signed), each opening the full rendered estimate document. Why: The screenshot of proj_003 shows the progression bar exists but its stage and the 42% completion don't agree — exactly the "progress % tied to stages" gap. Interactivity + the inspection loop + the scope-variance story are the core sales narrative (professional inspection turns a $200 self-report into an insurance-backed job). Uploads persist for the session (client-side), seeded with starting data.

Phase 5 — Subcontractor task stage machine

What: Replace the flat task statuses with: Not Assigned → Assigned → Pre-Work Inspection → Work In Progress → (On Hold ↔) → Post-Work Review → [Pass→Completed / Fail→Rework Needed (issue: what's wrong + note + photo) → back to Work In Progress]. Every transition carries an optional note + timestamp + who set it. Pre-Work Inspection and Post-Work Review record who performed them. Owner /owner/subcontractor-tasks table gains Task Category and Assigned Date columns; the task detail modal gets a richer progress timeline + issues list with photos. Why: Mirrors the real field workflow and gives the subcontractor an interactive inbox; the review/rework loop is a credible operational story.

Phase 6 — Subcontractor portal data + project parity (`/subcontractor/`)

What: The subcontractor-facing pages (/subcontractor/dashboard, projects, task detail) get realistic data and, where they show a job, the same project details as the owner sees (a permitted subset of the unified project) — so a sub viewing their task sees the real project (address, scope, schedule, their slice of budget/payments) consistent with the owner's view. Why: Coherence across logins is the demo's credibility test — the same job must look like the same job whether the owner or the subcontractor is looking. The Phase-2 unify makes this possible (one project entity); this phase wires the subcontractor views to it with appropriate visibility.

Phase 7 — Profiles, skill catalog & AI dispatch context

What: Every employee & subcontractor gets a two-layer profile: self section (preferred name, photo, contact, optional nickname/pronouns/gender/sex, bio, experience, languages, self-declared specialties + equipment carried e.g. "tarp/ladder rack"; subs: company/license/insurance) editable on a self-service User Details page (all roles incl. owners); and a company section (private to owner/admin): internal notes, status/tags, skill scores (a shared org skill catalog — name+description, each person 0–100 or N/A), pay terms. Employee achievements & levels (from ProCanvas gamification) surface read-only. An owner Employee/Subcontractor Details view shows the full profile. These feed LynkDispatch: DISPATCH_REPS map to canonical people and each recommendation's skillMatch/reasons/aiInsight cite real profile facts (equipment + skill scores), so "the AI read their profile" is demonstrably true on screen. Why: Richer context = better, more believable AI dispatch recommendations (the investor "wow"), and the profile pages add depth a prospect expects from a mature CRM.

4. Cross-cutting coherency requirements (the throughline)

One canonical person per id, one name everywhere (done in Phase 1; every later phase must preserve it).
A job is one entity (Phase 2) — lead→project→subcontractor task→invoices→commission all reference it and tie out.
Dashboard KPIs == sums of the underlying records (Phase 3 computed selectors).
The same job looks the same across owner / pipeline / subcontractor logins (Phases 2 & 6).
Profiles/skills/equipment are cited by dispatch (Phase 7).
No empty tabs, no "Unknown" labels, no future-dated mock data (anchor: DEMO_TODAY = 2026-05-29).

5. Execution model

Subagent-driven: controller extracts each task's full text + context, dispatches a fresh implementer per task, then spec + code-quality review; build gate (npm run build must be green) + targeted reconciliation checks per task; commit per task.
Parallelism (now allowed, with guardrails): tasks that touch disjoint files may run in parallel. Tasks that share a file (especially mockStore.jsx) run sequentially. Each plan ships a lane/ownership map assigning every task an exclusive file set; the controller only parallelizes tasks whose lanes don't intersect, and never lets two in-flight agents write the same file. Commit between dependent tasks. (This generalizes the original strictly-sequential rule: sequential is the fallback when lanes overlap; parallel is allowed when they don't.)
No test framework exists → verification is build + grep/reconciliation + dev-run, not unit tests.
Invariants every task preserves: canonical ids + roster names; coherency requirements in §4.

6. Plan / spec index

Spec: docs/superpowers/specs/2026-05-29-demo-data-coherence-design.md
Plan 1 (done): docs/superpowers/plans/2026-05-29-demo-data-foundation.md
Execution protocol: docs/superpowers/plans/2026-05-29-execution-protocol.md
Plans 2–7: to be authored from this master doc (Phase 2 next).

7. Open decisions / deferred

Stage-name wording tweaks (user said "I'll tweak a few" — proposed names stand until provided).
Exact PRJ-#### id format + whether pre-sale leads also get PRJ ids on conversion only.
Per-plan lane maps (authored with each plan) to enable safe parallel execution.

11 KiB Raw Blame History Unescape Escape