feat: Release CRM V2 (Clean History)

Squashed commits for V2 release including Dark Mode, Chatbot, and Landing Page enhancements.
2026-02-01 03:49:20 +05:30
commit 8a749d3041
42 changed files with 12518 additions and 0 deletions
@@ -0,0 +1,112 @@
+# 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.
+
+## 📚 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 Antigravity for Plano Realty CRM**