LynkedUpPro_CRM/README.md

# 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 "Golden Leads" (older, 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 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

### 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)

### Lead Creation Page _(in development)_
- Quick Capture (7 fields) for agents at the door, Full Form for office
- 5 color-coded sections: Contact (blue), Property (emerald), Job Details (amber), Insurance (purple), Assignment (cyan)
- Role-aware: agents get simplified assignment, admins/owners get Smart Assign with rep scoring
- Mobile-first, works beautifully on tablet and desktop too

### 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 (XP/streaks)
- **Routing**: React Router v7 with ProtectedRoute (role-based)
- **Animations**: Framer Motion (page transitions, stagger entrances, height animations)
- **Maps**: react-leaflet (Leaflet.js)
- **Charts**: Recharts (bar, area, pie, scatter)
- **Icons**: lucide-react
- **AI**: Groq SDK (qwen-32b) with dynamic role-aware system prompts
- **Notifications**: sonner (toasts)
- **Smooth Scroll**: Lenis

### 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`
- All components use `dark:` Tailwind variants — no JS theme switching per-element needed

---

## 📁 Project Structure (Abbreviated)

```
src/
├── pages/            # Route-level pages by role
├── components/
│   ├── estimates/    # EstimateBuilder modals (MaterialDetails, Measurements, etc.)
│   ├── leads/        # Lead creation form components (in development)
│   ├── dispatch/     # LynkDispatch AI panels (in development)
│   ├── dashboard/    # Admin dashboard widgets
│   ├── ProCanvas/    # Gamification subcomponents
│   └── ...           # Shared components (Layout, AnimatedCounter, etc.)
├── context/          # AuthContext, ThemeContext, GamificationContext
├── data/             # mockStore.jsx — central data layer
└── hooks/            # useGamification, custom hooks
```

---

**Maintained by Satyam Rastogi | Branch: revamp | Last updated: March 12, 2026**