# Plano Realty CRM - Field Service & Sales 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.

## 🚀 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` |

---
**Created by Satyam-Rastogi for Plano Realty CRM**