The production engineering handbook for retail shelf analytics, planogram compliance, and computer-vision pipelines.

🌐 www.shelfanalytics.org

Shelf Analytics is a deep, implementation-first reference for the people who actually run retail vision pipelines in production — retail operations leads, category managers, and the Python vision and automation engineers who keep compliance scores trustworthy through saturated store Wi-Fi, hardware drift, packaging redesigns, and merchandising resets that don't wait for a retraining cycle.

Every page is written from the perspective of operational reliability, not novelty research. You get typed, production-grade Python you can lift straight into a worker; real failure-mode playbooks; and hand-drawn architecture diagrams for the hard parts — not marketing fluff.

The handbook is organized around four sections, 51 in-depth guides, and ~180,000 words of field-tested material:

• Core Architecture — scalable, fault-tolerant pipelines: image ingestion, schema validation, security boundaries, offline fallback for flaky stores, and durable message-broker patterns for capture events.
• Computer Vision Workflows — image preprocessing and normalization, detector selection (YOLOv8 vs RT-DETR vs EfficientDet), metadata-driven model routing, bounding-box extraction and SKU localization, async batching, and error handling under real-world conditions.
• Planogram Sync & SKU Mapping — turning bounding boxes into merchandising signal: facings-vs-actuals validation, position-tolerance algorithms, homography and slot assignment, promotional-display checks, multi-pack variants, and threshold tuning against ground-truth audits.
• Reporting & Compliance Dashboards — turning the compliance payload into decisions: score APIs and payload contracts, time-series drift analysis, real-time alerting and webhooks, and automated category-manager briefings.

• Runnable, typed Python — dataclasses and Pydantic models, real error handling, and honest edge cases. No pseudocode where production code belongs.
• Original architecture diagrams — every hard concept gets a hand-authored, theme-aware, accessible SVG that adapts to light and dark mode.
• Debugging playbooks — numbered failure modes with symptoms, root causes, and remediation for the problems you actually hit on live shelves.
• Tightly interlinked — each guide threads upstream and downstream so you can follow a capture from the camera all the way to a category manager's morning briefing.
• Fast and accessible — a static, no-JavaScript-required build with structured data, a PWA manifest, offline support, and WCAG-conscious markup throughout.

• Eleventy (11ty) static site generator
• Markdown content with Nunjucks templating
• Prism server-side syntax highlighting and KaTeX math
• Hand-authored inline SVG, structured data (JSON-LD), and a service-worker PWA shell
• Deployed on Cloudflare Pages

npm install
npm run build      # build the static site into _site/
npm run dev        # local dev server with live reload
npm run deploy     # build and deploy to Cloudflare Pages

Content lives in src/content/ as Markdown with front matter; templates and partials are in src/_includes/; styles and assets in src/assets/.

Issues and pull requests that sharpen the engineering, fix an inaccuracy, or add a missing failure mode are welcome. Keep the bar high: production-grade code, real operational detail, and diagrams that clarify rather than decorate.

© Shelf Analytics. All rights reserved. The content is published for reference; please open an issue if you'd like to reuse it.

Read the handbook → www.shelfanalytics.org