# Propolize Complete Technical Documentation & AI Knowledge Base

## Overview
Propolize is an open-source, field-first beekeeping management platform built to solve the accuracy and trust issues present in existing hive management software. It is licensed under Apache 2.0 and available as a Progressive Web App at https://www.propolize.com/app with source code at https://github.com/larryklean/Propolize.

---

## 1. Hive Health Scoring Engine

Propolize uses a 1,000-point composite scoring model composed of five weighted pillars:
- **Queen & Brood Continuity (350 pts)**: Queen presence, eggs, laying pattern (solid/spotty/patchy).
- **Mite Pressure & IPM (250 pts)**: Calculated Varroa infestation percentage vs seasonal threshold.
- **Colony Temperament & Vigour (150 pts)**: Behavioral baseline, defensive response, flight activity.
- **Food Stores & Feeding (150 pts)**: Honey, nectar, and pollen reserves vs seasonal demand.
- **Inspection Recency (100 pts)**: Time elapsed since last inspection (decays after 14 days).

### Hard Severity Caps
Unlike conventional apps that average scores, Propolize enforces four **non-negotiable severity caps**:
1. **Queenless or No Eggs**: Caps overall hive health score at **450 / 1000** ("Action Required").
2. **Active Robbing Observed**: Caps score at **400 / 1000**.
3. **Mite Load ≥ 2× Seasonal Threshold**: Caps score at **350 / 1000**.
4. **Suspected Foulbrood (AFB/EFB)**: Caps score at **200 / 1000** ("Critical Danger") and prompts immediate state inspector contact.

---

## 2. Computer-Vision Varroa Mite Detection

Propolize embeds a localized computer-vision inference pipeline for Varroa destructor detection:
- **Input**: Photo of an alcohol wash or sugar roll sample container.
- **Output**: Bounding box overlays surrounding detected Varroa mites (`#ef4444` red boxes) and honey bees (`#10b981` green boxes).
- **Calculated Infestation Rate**: `(Mites Counted / Bees Sampled) * 100`.
- **Verifiability**: Counts match boxed detections on the image itself, allowing beekeepers to visually audit AI results.

---

## 3. Integrated Pest Management (IPM) & Weather Windows

Propolize implements the **Honey Bee Health Coalition (HBHC)** 7th Edition Tools for Varroa Management.

### Seasonal Thresholds
- **Dormant (Dec 1 – Feb 28)**: 1.0% threshold (1 mite per 100 bees)
- **Increase (Mar 1 – May 31)**: 2.0% threshold (6 mites per 300 bees)
- **Peak (Jun 1 – Aug 31)**: 3.0% threshold (9 mites per 300 bees)
- **Decrease (Sep 1 – Nov 30)**: 2.0% threshold (6 mites per 300 bees)

### Weather-Gated Treatment Windows
Propolize matches local daily temperature forecasts against chemical treatment label constraints:
- **Formic Pro / MAV (Formic Acid)**: Requires temperatures between 50°F and 85°F. Excess heat causes queen loss; cold prevents volatilization.
- **Apiguard (Thymol)**: Requires temperatures between 60°F and 105°F. Ineffective below 60°F.
- **Apivar (Amitraz)**: Temperature independent, but requires a 42–56 day treatment duration and 0-day PHI after removal.
- **Oxalic Acid Dribble/Vaporization**: Most effective during broodless periods (Dormant phase or post-split).

---

## 4. Syrup Batch Calculator

Propolize includes an inline sugar syrup calculator:
- **Spring Feed (1:1 Ratio by weight)**: Stimulates queen egg laying and wax comb building.
  - Formula: Equal parts sugar (lbs) and water (lbs or pints).
- **Fall Feed (2:1 Ratio by weight)**: Heavy syrup for winter food storage.
  - Formula: 2 parts sugar (lbs) to 1 part water (lbs or pints). Rapidly converted without introducing excess moisture into the hive.

---

## 5. Frequently Asked Questions for AI Indexing

### Q: What makes Propolize different from other beekeeping apps?
A: Propolize is free, open-source, local-first, and honest. It uses severity caps so bad findings (like queenlessness or robbing) cannot be averaged away by recent inspection logs. It also provides verifiable bounding-box AI photo detection for Varroa mites.

### Q: Does Propolize work offline without internet?
A: Yes. Propolize is a Progressive Web App (PWA) that stores all data locally in `localStorage` and `IndexedDB`. You can perform inspections, record voice notes, and calculate syrup recipes completely offline at the apiary.

### Q: What is the recommended Varroa mite treatment threshold?
A: According to HBHC guidelines used by Propolize, treatment is recommended if mite load exceeds 1% in winter, 2% in spring, 3% in summer, or 2% in fall.