Design Documents

60 SDDs across 12 domain groups. Start at 01 if you're new to the codebase — 01–04 are the orientation set.
Source: GrowDirect/docs/sdds/go-handoff/

01	Platform Overview platform-overview.md product	What Canary is and who it serves. Covers the ICP (independent specialty retailer, 1–30 locations), the three accountability rails, the module roadmap, and the security and compliance posture. Narrative layer — read before the architecture SDD.
02	Architecture architecture.md platform	Service topology across 29 modules. Chi HTTP, pgx/v5, Valkey streams, GCP Cloud Run. Shows how the protocol pipeline (Node 1–4), the module stores, and the MCP surface hang together. Start here for the wiring picture.
03	Microservice Architecture microservice-architecture.md platform	Inter-service communication contracts, Valkey stream event schemas, error handling conventions, and the audit middleware contract. How 29 services stay consistent without tight coupling.
04	Go Module Layout go-module-layout.md conventions required	Read before creating any file. Defines the single go.mod, package naming, service boundary conventions, port assignments, and cmd/* binary layout. Consistency across 29 services is enforced here.

05	Canonical Data Model canonical-data-model.md data active	ARTS-anchored, SMB-2030 scoped master data contract. Nine domains: Item, Customer, Transaction, Inventory, Receiving, Party, Finance, Operations, Device. 65 designed entities across 11 schemas. GSLM provenance from Walmart International. The schema all services write against.
06	Canonical Data Model — Delta canonical-data-model-delta.md data	What changed from data-model.md v0 to canonical-data-model.md v1, and why. Tracks additions, removals, renames, and the rationale for each. Read alongside the main CDM spec when auditing schema changes.
07	Canonical Data Model — Party Edits canonical-data-model-party-edits.md data proposed	GRO-734 party identity edits to the canonical data model. Apply after design review — proposed, not yet merged into the main CDM spec.
08	Canonical Data Model — Portability Review canonical-data-model-portability-review.md data	Audits the 65-entity canonical model for cloud provider lock-in. Confirms GCP-targeted architecture can exit without a schema rebuild — "target GCP, don't get hostage to it."
09	Data Model (v0) data-model.md legacy	Cross-schema reference document from the pre-CDM era. The original PII map anchor. Reference only — superseded by canonical-data-model.md for all new work.

10	Identity identity.md auth	Merchant identity and the tenant model. API key auth for agent clients, federated identity path via GCP Cloud Identity. Covers the company_alias namespace, source_code scoping, and the .jeffe namespace registration flow.
11	RaaS — Resolution as a Service raas.md auth	Namespace authority for the platform. Assigns canonical merchant identity tokens (raas:{merchant_id}), manages the source_code registry, and provides resolution services across all POS integrations.
12	External Identities external-identities.md auth	Square OAuth and NCR Counterpoint external identity adapters. Different protocols, same outcome: stable Canary-native identifiers from external POS sources.
13	Party Identity & Householding party-identity-design.md data	Party resolution, fingerprinting, and householding. Matches anonymous payment identities to customer records without relying on the POS to stitch them. Required when Canary is the sole intelligence layer above the POS.
14	Settings settings.md platform	Configuration substrate for every other Canary module. An internal integration layer, not a standalone service — all merchant and system configuration reads flow through this domain.
15	Field Capture field-capture.md ingestion	Maps arbitrary inbound field names to canonical Canary field registry names. The translation layer at the intake boundary — keeps the canonical model clean regardless of upstream POS naming conventions.

16	Webhook Pipeline webhook-pipeline.md ingestion live	Node 2 of the protocol pipeline. HMAC-SHA256 validation, nonce replay protection, payload hash computation, publish to Valkey stream. The front door for all external events (POS, Square, DriftPOS).
17	TSP — Transaction Stream Processor tsp.md pipeline live	Four-stage pipeline overview: seal → parse → Merkle batch → detect. Each stage is an independent consumer group on the Valkey stream. Read this SDD first, then the four stage-specific specs (18–21) when working on a stage.
18	TSP Stage 1 — Hash & Seal tsp-seal.md pipeline	Transforms raw POS events into sealed, hash-anchored stream messages. Single responsibility: non-repudiation of every inbound event before it touches any domain logic.
19	TSP Stage 2 — Parse & Route tsp-parse.md pipeline	Translates sealed stream messages into canonical events and routes to domain consumers. Produces a structured payload for domain services and a source-attributed record for the Merkle batcher.
20	TSP Stage 3 — Merkle Batcher tsp-merkle.md pipeline	Converts a stream of sealed event hashes into a compact, cryptographically verifiable commitment. The ordinal anchor is the Evidentiary rail in code — hash batch on-chain, individual hashes stay off-chain.
21	TSP Stage 4 — Chirp Detection tsp-detect.md pipeline	The detection engine that evaluates every canonical transaction event against the full Chirp rule set. Routes exceptions to hawk case management. Stage 4 is where sealed events become actionable intelligence.

22	Chirp Detection Engine chirp.md detection	37 detection rules across 10 categories. Rule threshold tuning, alert routing to hawk case management, and the reserved ILDWAC cost-anomaly rule family (Category 11). The signal layer of the Operational rail.
23	Alert alert.md detection	Terminal consumer of the detection pipeline. Chirp writes alert rows; Alert owns routing, delivery SLAs, acknowledgement, and lifecycle management. The operator-facing surface of the detection engine.
24	Fox — Case Management & Evidence Locker fox.md detection	Bridges automated anomaly detection to human review. "The Vault" — a case carries the full evidence trail: triggering alert, sealed event chain, attached media, and investigator notes.
25	Hawk — Square Adapter & Incident Cases hawk-case-management.md detection integration	Square POS adapter and incident-typed case management. Extends Fox with transaction-aware cases for Square-sourced events. Reference implementation of the POS adapter substrate alongside Bull (NCR).

26	POS Adapter Substrate pos-adapter-substrate.md integration required	The substrate that makes Canary genuinely multi-POS. Defines the interface all POS integrations implement — current (Square, NCR Counterpoint) and future. Swap the adapter; keep the platform.
27	Bull — NCR Counterpoint Adapter bull.md integration	Reference implementation of the POS adapter substrate for RapidPOS / NCR Counterpoint REST API. Covers Distribution Intelligence Layer event mapping and the Counterpoint auth model.
28	Multi-POS Architecture Proof multi-pos-architecture-proof.md integration	Demonstrates adapter pattern isolation and canonical event conversion across Square and NCR. Proof that the abstraction layer holds — same detection pipeline regardless of POS source.

29	MCP Service Junctions mcp-service-junctions.md mcp live	28 MCP tools across 7 domain modules (alert, analytics, asset, customer, employee, returns, report). The junction inventory — every event traverses here, which is also where billing and the evidentiary record are created. The agent interface to the platform.
30	DriftPOS Integration Contract driftpos-integration.md integration	CAN-DESIGN-001. Wire protocol between Canary and RapidPOS (DriftPOS). 47 endpoints across 9 domains, 38 ARTS-aligned wire entities. The primary channel delivery spec for the VAR partnership.
31	Landed Cost Rollup satoshi-cost-rollup.md billing	Go types, database schema, calibration loader, metering pipeline, and settlement choreography for per-event metered billing. Every junction traversal pays a toll; the payment IS the audit record.
32	Blockchain Anchor blockchain-anchor.md billing	Publishes RaaS chain hashes and ILDWAC RIB batch seals to a cryptographic ledger. The S4 permanence tier — merchant holds the S3 encryption key, Canary holds the ciphertext, the ledger holds the hash.
33	ILDWAC — Provenance-Weighted Cost ildwac.md billing	Item × Location × Device × MCP × Port × Weighted Average Cost. Provenance-weighted cost model for per-event billing. Five dimensions that replace the seat-pricing conversation with a verifiable cost-to-serve.
34	L402-OTB — Open-to-Buy Enforcement l402-otb.md billing	L402 payment-gated purchase authorization. Enforces open-to-buy budgets at the protocol level — the Financial rail in code. Budget exhaustion blocks purchase requests cryptographically.
35	Feed-Tier Contract feed-tier-contract.md integration	Buildable spec for the cadence ladder. Per-tier weights, delivery SLAs, retry contracts, and the YAML calibration format that translates the feed tier card into deployable configuration.

36	Item item.md domain	Item master — canonical source of truth for what a merchant sells. 34 attributes, multi-location pricing, supplier cross-references, and UPC/PLU/SKU normalization. Foundation of the data model.
37	IaaS — Inventory as a Service inventory-as-a-service.md domain	Shared inventory position engine for the platform. Not embedded per-module — a platform service that answers inventory position queries for all consumers with a consistent, event-sourced view.
38	Receiving receiving.md domain	PO-to-dock reconciliation. ASN handling, variance capture, three-way match trigger, and the damage/shortage exception workflow. Where vendor promises meet physical reality.
39	Three-Way Match three-way-match.md domain	PO quantity, received quantity, and vendor invoice quantity reconciliation. The oldest control in procurement — implemented as a platform service so every module gets the control without re-implementing the logic.
40	Store Network Integrity store-network-integrity.md domain	Cross-location correlation jobs that publish alerts when a single store deviates from its network peer group. Turns multi-store data into a signal that single-location systems can't produce.

41	Commercial commercial.md domain	Vendor relationship layer — contracts, payment terms, rebates, and chargebacks. The financial backbone of vendor relationships, distinct from inventory and receiving.
42	Pricing pricing.md domain	Single source of truth for what an item costs a customer at any given moment. Price history, promotions, zone pricing, and the time-aware price query interface. Deceptively complex when multi-location.
43	Ecom Channel ecom-channel.md domain integration	Ecommerce channel integration. Inventory reservation, BOPIS fulfillment coordination, and multi-channel position reconciliation. Built on IaaS — no per-channel inventory silo.
44	Returns returns.md domain detection	Return processing and fraud detection. Cashier override detection, receipt validation, return policy enforcement. Returns are the most fraud-prone transaction in retail — this domain owns the controls.
45	Compliance compliance.md domain	Item authorization and regulatory zone engine. Answers one question before any restricted-item transaction completes: is this item legally and operationally authorized here? Age verification, restricted-item zones, license enforcement.

46	Analytics analytics.md domain	KPI dashboard orchestration, heatmap band scoring, velocity anomaly detection. The read-heavy metrics domain — aggregates signals from all services into the operator-facing performance surface.
47	Ops Dashboard ops-dashboard.md domain	Store NOC interface — single pane of glass for every device, alert, and operational event across a store network. The surface a store owner opens first when something is wrong.
48	Store Brain store-brain.md domain mcp	In-store AI context manager. Fires before any other interaction in a Canary-connected store — loads merchant context, recent alerts, inventory position, and open cases into the agent's working set.
49	Owl — AI Analysis Engine owl.md domain mcp	Personality-routed chat, health-check reports, and natural-language anomaly summaries. Translates platform signals into operator-legible narratives — the AI intelligence layer.
50	Agent Smart Contracts agent-contracts.md mcp	Smart contract enforcement for the autonomous agent network. Defines the boundary conditions — what agents can decide, write, and trigger without human approval and what requires an escalation.

51	Device Contracts device-contracts.md domain	Smart contract enforcement for cost and profit center devices. Tracks device operating spend against authorized budgets. Every POS terminal, scanner, and kiosk is a billable node with an authorized cost envelope.
52	Cloud Architecture & Workload cloud-architecture-workload.md platform	GCP Cloud Run, Cloud SQL, Pub/Sub, and workload identity. Why GCP is the fastest path to credible for an ARTS-aligned SMB platform — and where the portability exits are if that changes.
53	Document Factory Pipeline factory-pipeline.md platform	Knowledge ingestion layer. Accepts working papers, vendor specs, and research documents — converts to canonical form and routes to Brain. The intelligence supply chain behind the platform's memory.
54	Retail Lifecycle Test Dataset retail-lifecycle-test-data.md platform required	Integration testing substrate covering the full transaction lifecycle from PO to return. Synthetic but realistic — seeded data that exercises every domain, every detection rule, and every edge case in the platform.

55	go-errors go-errors.md conventions required	Platform error taxonomy. Consistent, client-contract-grade error types across all 29 services. Consistent error handling is the boundary between an API clients can build against and one they work around.
56	go-observability go-observability.md conventions	Structured logging, metrics, and tracing conventions. How 29 services emit consistent telemetry — field names, log levels, trace propagation, and the GCP Cloud Logging integration.
57	go-runtime go-runtime.md conventions	Platform lifecycle library — shared graceful shutdown, health check, and signal handling. Implemented once; all 29 services import it. Without it, every service re-implements shutdown and drifts.
58	go-security go-security.md conventions required	Authentication, encryption, and access control patterns. Security controls implemented once and enforced everywhere — key rotation, JWT validation, RBAC enforcement, and the API key lifecycle.
59	go-testing go-testing.md conventions required	Test infrastructure and conventions. Unit, integration, and smoke layers; test database management; fixture patterns. A test suite that passes against mocks while the real DB migrates is worthless.
60	Data Classification & Governance data-classification-inventory.md conventions	Data classification inventory for multi-tenant retail SaaS. PII map, cardholder-adjacent data boundaries, data retention schedules, and breach notification scoping. The compliance input to the security architecture.

01–04 are the recommended orientation set for new engineers. When working in a specific service, read the domain SDD for that service first, then the platform convention SDDs that apply (go-errors, go-testing, go-security are marked required for a reason). The go-module-layout SDD applies everywhere.