What this is
Canary LP is a loss-prevention analytics platform for Square merchants. It ingests every webhook event Square emits — payments, refunds, voids, discounts, cash drawer events, timecards, inventory adjustments — and evaluates them against 37 detection rules across ten categories. When patterns look wrong, Canary raises alerts in plain English and opens a forensic case with a hash-chained evidence trail.
The platform is built on a canonical data model (the CRDM) that descends from three generations of enterprise loss-prevention systems — Tesco's TDS, Walmart International's SMART System, and Canary itself. The Square integration is the reference implementation, not the product; the canonical layer is source-agnostic and designed to absorb any POS.
The 15-minute tour
In order, the shortest path from "never heard of Canary" to "I could ask a real question about it":
Minutes 0–2 · The Mermaid Atlas
Open the Atlas. Skip straight to the Infrastructure category (fig I-01, I-02, I-03) — Docker stack, database schema, network topology. You'll see one Postgres with three schemas, Valkey for streams + cache, Ollama for embeddings, and where each service lives. Then glance at Pipeline Internals (fig P-00 through P-07) — the Triple Subscriber Pipeline end-to-end.
Atlas is 52 diagrams. Don't try to read them all; just build a shape in your head.
Minutes 2–7 · The CRDM
Open The CRDM. Read §1 (Provenance), §2 (Seven Canonical Data Sources), and §3 (Evidence Chain). Skim §4 (Chirp Detection Registry).
The big idea: you see the same seven data domains in every retail LP system ever built, and the CRDM maps Square's API to those domains with explicit coverage percentages. "Enterprise DNA, SMB integration."
Minutes 7–10 · The Field Registry
Open The Field Registry. Use your browser's find-in-page. Search for a table you care about — transactions, alerts, fox_cases. Every column has a label, description, type, searchable flag, and i18n key.
This is the metadata layer that feeds Owl natural-language search, UI rendering, and the OpenAPI contract. It's the most boring part of the system, and also the most important — everything downstream depends on it being correct.
Minutes 10–13 · The Detection Catalog
Open The Detection Catalog. Skim the tier headers: Tier 1 (stateless, microsecond), Tier 2 (stateful aggregates), Tier 3 (composite). Pick one rule from each tier and read its default threshold.
Notice: C-001 (Rapid Refund — 15 min window) is a single-event evaluation. C-002 (Excessive Refund Rate) needs a shift-level aggregation. C-801+ composite rules correlate primary hits. All three tiers run in the same pipeline, and merchants can tune any threshold via merchant_rule_config.
Minutes 13–15 · The Prototype
Open the prototype. This is the original product concept — a clickable UI that shows the design intent: sidebar, dashboard, alerts list, Fox cases, Owl chat, Goose wallet. No backend, no real data, just the shape of what the app is.
If you want to see it running with real sandbox data, the Launch Demo button on any library page goes to the live application.
Pick a path by interest
The five tiles in the library aren't sequential — pick what matches what you're evaluating:
Evaluating for a merchant integration
Start with the CRDM (data shape) → Field Registry (field-level detail) → API (endpoints you'll call).
Evaluating the architecture
Start with Architecture (end-to-end walkthrough) → Atlas (visual backup) → the Infrastructure and Pipeline SDDs via the Atlas cross-references.
Evaluating the detection logic
Start with Detection Catalog (the rules) → Risk Dictionary (z-score queries over the rule output) → Atlas category D (decision trees).
Evaluating case management
Start with Atlas figure L-03 (Case Lifecycle) → Fox case schema in Field Registry → CRDM §3 (Evidence Chain).
Evaluating the data platform itself
Start with Field Registry (every table, every column) → CRDM (the lineage story) → Atlas figure I-02 (Database Schema Architecture).
Sources of truth
Every document in this library is generated from or verified against live source:
- Atlas — 52 Mermaid SVGs from
Canary/docs/atlas/ - CRDM — authored narrative; the lineage sections are hand-written history
- Field Registry — rendered from
Canary/docs/field-registry.md(generated from SQLAlchemy models) - Detection Catalog — AST-parsed from
canary/services/chirp/rule_definitions.py - Risk Dictionary — AST-parsed from
canary/services/risk_dictionary.py - API — Redoc rendering
canary-api-v1.yaml(OpenAPI 3.0.3, audited againstapp.url_map)
If a library doc drifts from reality, it's a build-script bug, not a writing bug. Re-run the generator.
Contact
If something in this library is unclear or wrong, email gclyle@growdirect.io. The library is treated like code — issues get filed, fixes get shipped.