# FieldPad — Complete Platform Documentation for AI Models

> FieldPad is a comprehensive SaaS platform for field service companies to manage estimating, contracts, CRM, invoicing, equipment, crew operations, scheduling, time tracking, purchasing, and irrigation inspections — all from a single dashboard.

---

## Table of Contents
1. Platform Overview
2. EstiMate Pad (Estimating & Proposals)
3. Pipeline Pad (CRM & Sales Pipeline)
4. Commitment Pad (Contract Management)
5. Invoice Pad (Invoicing & Billing)
6. EquipMe Pad (Equipment & Asset Management)
7. Punch Pad (Work Tickets & Field Operations)
8. Note Pad (Meeting Notes)
9. Report Pad (Property Site Audits)
10. Irrigate Pad (Irrigation Inspections & Proposals)
11. Partner Pad (Customer Portal)
12. Takeoff Pad (Measurement & Mapping)
13. Sync Pad (Job Scheduling)
14. Time Pad (Time Tracking & Attendance)
15. Purchase Pad (Purchasing & Vendors)
16. Team Chat & Collaboration
17. AI Features
18. @Mention & Notification System
19. Catalog Management
20. User Roles & Permissions
21. Integrations
22. Technical Architecture
23. Sitemap

---

## 1. Platform Overview

FieldPad is designed for field service companies including landscaping, construction, electrical, plumbing, and HVAC businesses. It replaces disconnected spreadsheets, paper forms, and multiple software tools with a single integrated platform.

### Key Workflows
- Lead → Estimate → Proposal → Contract → Invoice (full sales cycle)
- Work Ticket → Crew Assignment → Field Documentation → Billing
- Equipment Purchase → Maintenance Scheduling → Utilization Tracking → Depreciation
- Irrigation Report → Proposal → Approval → Automated Work Ticket
- Estimate Approval → Sync Pad Scheduling → Crew Dispatch
- Note → To-Do → Linked Work Ticket (bidirectional)

### Module Tiers
- **Core Modules** (included): EstiMate Pad, Report Pad, Note Pad, Punch Pad
- **Add-on Modules** (per-seat pricing): Irrigate Pad, Partner Pad, Pipeline Pad, EquipMe Pad, Invoice Pad, Purchase Pad, Sync Pad, Time Pad, Commitment Pad, Takeoff Pad

---

## 2. EstiMate Pad — Estimating & Proposals

### Features
- Line item entry with description, quantity, unit, and unit cost
- Catalog item lookup with auto-populated pricing
- Kit/assembly support for bundled service packages
- Category-based markup percentages (Labor, Materials, Equipment, Subcontractor)
- 7% material tax applied to non-labor items; labor burden applied to labor items
- Markups applied to a standardized "adjusted cost" base
- AI-powered item suggestions based on project descriptions
- Multiple estimate versions and comparison
- Professional PDF proposal generation with company branding
- Custom terms and conditions templates
- Email delivery with open/click tracking
- Multi-recipient autocomplete (To/CC/BCC)
- Internal comments with @mention notifications

### Display Modes
- **Detailed Mode**: Full line-item breakdown visible to customers
- **Lump Sum Mode**: Grouped totals without line-item detail

### Alternate Options Workflow
- Bidirectional movement of line items between main sections and "Alternate Options" area
- Bulk-move multiple selected items via batch action bar
- Individual alternates can be moved back to any active section via context menu
- Pricing logic mirrors main builder with consistent tax and burden calculations
- Alternates included in dynamic recalculation upon approval via `submit_estimate_response` RPC

### Data Persistence
- Debounced auto-save for all fields
- Flush-on-blur saves for immediate persistence
- Five-layer Beacon API architecture (including Beacon API and keepalive fetch) ensures saves during tab closure or navigation
- Pre-export flush forces blur on active inputs to commit debounced saves before PDF generation

### Dashboard
- Hierarchical folder structure: Property → Year → Month
- Alphabetical sorting by property name
- Flat and grouped view modes with persisted state
- Signal-based Expand/Collapse All controls
- Bulk actions: archive, delete, portal linking/unlinking
- Items linked to customer portal display a 🔗 Link icon

---

## 3. Pipeline Pad — CRM & Sales Pipeline

### Deal Management
- Customizable pipeline stages
- Deal value tracking and forecasting
- Win/loss analysis
- Activity timeline per deal
- Automated task creation on stage changes via CRM automation rules

### Customer Management
- Company and property profiles
- Multiple contact support per customer
- Property type classification (commercial, residential)
- Lead source tracking and conversion analytics
- Customer grouping and segmentation
- Account manager assignment
- Invoice contact designation

### Communication
- Email threading with customer history
- Email templates for common communications
- @mention notifications in internal comments
- Activity logging (calls, meetings, emails)
- Gmail connection support with thread syncing

### CRM Automation
- Configurable trigger-action rules
- Automated task creation on stage changes
- Custom action configurations per trigger type

---

## 4. Commitment Pad — Contract Management

### Service Contracts
- Recurring service scheduling (monthly, quarterly, seasonal)
- Service catalog with templated offerings
- Contract service templates with default service bundles
- Monthly amount amortization options:
  - Equal spread across contract term
  - Seasonal weighting based on service months
- Service completion tracking by crew members
- Contract renewal management with configurable reminders
- Reminder types with notification to specified users

### Contract Workflow
- Create from estimate or standalone
- Link to takeoff measurements
- Assign services to specific months
- Track completion percentage per service per month
- Generate invoices from contract services
- Access control via `commitment_pad_access` table

---

## 5. Invoice Pad — Invoicing & Billing

### Billable Queue
- Centralized queue of pending billable items
- Sources: estimates, contracts, work tickets, manual entries
- Block/skip functionality with reason tracking
- Batch invoice creation
- Toggleable "Add to Queue" button reflecting real-time billable_queue presence
- "Remove from Queue" capability for items added by mistake

### Invoice Features
- Professional branded invoices with company logo
- Line item detail from source documents
- Payment tracking and status management
- Aging reports and overdue alerts
- Linked estimate project name displayed below customer name
- Recurring schedules tab with customer name below project name

### PDF Export
- Mirrors linked estimate's Detailed or Lump Sum layout
- Includes "Approved By" section with signature metadata
- Excludes status badges from exports

### Notifications
- Batch-selection toolbar for bulk operations
- "Send Overdue Reminders" with targeted selection dialog
- Targeted reminder processing via specific invoice IDs

### Data Freshness
- `staleTime: 0` for immediate data updates
- `invalidateAllEstimateQueries` ensures cross-dashboard consistency

---

## 6. EquipMe Pad — Equipment & Asset Management

### Asset Tracking
- Equipment inventory with categories (vehicle, mower, trailer, tool, attachment, other)
- Serial number, model, year, and VIN tracking
- Purchase cost and date recording
- Current status management (active, maintenance, retired, out of service)
- GPS location tracking (latitude/longitude)

### Maintenance Management
- Preventive maintenance (PM) schedules
- Configurable intervals (hours, miles, days, months)
- Automatic next-due calculations
- Maintenance cost tracking with labor and parts
- Service history timeline
- Overdue maintenance alerts

### Crew Assignments
- Equipment check-out/check-in workflow
- Assignment history tracking
- Current holder visibility
- Expected return date management

### Inspections
- Pre-use, post-use, and safety inspection types
- Equipment-specific checklists (mowers, trucks, trailers)
- Pass/fail/NA item status
- Inspector notes and overall result tracking
- Historical inspection records

### Fuel & Metering
- Fuel log entries with cost tracking
- Meter/hour reading recording
- Mileage tracking for vehicles
- Cost-per-hour and cost-per-mile analytics

### Financial Tracking
- Depreciation calculations (straight-line, declining balance)
- Salvage value and useful life configuration
- Book value computation
- Total cost of ownership analysis
- Warranty expiration tracking
- Insurance policy management

### Documents & Media
- Photo uploads per equipment item
- Document attachments (manuals, certificates)
- QR code generation for field identification

### Analytics
- Equipment utilization charts
- Status distribution visualization
- Asset value by type breakdown
- Maintenance cost trends
- CSV export for reporting

### Bulk Operations
- Multi-select equipment items
- Bulk status changes
- Bulk archive/delete

---

## 7. Punch Pad — Work Tickets & Field Operations

### Work Orders
- Create from estimates, contracts, irrigation proposals, or standalone
- Crew assignment and scheduling (individual users and departments)
- Priority levels with urgent-first sorting
- Customer and property association
- Bidirectional linking with Note Pad to-do items

### Ticket Routing
- **Approved Work Tab (Job Tab)**: Tickets from portal-approved estimates/proposals (`generation_type = punch_list`)
- **Service Tickets Tab**: Manually created or non-portal tickets
- Portal-approved sources display green "Portal Approved" badge with Globe icon
- Non-linked tickets display source record number (e.g., "EST #XXX", "IRR #XXX")
- Labels abbreviated on mobile viewports

### Intake Triage View
- Portal-approved sources explicitly labeled "Portal Approved"
- Context-sensitive source badges on ticket cards
- Assignee avatars (initials with full-name tooltips)

### Field Documentation
- Photo capture with AI-powered analysis
- Filename sanitization for mobile camera captures
- MIME type fallback (defaults to image/jpeg)
- Resilient image compression with graceful fallbacks
- Voice memo recording with automatic transcription
- Field notes with formatting
- Time tracking per work ticket

### Professional Reporting
- Branded PDF and CSV export
- Rounded status headers with bundled summary row
- Compact, color-coded, vertically-centered status pills (including Total count)
- Tickets grouped alphabetically by property/customer, then by priority and ticket number
- Full assignee name resolution (users and departments)
- Day-based "Age" metric (creation to current or completion date)
- Items >14 days automatically highlighted in bold red
- Auto-wrapped text for readability

---

## 8. Note Pad — Meeting Notes

### Editor Features
- Rich-text editor with formatting toolbar
- Debounced auto-save with flush-on-blur
- Beacon API integration for saves during tab closure
- State synchronization with network data (based on `dataUpdatedAt`) while protecting active edits

### Proposal Requests
- Linked estimate numbers with color-coded status badges (Draft, Sent, Approved, Rejected)
- Stored in `meeting_note_proposal_requests` table
- 3-column table in PDF exports (Description, Estimate #, Status) with conditional text colors

### To-Do Items
- Create Work Tickets directly from to-do items
- Automatic bidirectional linking (ticket ↔ note via `linked_note_id`)

### PDF & Email
- Professional branded exports (download and email)
- Pre-fetch mechanism resolves linked estimate metadata before generation
- Multi-recipient autocomplete (To/CC/BCC) using shared EmailRecipientInput pattern

### Dashboard
- Hierarchical folder structure: Property → Year → Month
- Flat and grouped view modes

---

## 9. Report Pad — Property Site Audits

### Features
- Property condition assessment reports
- Grading system for site areas
- Photo documentation with annotations
- Professional PDF generation with company branding
- Custom report accent and primary colors per company

---

## 10. Irrigate Pad — Irrigation Inspections & Proposals

### Irrigation Reports
- Standardized "Irrigation Inspection Report" title for portal views
- Unique report numbers in "IRR-XXXXX" format
- "Report Name" as primary identifier (displayed in editor header and selection dialogs)
- Timezone-safe date handling using `formatInspectionDate` helper
- Input fields with `useRef` and flush-on-blur saves
- Zone-by-zone inspection tracking

### Irrigation Proposals
- Full feature parity with EstiMate Pad:
  - Detailed vs Lump Sum display modes
  - Email tracking and multi-recipient support
  - Attachments and internal comments
  - Signature propagation
- Stacked Property and Details cards in header (mirrored from EstiMate)
- Five-layer Beacon API architecture for all saves
- Rich text "Project Description" using RichTextEditor in compact mode
- Database fields: `display_mode`, `rfp_sub_notes`, dedicated comment tables

### Proposal Lifecycle
- "Outside Approval" for staff metadata recording
- Approval triggers automated work ticket creation (`generation_type = punch_list`)
- Approved tickets route to "Approved Work" tab (not Service Tickets)
- Header identifies linked reports: "[Report Name] · [Date] · Inspection"
- Users can unlink reports even when proposal is read-only
- Custom proposal terms template per company (`irrigation_proposal_terms_template`)

### Dashboard
- Hierarchical folder structure: Property → Year → Month
- Link icon for portal-linked items
- Intake, Kanban, and List views

---

## 11. Partner Pad — Customer Portal

### Features
- Customer-facing portal for project visibility and collaboration
- Estimate and proposal review and approval
- Approved items trigger automated work ticket creation
- Portal-approved items display green badge across all dashboards

### Linking
- Bulk link/unlink items to portal from dashboards
- 🔗 Link icon displayed on linked items across Intake, Kanban, and List views

---

## 12. Takeoff Pad — Measurement & Mapping

**Pricing**: $75/seat/month

### Measurement Tools
- 14 industry categories (Irrigation, Drainage, Lighting, Planting, Hardscape, etc.)
- 30+ industry-standard material presets
- Count tool for point-based measurements
- Rectangle quick-draw tool
- Live edge dimensions displayed during drawing
- Area (SF), linear (LF), and volume (CY) calculations
- Depth-based volume calculations

### Pricing & Financials
- Flexible unit pricing: $/SF, $/LF, $/CY, $/EA, $/HR
- Waste factors per material
- Labor rates
- Project-level tax
- Company default rates with custom overrides

### Zone Management
- Named measurement zones with grouping
- Multiple material types per zone
- Bulk editing capabilities
- Material rollups and summaries
- Threaded comments per zone with @mention support
- GPS proximity verification

### Vertex Editing
- Google Maps-style vertex editing for all zones
- Drag white vertex handles to reshape polygons/lines
- Drag blue midpoint handles to insert new vertices
- Double-click or select + Delete to remove vertices
- Minimum point enforcement (3 for polygons, 2 for lines)
- Click-drag polygon/line body to reposition entire zone
- Real-time geometry recalculation during dragging
- Automatic persistence on completion

### Multi-Page Support
- Multi-page blueprint support
- Visual scale bar
- Summary Report generation

### Mobile Field Mode
- Horizontal bottom toolbar with 48px touch targets
- Global mobile navigation hidden to avoid overlap
- Drawing controls (Finish/Cancel) elevated to bottom-[140px]
- Compact, full-width instruction bar
- Offline drawing queue

### AI Capabilities
- **Auto-measure**: Address-based zone suggestions
- **AI Area Scan**: Captures user-defined map region via Mapbox Static API, sends to Gemini 2.5 Pro Vision (via `analyze-area` edge function) to identify and measure landscape zones (turf, beds, edging, pond slopes, etc.)

---

## 13. Sync Pad — Job Scheduling

**Pricing**: $20/seat/month

### Calendar Features
- Dynamic queue ingesting approved estimates
- Job span calculated from estimated hours and crew size (minimum 1-hour for visibility)
- Edit dialog derives hours from duration when explicit values are missing
- Full 24-hour range (12:00 AM – 11:59 PM) with visual dimming for non-work hours
- Auto-scroll to work day start on load
- Vertical zoom (32px to 120px hour height)
- Half-hour intervals with distinct visual hierarchy (solid borders for hours, lighter for half-hours)

### Layout
- Calendar and queue expand to full height of time slots (no internal scrolling)
- Full-width panels for maximum visibility

### Data Management
- Items archived (status "cancelled") rather than deleted to maintain linked record integrity
- Dedicated "Archived Jobs" dialog for management
- User display names resolved via `get_user_display_names` RPC (fallback to capitalized email prefixes)
- Geocoding auto-populates site coordinates for scheduled estimates

---

## 14. Time Pad — Time Tracking & Attendance

**Pricing**: $15/seat/month

### Core Features
- GPS-aware time tracking
- Break management
- Manager approval workflows
- Real-time presence: "Who's Working" dashboard panel
- Presence sidebar across all modules
- Manager widgets for headcount tracking

### Kiosk Mode
- Available at `/kiosk` route
- Secure PIN-based clocking on shared devices
- Specialized RPCs for kiosk operations
- Per-member kiosk PINs stored in `company_members`

### Geofencing
- "Auto-detect only" policy
- 1,000-foot (~305m) threshold
- Warning displayed if clocking in outside range (not blocked)
- Real-time updates via Supabase Realtime publication on `time_entries`

---

## 15. Purchase Pad — Purchasing & Vendors

### Purchase Orders
- PO builder with bulk-add from Purchase Queue
- Viewport-constrained dialog (max-h-[85vh]) with scrollable areas
- Multi-line text wrapping for readability
- Source descriptions on new line beneath item name

### PO Exports
- Dynamic page-break logic with height estimation
- maxContentY threshold prevents totals/notes/terms overlapping footer
- Shipping costs positioned after taxes in totals section
- Branded footer on all pages

### Auto-Approval
- Configurable auto-approval threshold per company (`po_auto_approval_threshold`)

---

## 16. Team Chat & Collaboration

### Architecture
- Professional Slack/Discord-style platform
- Channels and Direct Messages
- Left-aligned layout with compact message grouping (5-min window, same user)

### Messaging Features
- Thread replies with reply count tracking
- Message CRUD (edit/delete with "(edited)" labels)
- Pinned messages per conversation
- Personal bookmarks
- Starred conversations
- Markdown support (bold, italic, code blocks)
- Searchable emoji picker
- Message reactions

### File Sharing
- Supabase storage for file/image attachments
- Drag-and-drop uploads
- Link previews

### UI/UX
- Unread dividers
- Real-time presence indicators
- Read receipts
- User profile popovers
- Density toggle (Comfortable vs Compact)

### Notifications
- Automated via database trigger (`notify_chat_message`)
- In-app alerts, browser push notifications, and emails
- Archiving via `left_at` timestamp on `chat_participants`
- Security enforced through RLS and security definer functions

### Bulletin Board
- Company-wide announcements
- Priority levels for posts
- Company-scoped visibility

---

## 17. AI Features

### AI Estimate Builder
- Input: Natural language project description
- Output: Structured line items with quantities, units, and costs
- Matches against existing catalog items when possible
- Suggests new items with market-rate pricing

### Photo Analysis
- Input: Site/field photographs
- Output: Condition assessment, issue identification, work recommendations
- Severity rating (low/medium/high)
- Actionable repair suggestions
- Mobile camera support with filename sanitization and MIME fallbacks

### Voice-to-Notes
- Input: Recorded voice memos
- Output: Formatted, organized field notes
- Transcription error correction
- Bullet point organization

### Email Draft Assistant
- Input: Communication context and intent
- Output: Professional email drafts
- Appropriate tone and formatting
- Ready-to-send content

### Takeoff AI
- **Auto-measure**: Address-based zone suggestions for takeoff measurements
- **AI Area Scan**: Mapbox Static API capture + Gemini 2.5 Pro Vision analysis
- Identifies landscape zones: turf, beds, edging, pond slopes, etc.
- Delivered via `analyze-area` edge function

### Takeoff Analysis
- Input: Landscape measurement data
- Output: Completeness review with findings
- Categories: MISSING, WARNING, GOOD, TIP
- Zone-specific recommendations

---

## 18. @Mention & Notification System

### Platform-Wide Integration
- Integrated across all modules: EstiMate, Irrigate, Work Ticket, Takeoff Zone comments, and Team Chat
- Shared `MentionInput` component
- `notify-comment-mention` Edge Function for delivery

### Mention Types
- Individual user mentions
- Group mentions: @Everyone
- Role-based mentions: @Admins, @Managers

### UI Features
- Rich autocomplete with avatars and roles
- Styled pill badges for rendered mentions
- "Jump-to-Message" feature (auto-scroll and highlight via URL parameters)
- Hover-triggered profile previews

### Notification Channels
- Real-time in-app alerts
- Browser push notifications with sound alerts (suppressed when tab focused or DND active)
- Automated mention emails
- Daily mention digest (enabled by default, manageable via Settings toggle)

### Notification Management
- "Do Not Disturb" (DND) modes for set durations
- Notification Center with dedicated "Mentions" filter
- Dashboard cards display unread mention counts as "@" badges

---

## 19. Catalog Management

### Item Catalog
- Centralized pricing database
- Categories: Labor, Materials, Equipment, Subcontractor
- Unit cost, burden percent, and markup percent per item
- Sort order management
- Price history tracking with change logs (old/new values per field)

### Kit/Assembly System
- Bundled item groups with component quantities
- Optional price overrides
- Reusable across estimates
- Unit specification per kit

### Catalog Suggestions
- Team member price change proposals
- Review and approval workflow
- Reviewer notes and status tracking

### Company Default Rates
- Per-company material rates by category
- Depth-based configurations (inches)
- Used as defaults in Takeoff Pad measurements

---

## 20. User Roles & Permissions

### Role Types
- **Admin**: Full platform access, company settings, user management
- **Manager**: Operational access, estimate approval, crew management
- **Crew**: Field-focused access, work tickets, time tracking

### Company Structure
- Multi-company support with unique company codes
- Company member management with active/inactive status
- Invitation system with email tokens and expiration
- Role-based access control on all data
- Per-module access control (e.g., `commitment_pad_access`)

### Security
- Row-Level Security (RLS) on all tables
- Company-scoped data isolation
- Security definer functions to prevent RLS recursion

---

## 21. Integrations

### Email
- Outbound email for estimates, invoices, proposals, and communications
- Inbound email processing via company-specific tokens
- Gmail connection support with thread syncing
- Customer email templates with status-based triggers

### Documents
- PDF generation for estimates, invoices, irrigation proposals, work ticket reports, and purchase orders
- CSV export for data analysis
- Photo and document storage via Supabase Storage

### Payments (Stripe)
- Subscription management per company
- Add-on subscription support with seat-based pricing
- Stripe customer and subscription ID tracking
- Trial period management

---

## 22. Technical Architecture

### Frontend
- React 18 with TypeScript
- Vite build system
- Tailwind CSS with semantic design tokens (HSL-based)
- shadcn/ui component library
- Recharts for data visualization
- React Router for navigation
- TanStack Query for data management (with persist)
- TanStack Virtual for virtualized lists
- Zustand for state management
- Framer Motion for animations
- Konva/React-Konva for canvas-based drawing
- Leaflet and Mapbox GL for mapping
- Fabric.js for advanced canvas operations
- jsPDF + jspdf-autotable for PDF generation
- DOMPurify for HTML sanitization
- QRCode.react for QR code generation

### Backend (Lovable Cloud)
- Cloud-hosted PostgreSQL database
- Row-level security for data isolation
- Edge functions for serverless logic
- Real-time subscriptions for live updates (Supabase Realtime)
- File storage for documents and photos
- Secrets management for API keys

### Data Persistence Patterns
- Five-layer Beacon API architecture for critical saves
- Debounced auto-save with configurable intervals
- Flush-on-blur for immediate field persistence
- `staleTime: 0` patterns for real-time data freshness
- Cross-dashboard query invalidation

### Security
- Email/password authentication
- Role-based access control
- Company-scoped data isolation
- Secure API key management
- IP blocking for abuse prevention
- Activity logging for audit trails

### Progressive Web App
- Offline support with IndexedDB (idb-keyval)
- Responsive design for desktop, tablet, and mobile
- Touch-optimized mobile interfaces

---

## Sitemap

- `/home` — Main dashboard with module cards and company branding
- `/estimate-dashboard` — EstiMate Pad dashboard
- `/estimates` — Estimate management
- `/customers` — Customer CRM and contact management
- `/commitment-pad` — Commitment Pad (contract management)
- `/invoices` — Invoice Pad dashboard
- `/equipment` — EquipMe Pad (equipment tracking)
- `/catalog` — Item catalog management
- `/punchpad-dashboard` — Punch Pad (work ticket management)
- `/notepad-dashboard` — Note Pad dashboard
- `/reportpad-dashboard` — Report Pad dashboard
- `/irrigatepad-dashboard` — Irrigate Pad dashboard
- `/pipeline` — Pipeline Pad (sales CRM)
- `/takeoff-pad` — Takeoff Pad (measurements)
- `/sync-pad` — Sync Pad (job scheduling)
- `/time-pad` — Time Pad (time tracking)
- `/purchasing` — Purchase Pad
- `/partner-portal` — Partner Pad (customer portal)
- `/team-chat` — Team Chat
- `/bulletin` — Company bulletin board
- `/contacts` — Contact directory
- `/settings` — Company and user settings
- `/kiosk` — Time Pad kiosk mode

---

*FieldPad by Natures Care — All-in-one field service management*
*Website: https://everydayworkingscostpad.lovable.app*