Wickham Roofing AI Pipeline — V4 "Wickham Roofing CRM"

The Wickham Roofing AI Controller (V4 "Wickham Roofing CRM") is a proprietary, local-first operational platform designed to automate insurance roofing production from field lead intake to financial ledger reconciliation.

Engineered to operate entirely offline or via zero-cloud tunneling directly from field office hardware, V4 completely eliminates third-party SaaS dependency by orchestrating deterministic insurance math, forensic AI roof analysis, automated paperwork matrices, and QuickBooks Online (QBO) invoice exporting over a self-healing SQLite state machine.

┌─────────────────────────────────────────────────────────────────────────────┐
│                       WICKHAM ROOFING "WICKHAM ROOFING CRM"                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  FIELD OPERATIONS (Mobile SPA via Cloudflare/Ngrok Tunnel)                  │
│  ┌──────────────┐      ┌──────────────┐      ┌───────────────────────────┐  │
│  │ Lead Intake  │ ───► │ Offline-First│ ───► │ Cryptographically Hashed    │  │
│  │ & Signatures │      │ IndexedDB    │      │ EagleView & Photo Uploads │  │
│  └──────────────┘      └──────────────┘      └───────────────────────────┘  │
│          │                                                  │               │
│          ▼                                                  ▼               │
│  OFFICE & TECHNICAL CONTROL PANEL (Local Uvicorn Dashboard)                 │
│  ┌──────────────┐      ┌──────────────┐      ┌───────────────────────────┐  │
│  │ Real-Time    │ ───► │ Deterministic│ ───► │ Automated Climate Gating  │  │
│  │ Margin Gate  │      │ SoL / EV Math│      │ & Manual Review Overrides │  │
│  └──────────────┘      └──────────────┘      └───────────────────────────┘  │
│          │                                                  │               │
│          ▼                                                  ▼               │
│  THE PAPERWORK & ACCOUNTING MATRIX (ReportLab & QBO Export Engine)          │
│  ┌──────────────┐      ┌──────────────┐      ┌─────────────┐  ┌──────────┐  │
│  │ Supplier POs │      │ Statutory GA │      │ QBO Invoice │  │ 1099 Rep │  │
│  │ & Estimates  │      │ Compliance   │      │ CSV Export  │  │ Ledger   │  │
│  └──────────────┘      └──────────────┘      └─────────────┘  └──────────┘  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

The system isolates operational data across four distinct user roles, authenticated via secure, database-hashed (bcrypt) 4-digit PINs and signed with symmetric algorithm-confineable (HS256) JSON Web Tokens (JWTs):

1. Field Canvassers (verify_field): Mobile SPA interface scoped via strict IDOR boundaries (assert_field_rep_owns_job). Allows canvassers to input leads, collect HTML5 canvas client signatures offline, upload EagleView reports, and view only their personal commission statements.
2. Operations & Production (verify_operations): A streamlined, read-only departure board allowing production managers to oversee installation schedules, material orders (MaterialBOM), and toggle site material flags (materials_ordered, materials_on_site).
3. Accounting Ledger (verify_accounting): Full financial oversight across all jobs. Empowers financial staff to record Actual Cash Value (ACV) and Supplement check payments, adjust manual commission percentage overrides per job, and perform atomic QuickBooks Online (QBO) CSV invoice exports.
4. Admin Technical Control Panel (verify_admin): Comprehensive triage and pipeline oversight. Enables administrators to review and resolve AI calculation flags, manage field rep onboarding/identities, trigger emergency state machine bypasses, and monitor background queue telemetry.

To ensure real-world financial accuracy, the pipeline strictly separates mathematical calculations from artificial intelligence reasoning.

• SupplementEngine: An isolated pure-Python mathematical kernel that reconciles EagleView physical dimensions against carrier Statements of Loss (SoL) without AI guesswork.
• Universal Claim AST: Pydantic V2 schemas that mathematically prove carrier RCV/ACV totals and enforce strict SHA256 provenance tracking before triggering document synthesis.
• Climate Zone Gating: Automates statutory building code enforcement (e.g., Ice & Water Shield rules in northern climates vs. Georgia municipal codes) using zero-cost RAG databases.

• In-Memory Sliding Window Rate Limiter: Protects computationally expensive ARQ job enqueuing endpoints against accidental or malicious queue flooding.
• Self-Healing Realtime WebSockets: Automated frontend reconnect logic coupled with server-side active background heartbeat loops instantly sweeps dead client sockets.
• Path Traversal & IDOR Defense: All document download endpoints apply rigorous cryptographic hashing and filename sanitization (sanitize_download_filename).

Field reps can now capture minimal lead data (name, address, phone) at the door without requiring an immediate signature or photos. The system stores the lead as LEAD_CAPTURED, keeping it visible to the core team without clogging the active production pipeline.

• Resume & Sign: From My Recent Jobs, reps tap ✍️ Resume & Sign to re-open the intake form pre-populated with saved data and walk through the full contingency agreement for on-the-spot or follow-up signing.
• Unsigned Agreement PDF: Reps can download or email the homeowner a printable unsigned contingency agreement directly from the job card — no office visit required.
• Evidence Grid Pitch Tool: The Inspection Evidence Grid PDF (storm findings, hail impacts, weather data) is accessible directly from the job card, enabling reps to present objective storm damage proof before asking for the signature.

• Windows, macOS, or Linux machine with Python 3.11+ and Git installed.
• Redis broker (optional for local simulation; automated via Docker/WSL in boot scripts).

# Clone repository
git clone https://github.com/blairmichaelg/wickham_crm.git
cd wickham_crm

# Provision virtual environment
python -m venv venv
.\venv\Scripts\activate          # Windows PowerShell
# source venv/bin/activate         # Linux / Mac Bash

# Install strict dependency requirements
pip install -r requirements.txt

Copy the supplied template and inject your Gemini API credentials:

cp .env.example .env
# Open .env and enter your valid GEMINI_API_KEY

Validate system stability against the 262-test verification matrix before firing the application engines:

# Execute comprehensive automated test matrix
python -m pytest tests/ -v

# Run local development server (Port 8000)
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

If you need the CRM in a completely clean, empty-job state for a presentation, run the built-in reset script before starting the stack:

python scripts/db_demo_reset.py

This clears all jobs, resets the demo database to a pristine state, removes uploaded artifacts from the document directories, and restores the default demo field rep Jerry Grubb with PIN 1111.

Comprehensive operator manuals and operational runbooks are maintained directly within the docs/ folder:

• Accounting Guide: Ledger instruction manual for check tracking, commission adjustments, and QBO invoice exporting.
• Operations Guide: Schedule and material flag instructions for production dispatchers.
• Canvasser Field Guide: Mobile SPA training manual for field personnel.
• Admin & Technical Guide: Master triage, rep administration, and emergency override procedures.
• Field Runbook: Emergency troubleshooting playbook for connectivity or state machine issues during live deployment.
• Security Architecture: Authorization boundaries and Phase 3 cryptographic security specifications.

Proprietary Software — Copyright © 2026 Wickham Roofing LLC.
All rights reserved. Unauthorized reproduction, adaptation, distribution, or decompilation of this software, or any portion thereof, is strictly prohibited without explicit authorization from Wickham Roofing LLC.