feat: complete dashboard widgets, fix tooltips, integrate chatbot, and update docs
This commit is contained in:
Satyam
@@ -1,134 +1,113 @@
|
||||
# Plano Realty CRM - Field Service & Sales Platform
|
||||
# Plano Realty CRM - Geospatial Field Service Platform
|
||||
|
||||
**Plano Realty CRM** is a next-generation Geospatial CRM designed for roofing professionals in Plano, Texas. It specifically targets the coordination between field agents and customers, leveraging AI and real-time data to streamline the sales and inspection process.
|
||||
> **The Next Generation of Roofing Sales & Territory Management**
|
||||
|
||||
## 🚀 Product Overview
|
||||
|
||||
- **Purpose**: To replace outdated spreadsheet tracking with an interactive, map-based interface for managing roofing leads and inspections.
|
||||
- **Core Functionality**:
|
||||
- **Interactive Maps**: Visual territory management with property polygons.
|
||||
- **AI Concierge**: A chatbot (powered by Groq/Qwen) that schedules meetings and answers context-aware questions.
|
||||
- **Dashboard**: Real-time metrics, weather integration (OpenWeatherMap), and schedule management.
|
||||
- **Role-Based Access**: Distinct interfaces for **Field Agents**, **Admins**, and **Customers**.
|
||||
|
||||
## 🛠 Implementation Details
|
||||
|
||||
The system is built as a **Single Page Application (SPA)** using:
|
||||
|
||||
- **Frontend Framework**: React 18 + Vite
|
||||
- **Styling**: Tailwind CSS (Dark Mode Native) + Glassmorphism UI
|
||||
- **State Management**: React Context API (`AuthContext`, `MockStore`)
|
||||
- **AI Integration**: Groq SDK (running `qwen-2.5-32b`) for natural language processing.
|
||||
- **Maps**: Custom SVG/Canvas implementations for property visualization.
|
||||
- **Animations**: GSAP (GreenSock) for high-performance interactions.
|
||||
|
||||
## 📂 Project Structure
|
||||
|
||||
```text
|
||||
/src
|
||||
├── assets/ # Static images and icons
|
||||
├── components/ # Reusable UI components
|
||||
│ ├── Chatbot.jsx # AI Floating Widget
|
||||
│ ├── Layout.jsx # App Sidebar & Shell
|
||||
│ ├── SpotlightCard.jsx # Premium Card UI with Glow
|
||||
│ └── ...
|
||||
├── config/ # Environment variables
|
||||
│ └── env.js # Centralized config loader
|
||||
├── context/ # Global State
|
||||
│ ├── AuthContext.jsx # User Authentication Logic
|
||||
│ └── ThemeContext.jsx # Dark Mode Management
|
||||
├── data/ # Data Layer
|
||||
│ └── mockStore.jsx # Mock Data Generator (Users, Meetings, Properties)
|
||||
├── pages/ # Route Views
|
||||
│ ├── Dashboard.jsx # Agent KPI View
|
||||
│ ├── Landing.jsx # Public Sales Page
|
||||
│ ├── Login.jsx # Authentication Pge
|
||||
│ └── Maps.jsx # Territory Map View
|
||||
└── utils/ # Helpers
|
||||
└── logger.js # Structured Logging
|
||||
```
|
||||
|
||||
## ⚡ Running the Project
|
||||
|
||||
1. **Prerequisites**: Node.js (v18+) and `pnpm`.
|
||||
2. **Installation**:
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
3. **Environment Setup**:
|
||||
- Create a `.env` file in the root.
|
||||
- Add keys:
|
||||
```env
|
||||
VITE_GROQ_API_KEY=your_key_here
|
||||
VITE_OPENWEATHER_API_KEY=your_key_here
|
||||
```
|
||||
4. **Start Dev Server**:
|
||||
```bash
|
||||
pnpm run dev
|
||||
```
|
||||
Access the app at `http://localhost:5173`.
|
||||
|
||||
## 📝 File Responsibilities
|
||||
|
||||
### `src/data/mockStore.jsx`
|
||||
The heart of the application's data layer. Since there is no backend, this file generates realistic seed data.
|
||||
|
||||
- **`generateProperties()`**: Creates ~60 property records with geospatial coordinates, ownership details, and styles (Commercial vs Residential).
|
||||
- **`generateMockMeetings()`**: Simulates agent schedules, ensuring a mix of past (completed) and future (scheduled) appointments.
|
||||
|
||||
### `src/components/Chatbot.jsx`
|
||||
Handles all AI interactions.
|
||||
- **Input**: User text + Current User Context + Meeting Schedule.
|
||||
- **Processing**: Sends prompt to Groq API with a custom system prompt ensuring "Americana" branding.
|
||||
- **Output**: Renders Markdown responses and handles structured `CALLBACK_REQUEST` JSON for scheduling.
|
||||
|
||||
### `src/context/AuthContext.jsx`
|
||||
Manages user sessions.
|
||||
- **`login(identifier, password, type)`**: Validates credentials against `MOCK_USERS`.
|
||||
- **`user` object**: Contains `role`, `name`, `id`, and permissions.
|
||||
|
||||
## 🗺️ Map Functionality & Geospatial Logic
|
||||
|
||||
The map interface (`src/pages/Maps.jsx`) is the core operational view, overlaying business data on real-world geography.
|
||||
|
||||
### 1. Visualization & Overlays
|
||||
- **Rendering Engine**: Powered by `react-leaflet`.
|
||||
- **Polygons**: Property boundaries are drawn using the `Polygon` component, taking an array of `[lat, lng]` coordinates.
|
||||
- **Status Styling**:
|
||||
- **Hot Lead**: Red Fill (`#ef4444`)
|
||||
- **Customer**: Emerald Fill (`#10b981`)
|
||||
- **Renovated**: Blue Fill (`#3b82f6`)
|
||||
- **Neutral**: Zinc Fill (Default)
|
||||
|
||||
### 2. Interaction & Data Retrieval
|
||||
- **Click-to-Reveal**: Clicking a polygon triggers `onSelect(property)`, opening the **Property Drawer**.
|
||||
- **Returns**: Full `propertyData` (Address, Build Year, Value) and `ownerData` (Name, Contact, Intent).
|
||||
- **Reverse Geocoding (New Property)**:
|
||||
- **Trigger**: Clicking an empty map area (Field Agents only).
|
||||
- **API Call**: `https://nominatim.openstreetmap.org/reverse`
|
||||
- **Parameters**: `lat`, `lon`, `format='json'`.
|
||||
- **Return**: Returns a JSON object where `display_name` is extracted as the property address.
|
||||
|
||||
## 📚 Function Documentation
|
||||
|
||||
### `useMockStore: addMeeting(meeting)`
|
||||
Adds a new meeting to the global state.
|
||||
- **Inputs**:
|
||||
- `meeting` (Object): `{ agentId, customerName, time, date, propertyId, status }`
|
||||
- **Returns**: `void`
|
||||
- **Side Effect**: Updates the `meetings` array and triggers a re-render of the Dashboard and Chatbot context.
|
||||
|
||||
### `config.isDemoMode(key)`
|
||||
Checks if the system should run in simulated demo mode.
|
||||
- **Inputs**: `key` (String) - The API key from environment variables.
|
||||
- **Returns**: `Boolean` - `true` if key is missing or is the default placeholder.
|
||||
|
||||
## 🔌 APIs & Integrations
|
||||
|
||||
| Service | Purpose | Key Variable |
|
||||
| :--- | :--- | :--- |
|
||||
| **Groq Cloud** | LLM Inference (Chatbot) | `VITE_GROQ_API_KEY` |
|
||||
| **OpenWeather** | Dashboard Weather Widget | `VITE_OPENWEATHER_API_KEY` |
|
||||
**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.
|
||||
|
||||
---
|
||||
**Created by Satyam-Rastogi for Plano Realty CRM**
|
||||
|
||||
## 🏛️ PART 1: 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 Assistant" (Chatbot)
|
||||
Our AI is not just a support bot; it is a context-aware worker that understands your business data.
|
||||
|
||||
#### For Field Agents (Workers)
|
||||
- **"Smart Querying"**: Ask *“Show me the properties built before 2000”* or *“Which homeowner wants to sell?”*.
|
||||
- **Lead Qualification**: The AI knows which leads are "Hot" and prompts you to prioritize them.
|
||||
- **Risk Analysis**: Ask *“What is the current storm risk?”* to get a breakdown of wind speeds vs. roof vulnerability.
|
||||
|
||||
#### For Customers (Homeowners)
|
||||
- **Instant Diagnostics**: (Future) Schedule inspections without waiting on hold.
|
||||
- **Project Updates**: Check the status of their roof repair.
|
||||
|
||||
#### For Guests (Website Visitors)
|
||||
- **Lead Capture**: The AI engages visitors, answers generic questions about roofing services, and encourages them to sign up or request a free estimate.
|
||||
|
||||
### 📊 The Data Dashboard
|
||||
A 360-degree view of your territory's health.
|
||||
|
||||
1. **Golden Leads Scatter Plot**: Visualizes high-value opportunities (High Value + Older Built Year).
|
||||
2. **Risk Index Gauge**: A real-time meter combining live wind speed data with the percentage of "Needs Repair" roofs.
|
||||
3. **Revenue Potential**: Bar charts showing which neighborhoods offer the highest ROI based on renovation needs.
|
||||
4. **Roof Health**: A visual breakdown of the entire territory's roof conditions (Good, Fair, Needs Repair).
|
||||
5. **Owner Intent Funnel**: Tracks the pipeline from "Willing to Sell" -> "Hot Leads".
|
||||
|
||||
---
|
||||
|
||||
## 👥 USER ROLES & DEMO ACCOUNTS
|
||||
|
||||
To explore the platform, use these pre-configured accounts.
|
||||
|
||||
### 1. Field Agent (Worker)
|
||||
*The primary user. Can view maps, access detailed property data, and manage leads.*
|
||||
- **Username/ID**: `EMP001`
|
||||
- **Password**: `password123`
|
||||
- **Role Capabilities**:
|
||||
- Access Dashboard & Widget Data.
|
||||
- View/Edit Lead Status (Hot, Cold, Customer).
|
||||
- Use Chatbot with full data context.
|
||||
|
||||
### 2. Administrator
|
||||
*The manager. Sees all agents and global stats.*
|
||||
- **Username/ID**: `ADMIN01`
|
||||
- **Password**: `adminpass`
|
||||
- **Role Capabilities**:
|
||||
- All Agent capabilities + User Management (Mock).
|
||||
|
||||
### 3. Customer (Homeowner)
|
||||
*The client. Limited view of their own property.*
|
||||
- **Username**: `john_doe`
|
||||
- **Password**: `customer123`
|
||||
- **Role Capabilities**:
|
||||
- View personal property details.
|
||||
- Request Service.
|
||||
|
||||
---
|
||||
|
||||
## 💻 PART 2: 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-2.5-32b`) injected with dynamic system prompts.
|
||||
- **Visuals**: `react-leaflet` (Maps), `recharts` (Analytics), `lucide-react` (Icons).
|
||||
|
||||
### 🧠 Deep Dive: How It Works
|
||||
|
||||
#### 1. The "Mock Store" (Data Layer)
|
||||
Located in `src/data/mockStore.jsx`. It generates ~60 realistic property records using weighted randomization algorithms to create organic-looking data distributions (e.g., 10% bad roofs, random build years).
|
||||
- **Why?**: To provide a rich, testable dataset without needing a live backend database.
|
||||
|
||||
#### 2. AI Context Injection
|
||||
Located in `src/components/Chatbot.jsx`.
|
||||
- When a user sends a message, we don't just send their text. We inject a **System Prompt** containing live dashboard metrics.
|
||||
- **Example Injection**:
|
||||
```text
|
||||
SYSTEM: You are a roofing assistant.
|
||||
CONTEXT:
|
||||
- 45 Total Properties
|
||||
- 12 Golden Leads (Top: 123 Maple Dr)
|
||||
- 8 Hot Leads needing canvassing
|
||||
```
|
||||
- This allows the AI to answer specific questions accurately.
|
||||
|
||||
#### 3. Leaflet Customization
|
||||
Located in `src/pages/Maps.jsx`.
|
||||
- We use custom SVGs overlays on the map.
|
||||
- **Reverse Geocoding**: Clicking a blank spot calls the OpenStreetMap API to fetch the address, allowing agents to "create" new property records on the fly.
|
||||
|
||||
### 🚀 Setup & Contribution
|
||||
|
||||
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`
|
||||
|
||||
**Maintained by Satyam Rastogi**
|
||||
|
||||
Reference in New Issue
Block a user