docs: master scope & rationale for the demo build (all phases + why)
This commit is contained in:
Satyam Rastogi
@@ -0,0 +1,82 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user