Satyam Rastogi
2ce3395006
Switch the assistant model from qwen/qwen3-32b to openai/gpt-oss-120b. Cap every per-role context list, hard-clamp the assembled system prompt to ~4000 tokens at a line boundary, and bound re-sent chat history to 12 messages so the model context window can't be exceeded regardless of mock-data volume.
163 lines
9.1 KiB
Markdown
163 lines
9.1 KiB
Markdown
# LynkedUpPro CRM — Field Sales & Territory Management Platform
|
||
|
||
> **The Next Generation of Roofing Sales & Dispatch Management**
|
||
|
||
**LynkedUpPro CRM** is an advanced, data-driven platform for roofing and real estate canvassing teams. Field agents knock doors and log leads on mobile, admins dispatch reps from the office, and owners get a real-time command center — all in one app.
|
||
|
||
**Current branch:** `revamp` — complete UI/UX overhaul in progress.
|
||
|
||
---
|
||
|
||
## PRODUCT OVERVIEW
|
||
|
||
### Value Proposition
|
||
- **Precision Targeting**: Identify high-value homes instantly on a map.
|
||
- **AI-Powered Dispatch**: LynkDispatch AI scores and recommends rep assignments in real-time.
|
||
- **Gamified Field Performance**: ProCanvas turns door-knocking into a performance game — XP, streaks, leaderboards, daily missions.
|
||
- **Intelligent Lead Capture**: Mobile-optimized lead creation with Quick Capture for the door, Full Form for the office.
|
||
|
||
---
|
||
|
||
## KEY FEATURES
|
||
|
||
### ProCanvas — Gamified Agent Dashboard
|
||
- FIFA-style player card with XP bar, streak tracker, and rank badge
|
||
- Log Action hub (Door Knocked, Lead Gained, Appointment, Client Meet)
|
||
- Daily Missions with Energy Bars, Weekly Challenge with progress tracking
|
||
- Live event cards: Showdown, Hot Streak, Weekly Objective
|
||
- Rewards & Checkpoints milestone track, Badges & Achievements trophy room
|
||
- **Dual design identity**: Light mode (energetic/clean — solid colored header banners on white cards) and Dark mode (neon/glass arcade aesthetic) — distinct, never washed-out
|
||
|
||
### Estimate Builder
|
||
- Section → Group → Item hierarchy
|
||
- Material Details Modal (measurement → waste → qty → cost → price formula)
|
||
- Measurements Modal for detailed takeoffs
|
||
- Financial Summary sidebar with adjustable margin slider
|
||
- Full light/dark theme support
|
||
|
||
### Lead Creation Page _(All 8 phases complete)_
|
||
- Quick Capture (essential fields only) for agents at the door; Full Form for the office
|
||
- 5 color-coded accordion sections: Contact (blue), Property (emerald), Job Details (amber), Insurance (purple), Assignment (cyan)
|
||
- **Custom portaled dropdowns** (`LeadCustomSelect`) — dark zinc-900 panel, fully scrollable, escapes all `overflow:hidden` containers via `ReactDOM.createPortal`; scroll detection uses `e.composedPath()` for reliability across browsers and touch
|
||
- **Fuzzy-search state combobox** (`LeadCombobox`) — type "tex" to find Texas, searches both abbreviation and full state name simultaneously
|
||
- **Flex-wrapper icon pattern** for Phone/MapPin icons — eliminates z-index conflicts, icons are true flex siblings of the input
|
||
- **Insurance section** — carrier, claim number, claim status, adjuster name/phone, policy number (purple accent)
|
||
- **Assignment section** — role-aware rep selector (agents: self-assign toggle; admins/owners: full scrollable agent list), priority pill (Low/Medium/High), follow-up date picker (cyan accent)
|
||
- **Save action** — validates required fields, Sonner toast on success/failure, redirects to Leads list
|
||
- **Leads list page** (`/emp/fa/leads`) — card list with urgency/status badges, search bar, animated empty state
|
||
- Animated progress bar (GSAP), section completion checkmarks, spring height animations (Framer Motion)
|
||
- Mobile-first: sticky Save footer, responsive City/State/ZIP grid layout, ample bottom padding for footer clearance
|
||
|
||
### LynkDispatch AI _(investor demo — in development)_
|
||
- 3-panel command center: Lead Queue + Map + AI Recommendation Drawer
|
||
- Rep scoring with proximity, drive time, calendar fit, weather, and skill factors
|
||
- Storm Mode — full UI shift to amber, storm path on map, weather-aware recommendations
|
||
- KPI bar with animated metrics (leads in queue, assigned today, response time, storm alerts)
|
||
- New lead auto-drops every 20s during demo, Leaflet map with real Plano TX coordinates
|
||
- Sidebar label: "LynkDispatch" — branded, sidebar-friendly
|
||
|
||
### Maps & Territory
|
||
- Interactive Leaflet map with color-coded property polygons
|
||
- Reverse geocoding to create properties from map clicks
|
||
- Rep location overlays and lead clustering (in development)
|
||
|
||
### Admin Action Center
|
||
- Unassigned lead queue — zero leakage
|
||
- Smart agent assignment modal
|
||
- Urgency counters and pending signatures tracking
|
||
|
||
### Owner's Box
|
||
- Financial KPIs (revenue, spend, health score)
|
||
- Project command center with change orders and budget vs. actuals
|
||
- People, vendor, and document management
|
||
|
||
---
|
||
|
||
## USER ROLES & DEMO ACCOUNTS
|
||
|
||
**Password for ALL accounts: `password`**
|
||
|
||
| Role | Account ID | Description |
|
||
|---|---|---|
|
||
| Field Agent | `FA001` – `FA005` | Door knocking, lead logging, ProCanvas |
|
||
| Admin | `ADM01` – `ADM03` | Action center, dispatch, leaderboard |
|
||
| Owner | `OWN01`, `OWN02` | Full platform access, owner snapshot |
|
||
| Contractor | `CON01` | Project and task management |
|
||
| Vendor | `VEN01` | Orders and invoices |
|
||
| Subcontractor | `SUB01` | Work scope and tasks |
|
||
| Customer | `alice`, `bob`, `charlie` | Customer portal |
|
||
|
||
---
|
||
|
||
## DEVELOPER GUIDE
|
||
|
||
### Tech Stack
|
||
- **Frontend**: React 19 (Vite), Tailwind CSS (`darkMode: 'class'`)
|
||
- **State**: MockStore (simulates backend), AuthContext (RBAC), ThemeContext (light/dark), GamificationContext
|
||
- **Routing**: React Router v7 with ProtectedRoute (role-based)
|
||
- **Animations**: Framer Motion (page transitions, stagger, height animations, layoutId), GSAP (progress bars, counters)
|
||
- **Maps**: react-leaflet
|
||
- **Charts**: Recharts
|
||
- **Icons**: lucide-react
|
||
- **AI**: Groq SDK (openai/gpt-oss-120b) with dynamic role-aware system prompts (token-budgeted)
|
||
- **Notifications**: sonner (toasts)
|
||
|
||
### Setup
|
||
1. **Clone**: `git clone <repo>`
|
||
2. **Install**: `pnpm install`
|
||
3. **Env**: Create `.env` with `VITE_GROQ_API_KEY` and `VITE_OPENWEATHER_API_KEY`
|
||
4. **Run**: `pnpm run dev`
|
||
|
||
### Design System
|
||
- **Dark mode**: Glass panels (`bg-zinc-900/70 backdrop-blur-xl`), neon accents, Barlow Condensed uppercase
|
||
- **Light mode**: White cards (`bg-white shadow-md`), solid colored header banners, `bg-zinc-100/80` page background
|
||
- Theme controlled via `useTheme()` from `src/context/ThemeContext.jsx`
|
||
- **Critical rule**: always use `dark:` Tailwind variants on inputs and text — never `isDark ? 'classA' : 'classB'` — JS conditionals caused invisible text bugs in dark mode that dark: variants solve
|
||
|
||
### Custom Dropdown Architecture (LeadCustomSelect / LeadCombobox)
|
||
All select fields in the Lead Creation form use custom components rather than native `<select>`:
|
||
- Trigger button styled identically to the other input fields
|
||
- Panel rendered via `ReactDOM.createPortal` into `document.body` — escapes all `overflow:hidden` ancestors (critical because Framer Motion collapse animations use overflow:hidden)
|
||
- Position: `getBoundingClientRect()` + `window.scrollY/scrollX` → `position: absolute` on body
|
||
- Scroll detection: `e.composedPath()` — reliable across Chrome, Safari, Firefox, and mobile touch
|
||
- `accent` prop: `'blue'` (Job Details) or `'emerald'` (Property section)
|
||
- `compact` prop: for inline type pickers (phone/email type selectors, `w-24` container)
|
||
- `LeadCombobox`: input-based variant with live fuzzy filtering — `Enter` selects top result, `Escape` cancels
|
||
|
||
---
|
||
|
||
## Project Structure (Abbreviated)
|
||
|
||
```
|
||
src/
|
||
├── pages/
|
||
│ ├── CreateLeadPage.jsx # Lead creation orchestrator (form state, sections, progress, save)
|
||
│ ├── LeadsListPage.jsx # Leads list with search, cards, empty state
|
||
│ └── ... # Other role pages
|
||
├── components/
|
||
│ ├── leads/
|
||
│ │ ├── LeadSectionWrapper.jsx # Collapsible accordion with spring animation
|
||
│ │ ├── LeadContactSection.jsx # Name, dynamic phone rows, dynamic email rows
|
||
│ │ ├── LeadPropertySection.jsx # Address, city/state/zip, property type, site photos
|
||
│ │ ├── LeadJobSection.jsx # Lead source, type, work/trade type, urgency, notes
|
||
│ │ ├── LeadInsuranceSection.jsx # Carrier, claim #/status, adjuster name/phone, policy #
|
||
│ │ ├── LeadAssignmentSection.jsx # Role-aware rep selector, priority pill, follow-up date
|
||
│ │ ├── LeadCustomSelect.jsx # Portaled custom dropdown (accent + compact modes)
|
||
│ │ ├── LeadCombobox.jsx # Fuzzy-search combobox for state field
|
||
│ │ ├── UrgencyPillSelector.jsx # Sliding pill with Framer Motion layoutId
|
||
│ │ ├── PhoneEntryRow.jsx # Phone input with mask, type picker, primary star
|
||
│ │ └── EmailEntryRow.jsx # Email input with type picker, primary star
|
||
│ ├── estimates/ # EstimateBuilder modals
|
||
│ ├── dispatch/ # LynkDispatch AI panels (in development)
|
||
│ ├── dashboard/ # Admin dashboard widgets
|
||
│ └── ... # Layout, AnimatedCounter, shared components
|
||
├── context/ # AuthContext, ThemeContext, GamificationContext
|
||
├── data/
|
||
│ └── mockStore.jsx # Central data layer + LEAD_FORM_OPTIONS + leads[] + addLead()
|
||
└── hooks/ # useGamification, custom hooks
|
||
```
|
||
|
||
---
|
||
|
||
**Maintained by Satyam Rastogi | Branch: revamp | Last updated: March 21, 2026**
|