diff --git a/.gitignore b/.gitignore index a464f83..80a91ff 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,6 @@ dist-ssr !data_schema.txt !docs/**/*.md .env + +# Reference images / design workflows (local only, not for repo) +Estimate_Section_Screens_and_Workflows/ diff --git a/README.md b/README.md index 389fde3..cc1a495 100644 --- a/README.md +++ b/README.md @@ -1,99 +1,131 @@ -# Plano Realty CRM - Geospatial Field Service Platform +# LynkedUpPro CRM β€” Field Sales & Territory Management Platform -> **The Next Generation of Roofing Sales & Territory Management** +> **The Next Generation of Roofing Sales & Dispatch Management** -**Plano Realty CRM** is an advanced, data-driven platform designed to revolutionize how roofing professionals in Plano, Texas manage their territories, leads, and customer interactions. By combining geospatial intelligence, AI-driven insights, and intuitive workflows, we bridge the gap between field agents and office operations. +**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. --- -## πŸ›οΈ PART 1: PRODUCT OVERVIEW +## πŸ›οΈ PRODUCT OVERVIEW -### 🌟 Value Proposition -In a competitive roofing market, speed and data are everything. Traditional spreadsheets and paper maps leave money on the table. **Plano Realty CRM** solves this by providing: -- **Precision Targeting**: Identify "Golden Leads" (older homes with high value) instantly on a map. -- **Operational Efficiency**: Automate scheduling and follow-ups with our AI Concierge. -- **Real-Time Intelligence**: Know the storm risk and roof condition of every property before you knock. - -### πŸ€– The "Plano AI Concierge" (Upgrade) -Our AI is now a full-fledged **Sales & Support Engine**: -- **For Guests**: Acts as a "Seasoned Consultant" to triage emergencies (leaks) vs. sales (inspections). "Hook" logic converts casual visitors into leads. -- **For Employees**: Answers complex queries like *β€œWhat is my win rate this month?”* or *β€œShow me the average home value in this zip code.”* -- **For Admins**: Provides instant summaries of urgent actions (Unassigned Leads, Pending Signatures) and business health. -- **For Customers**: Dynamic logic checks warranty status based on build year and offers personalized maintenance tips. - -### πŸ“Š The Data Dashboard -A 360-degree view of your territory's health. -1. **Admin Action Center**: A dedicated command center for managers to assign leads, approve schedules, and track urgent tasks. -2. **Golden Leads Scatter Plot**: Visualizes high-value opportunities (High Value + Older Built Year). -3. **Risk Index Gauge**: A real-time meter combining live wind speed data with the percentage of "Needs Repair" roofs. -4. **Revenue Potential**: Bar charts showing which neighborhoods offer the highest ROI based on renovation needs. -5. **Roof Health**: A visual breakdown of the entire territory's roof conditions (Good, Fair, Needs Repair). +### 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 (Latest Updates) +## 🎨 KEY FEATURES -### 1. "LynkedUp Pro" Branding & UX -- **Glassmorphism UI**: A premium, dark-mode-first aesthetic with "Spotlight" cards that glow on hover. -- **Smooth Animations**: Global page transitions (Fade/Slide) and silky-smooth collapsible sidebar. -- **System-Wide Dark Mode**: Inverted map tiles and high-contrast text for comfortable night viewing. +### 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 -### 2. Admin Action Center (NEW) -- **Unassigned Leads**: Instant visibility into new opportunities that need an owner. -- **Hot Leads**: Track high-value prospects that haven't been contacted in >7 days. -- **Smart Assignment**: "One-click" agent assignment with a searchable modal. -- **Urgency Counters**: visual badges highlighting pending signatures and reschedule requests. +### 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 -### 3. Advanced Geospatial Mapping -- **Interactive Polygons**: Color-coded property footprints (Red=Hot Lead, Blue=Customer). -- **Reverse Geocoding**: Click anywhere on the map to create a new property record instantly using OpenStreetMap data. +### 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) -### 4. Role-Based Access Control (RBAC) -- **Field Agents**: View assigned territories, update lead status, and request schedule changes. -- **Admins**: Global view of all agents, approval workflows, and system settings. -- **Customers**: (Coming Soon) Portal to view project status and request service. +### 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 -### 5. Enterprise-Grade Reliability (NEW) -- **Resilient AI**: Chatbot restores user input on network failure, preventing frustration. -- **Global Error Boundaries**: Catches unexpected crashes and offers a graceful "Reload" option. -- **Visual Feedback**: Comprehensive toast notifications for all data actions (Success/Error states). +### 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 -To explore the platform, use these pre-configured accounts. **Password for ALL accounts is: `password`** +**Password for ALL accounts: `password`** -### 1. Field Agent (Worker) -*The primary user. Can view maps, access detailed property data, and manage leads.* -- **Username/ID**: `FA001` (Frank Agent) -- **Alternates**: `FA002`, `FA003`, `FA004`, `FA005` - -### 2. Administrator -*The manager. Sees all agents, global stats, and the **Action Center**.* -- **Username/ID**: `ADM01` (Adam Admin) -- **Alternates**: `ADM02`, `ADM03` - -### 3. Customer (Homeowner) -*The client. Limited view of their own property.* -- **Username**: `alice` -- **Alternates**: `bob`, `charlie` +| 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 | --- -## πŸ’» PART 2: DEVELOPER GUIDE +## πŸ’» DEVELOPER GUIDE -### πŸ›  Tech Stack & Architecture -- **Frontend**: React 18 (Vite), Tailwind CSS, Glassmorphism UI. -- **State**: `MockStore` (Simulates Backend/DB), `AuthContext` (Session Management). -- **AI Engine**: Groq SDK (`qwen-32b`) injected with dynamic system prompts. -- **Visuals**: `react-leaflet` (Maps), `recharts` (Analytics), `lucide-react` (Icons). -- **Reliability**: `sonner` (Toasts), Error Boundaries, Layout Portals. +### 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 & Contribution -1. **Clone**: `git clone ` -2. **Install**: `pnpm install` -3. **Env**: Create `.env` with `VITE_GROQ_API_KEY` and `VITE_OPENWEATHER_API_KEY`. -4. **Run**: `pnpm run dev` +### Setup +1. **Clone**: `git clone ` +2. **Install**: `pnpm install` +3. **Env**: Create `.env` with `VITE_GROQ_API_KEY` and `VITE_OPENWEATHER_API_KEY` +4. **Run**: `pnpm run dev` -**Maintained by Satyam Rastogi** +### 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**