Module 9: Multi-location
⛔ SUPERSEDED 2026-06-11 — Sprig-era feature spec (pre-pivot). The authoritative current design is the locked schema in docs/SCHEMA.md, the module's entry in docs/PROJECT_DECISIONS.md, and the responsibility/seam maps in docs/MODULE_INDEX.md + docs/CROSS_MODULE_CONTRACTS.md. This file is retained for historical feature context only; do NOT treat its scope/table/feature claims as current (it predates the nursery→generic pivot, the HR-out-of-scope cut, the identity/payments/integrations/files extractions, and the schema locks). Superseded note added 2026-06-11.
Status: ✅ Locked for v1.0 (schema-ready; UI rollout v1.5+)
Schema: multi_loc
Feature count: 107 features in v1.0
Build estimate: Strategic spec only — implementation effort TBD
Last updated: 2026-05-12
Overview
Multi-location handles tenant operations spanning multiple physical sites. Schema is multi-site-ready in v1.0; dedicated multi-site UI activates in v1.5+. Single-site tenants operate normally — multi-loc complexity stays hidden until they expand.
The module covers: site setup, per-site inventory, inter-site transfers, cross-site sales/refunds/reservations, customer experience across sites, staff and permissions, production across sites, multi-site reporting, pricing/promotions, operations, and audit/compliance.
Multi-location depends on Inventory (per-site stock), POS (sales attribution per site), Orders (cross-site fulfillment), Production (production at sites), CRM (customer recognition across sites), and Reporting (multi-site dashboards).
See ARCHITECTURE.md → "Multi-Site Architecture" for the core schema pattern.
Target Customer Profile
- Mid-size growth-stage retail nursery, $500K–$5M revenue
- Currently 1 site; planning 1–3 additional sites within 24 months
- OR currently 2–5 sites; growing to 10+ within 24 months
- Mixed retail / wholesale / production operations
- Regional or multi-state operations
- Customer base shops across sites (locals, vacationers, contractors)
Tier Behavior
| Tier |
Multi-location capability |
| Starter |
Single site only — multi-site UI not available |
| Pro |
Single site in v1.0; multi-site UI in v1.5+ |
| Enterprise |
Multi-site UI from v1.5; full multi-site features including site hierarchies, custom pricing per site, advanced reporting |
Architecture Principle: Configurability
Every threshold, default, and policy in Multi-location is configurable per tenant via the Owner Dashboard (Module 10).
Feature Hierarchy (107 features across 12 groups)
Group 1: Site Setup & Configuration (15 features)
| # |
Feature |
Notes |
| 1.1 |
Site master record |
Site name, address, contact info, status |
| 1.2 |
Multiple sites per tenant |
Tenant manages 2-10+ physical locations Schema-ready in v1.0; UI in v1.5+. |
| 1.3 |
Site type categorization |
Retail / Wholesale / Production / Storage / Hybrid |
| 1.4 |
Site operating hours |
Day-by-day hours, holidays, special hours |
| 1.5 |
Site contact info |
Manager email, phone, on-site staff contact |
| 1.6 |
Site default configuration |
Each site has own settings (receipt format, tax jurisdiction, etc.) |
| 1.7 |
Site capacity / size |
Physical footprint info; helps with planning |
| 1.8 |
Site location coordinates |
GPS for delivery routing, customer directions |
| 1.9 |
Site brand customization |
Logo, brand colors per site (for multi-brand operations) Schema-ready in v1.0; UI in v1.5+. |
| 1.10 |
Site activate/deactivate |
Temporarily close a site; reopen later Schema-ready in v1.0; UI in v1.5+. |
| 1.11 |
Primary site designation |
Default site for new operations Schema-ready in v1.0; UI in v1.5+. |
| 1.12 |
Site code / identifier |
Short code (e.g., "MAIN", "BRANCH-B") for receipts, invoices, etc. |
| 1.13 |
Site hierarchies (parent-child) |
"Main HQ has 3 branches" — organizational structure Schema-ready in v1.0; UI in v1.5+. |
| 1.14 |
Site-specific merchant accounts |
Different Stripe Connect account per site (for payment routing). Distinct from the per-tenant Stripe Customer used for SaaS subscription billing (Module 11). See PROJECT_DECISIONS Stripe Architecture. Routes via PaymentsService (Payments module) — Multi-location surfaces the per-site Connect account configuration UI; PaymentsService owns the Stripe API client and Connect Account lifecycle. Schema-ready in v1.0; UI in v1.5+. |
| 1.15 |
Site rollover / decommissioning |
Closing a site; data preservation; archival workflow Schema-ready in v1.0; UI in v1.5+. |
Group 2: Inventory at Site Level (10 features)
| # |
Feature |
Notes |
| 2.1 |
Per-site inventory |
Each site has independent stock counts |
| 2.2 |
Cross-site inventory visibility |
"Where is Bloodgood Japanese maple available?" — see across sites Schema-ready in v1.0; UI in v1.5+. |
| 2.3 |
Per-site zones (within sites) |
Each site has its own zones |
| 2.4 |
Per-site bins (within zones) |
Bin-level location within each site |
| 2.5 |
Receiving per site |
Each site has its own receiving workflow |
| 2.6 |
Site-specific cost basis |
Same plant, different cost at different sites Schema-ready in v1.0; UI in v1.5+. |
| 2.7 |
Site-specific retail pricing |
Same plant, different retail price per site Schema-ready in v1.0; UI in v1.5+. |
| 2.8 |
Site-level reorder thresholds |
"Low stock at Site A" alerts |
| 2.9 |
Site-level vendor relationships |
Some vendors only deliver to specific sites Schema-ready in v1.0; UI in v1.5+. |
| 2.10 |
Site-level inventory valuation |
Per-site dollar value of stock |
Group 3: Inter-Site Transfers (10 features)
| # |
Feature |
Notes |
| 3.1 |
Create transfer order |
"Send 50 plants from Site A to Site B" Schema-ready in v1.0; UI in v1.5+. |
| 3.2 |
Transfer status states |
draft / sent / in_transit / received / completed / cancelled Schema-ready in v1.0; UI in v1.5+. |
| 3.3 |
Transfer shipping documentation |
BOL, packing slip for transfers Schema-ready in v1.0; UI in v1.5+. |
| 3.4 |
Transfer carrier tracking |
If using carriers (vs internal transport) Schema-ready in v1.0; UI in v1.5+. |
| 3.5 |
Transfer cost allocation |
Internal transfer cost (if any) tracked Schema-ready in v1.0; UI in v1.5+. |
| 3.6 |
Receiving at destination site |
Stock added to Site B inventory Schema-ready in v1.0; UI in v1.5+. |
| 3.7 |
Transfer discrepancy capture |
"Sent 50, received 47" — short tracking Schema-ready in v1.0; UI in v1.5+. |
| 3.8 |
Transfer photo capture |
Document transferred items Schema-ready in v1.0; UI in v1.5+. |
| 3.9 |
Multi-site transfer (A→B→C) |
Chained transfers Schema-ready in v1.0; UI in v1.5+. |
| 3.10 |
Transfer history per site |
All transfers involving each site Schema-ready in v1.0; UI in v1.5+. |
Group 4: Sales Across Sites (8 features)
| # |
Feature |
Notes |
| 4.1 |
Sale rung up at any site |
Customer buys at Site A or Site B |
| 4.2 |
Sale attributed to site |
Each sale tagged with originating site |
| 4.3 |
Sale-from-other-site at register |
Customer at Site A wants Site B's stock; ring up at A, transfer/deliver from B Schema-ready in v1.0; UI in v1.5+. |
| 4.4 |
Cross-site reservation fulfillment |
Customer reserves at Site A, picks up at Site B Schema-ready in v1.0; UI in v1.5+. |
| 4.5 |
Cross-site refund |
Customer returns at Site B what they bought at Site A Schema-ready in v1.0; UI in v1.5+. |
| 4.6 |
Cross-site loyalty / customer recognition |
Same customer at any site; loyalty tracked across Schema-ready in v1.0; UI in v1.5+. |
| 4.7 |
Per-site cashier permissions |
"User X can only sell at Site A" Schema-ready in v1.0; UI in v1.5+. |
| 4.8 |
Customer's preferred site |
"I always pick up at Site B" — preference captured Schema-ready in v1.0; UI in v1.5+. |
Group 5: Customer Experience Across Sites (9 features)
| # |
Feature |
Notes |
| 5.1 |
Customer chooses preferred site |
At signup or in app Schema-ready in v1.0; UI in v1.5+. |
| 5.2 |
App shows "your local site" |
Personalized to customer Schema-ready in v1.0; UI in v1.5+. |
| 5.3 |
Order pickup at customer-chosen site |
Reserve at one site, pickup at another Schema-ready in v1.0; UI in v1.5+. |
| 5.4 |
Customer notifications site-specific |
"Site A is having a sale" — only for that site's customers Schema-ready in v1.0; UI in v1.5+. |
| 5.5 |
Customer can travel between sites |
One customer record, used at any site Schema-ready in v1.0; UI in v1.5+. |
| 5.6 |
Customer order history across sites |
Unified view Schema-ready in v1.0; UI in v1.5+. |
| 5.7 |
Site-specific events / announcements |
Per-site marketing Schema-ready in v1.0; UI in v1.5+. |
| 5.8 |
Cross-site customer service |
Issue raised at Site A handled at any site Schema-ready in v1.0; UI in v1.5+. |
| 5.9 |
Customer-site "owned by" attribution |
Track which site "owns" the customer relationship for sales rep attribution Schema-ready in v1.0; UI in v1.5+. |
Group 6: Staff & Permissions Across Sites (10 features)
| # |
Feature |
Notes |
| 6.1 |
Staff assigned to specific sites |
"Cashier John works at Site A only" Schema-ready in v1.0; UI in v1.5+. |
| 6.2 |
Staff working at multiple sites |
"Manager Sarah works at all sites" Schema-ready in v1.0; UI in v1.5+. |
| 6.3 |
Site-specific staff schedules |
Each site has its own staff schedule Schema-ready in v1.0; UI in v1.5+. |
| 6.4 |
Per-site permissions |
Different role at different sites Schema-ready in v1.0; UI in v1.5+. |
| 6.5 |
Staff sign-in at site |
Cashier logs into specific site's register |
| 6.6 |
Staff transfer between sites |
"Move John from Site A to Site C this week" Schema-ready in v1.0; UI in v1.5+. |
| 6.7 |
Cross-site staff communication |
Internal messaging across sites Schema-ready in v1.0; UI in v1.5+. |
| 6.8 |
Staff time tracking per site |
Hours per site for payroll allocation |
| 6.9 |
Manager assigned per site |
Site manager role tracking Schema-ready in v1.0; UI in v1.5+. |
| 6.10 |
Site-specific reporting permissions |
"Site manager only sees their site's data" Schema-ready in v1.0; UI in v1.5+. |
Group 7: Production Across Sites (6 features)
| # |
Feature |
Notes |
| 7.1 |
Production at specific site |
Each site has own production zones |
| 7.2 |
Production transfer between sites |
"Grew at Site A, sold at Site B" Schema-ready in v1.0; UI in v1.5+. |
| 7.3 |
Cross-site production planning |
Plan production capacity across all sites Schema-ready in v1.0; UI in v1.5+. |
| 7.4 |
Site-specific propagation |
Some plants only propagated at one site Schema-ready in v1.0; UI in v1.5+. |
| 7.5 |
Production lot moved to retail at another site |
Common workflow Schema-ready in v1.0; UI in v1.5+. |
| 7.6 |
Cross-site production reporting |
Combined production view Schema-ready in v1.0; UI in v1.5+. |
Group 8: Multi-Site Reporting & Analytics (10 features)
| # |
Feature |
Notes |
| 8.1 |
Multi-site dashboard |
Owner sees all sites in one view Schema-ready in v1.0; UI in v1.5+. |
| 8.2 |
Site comparison report |
Side-by-side performance Schema-ready in v1.0; UI in v1.5+. |
| 8.3 |
Site ranking |
"Best performing site this quarter" Schema-ready in v1.0; UI in v1.5+. |
| 8.4 |
Site-specific financial reports |
P&L per site |
| 8.5 |
Consolidated financial reporting |
Tenant-wide P&L across sites Schema-ready in v1.0; UI in v1.5+. |
| 8.6 |
Cross-site customer report |
Customers who shop at multiple sites Schema-ready in v1.0; UI in v1.5+. |
| 8.7 |
Cross-site inventory report |
Where stock lives across the network Schema-ready in v1.0; UI in v1.5+. |
| 8.8 |
Site-specific marketing report |
Campaign performance per site |
| 8.9 |
Inter-site transfer report |
Transfer activity, costs, frequency Schema-ready in v1.0; UI in v1.5+. |
| 8.10 |
Site capacity utilization |
"Site A is at 90% capacity, Site B at 50%" |
| # |
Feature |
Notes |
| 9.1 |
Site-specific pricing |
Same plant, different price per site (geographic markets) Schema-ready in v1.0; UI in v1.5+. |
| 9.2 |
Site-specific promotions |
Campaign at Site A only |
| 9.3 |
Cross-site promotion eligibility |
Promotion at Site A redeemable at Site B (configurable) Schema-ready in v1.0; UI in v1.5+. |
| 9.4 |
Site-specific loyalty rules |
Each site might have different points multipliers Schema-ready in v1.0; UI in v1.5+. |
| 9.5 |
Cross-site loyalty redemption |
Same customer's points usable at any site Schema-ready in v1.0; UI in v1.5+. |
| 9.6 |
Site-specific contractor pricing |
Same contractor might get different tier at different sites Schema-ready in v1.0; UI in v1.5+. |
| 9.7 |
Inter-site competition incentives |
"Beat the other site's sales this week" — internal contest Schema-ready in v1.0; UI in v1.5+. |
| 9.8 |
Site-specific bundle / combo deals |
"Buy at Site A, save at Site C" Schema-ready in v1.0; UI in v1.5+. |
| 9.9 |
Site-specific gift card scope |
Issuing-site only OR cross-site redeemable (configurable per card) Schema-ready in v1.0; UI in v1.5+. |
Group 10: Multi-Site Operations (9 features)
| # |
Feature |
Notes |
| 10.1 |
Cross-site bulk operations |
"Update price for all sites" Schema-ready in v1.0; UI in v1.5+. |
| 10.2 |
Site-specific operating policy |
Some policies only at certain sites |
| 10.3 |
Site-by-site rollout |
Test new features at one site before rolling out Schema-ready in v1.0; UI in v1.5+. |
| 10.4 |
Cross-site data sharing |
Real-time sync of changes (inventory, prices) Schema-ready in v1.0; UI in v1.5+. |
| 10.5 |
Site-specific hardware setup |
Different POS hardware at different sites |
| 10.6 |
Cross-site staff scheduling |
Centralized schedule view Schema-ready in v1.0; UI in v1.5+. |
| 10.7 |
Cross-site customer service triage |
Route issues to correct site Schema-ready in v1.0; UI in v1.5+. |
| 10.8 |
Cross-site emergency notifications |
"Sales system down at Site A — backup procedures" Schema-ready in v1.0; UI in v1.5+. |
| 10.9 |
Site-to-site data sync conflict resolution |
When same record edited at two sites — resolution workflow Schema-ready in v1.0; UI in v1.5+. |
| # |
Feature |
Notes |
| 11.1 |
Site health dashboard |
All sites' operational status |
| 11.2 |
Per-site uptime tracking |
"Site A had 99.8% uptime this month" |
| 11.3 |
Per-site key metrics |
Sales velocity, customer count, avg ticket |
| 11.4 |
Per-site staff metrics |
Performance, turnover, training status |
| 11.5 |
Per-site customer satisfaction |
If review feature enabled |
| 11.6 |
Per-site predictive maintenance |
"Site B's POS terminal needs replacement soon" |
Group 12: Audit & Compliance Across Sites (5 features)
| # |
Feature |
Notes |
| 12.1 |
Per-site audit trail |
All actions at each site |
| 12.2 |
Cross-site audit trail |
Tenant-wide audit log Schema-ready in v1.0; UI in v1.5+. |
| 12.3 |
Per-site compliance reporting |
Tax filings, regulatory reports per jurisdiction |
| 12.4 |
Site-specific data retention |
Different retention per site if needed for jurisdictional rules Schema-ready in v1.0; UI in v1.5+. |
| 12.5 |
Per-site bank deposits & QuickBooks file |
Each site can have its own bank account and QuickBooks file for accounting separation Schema-ready in v1.0; UI in v1.5+. |
Configurable Defaults (Owner Dashboard)
| Configurable |
Default |
| Multi-site enabled per tenant |
Schema-ready always; UI gated to Pro+ tier v1.5+ |
| Cross-site inventory visibility |
ON for all connected sites |
| Cross-site customer recognition |
ON |
| Cross-site loyalty redemption |
ON (configurable per loyalty program) |
| Inter-site transfer cost allocation |
Internal cost (configurable) |
| Site-specific pricing |
OFF (use tenant-wide pricing); configurable |
| Per-site reorder thresholds |
Inherited from tenant; override-able |
| Cross-site promotion eligibility |
OFF by default (configurable) |
| Cross-site refund permission |
ON |
| Cross-site staff permissions |
OFF (each site has own staff by default) |
| Multi-site dashboard |
Enterprise tier only |
| Cross-site bulk operations |
Enterprise tier only |
| Per-site brand customization |
OFF (single tenant brand by default); configurable |
| Site hierarchies enabled |
OFF (configurable) |
| Per-site merchant account |
OFF (configurable; Pro+ tier) |
| Per-site QuickBooks file |
OFF (configurable; Enterprise tier) |
| Site decommissioning workflow |
Manager + Owner approval required |
| Cross-site sync conflict resolution |
Auto-resolve with audit log; manual override available |
| Gift card scope (default) |
Issuing-site only (configurable to cross-site) |
AI Features in Multi-location
| Feature # |
AI capability |
| 4.3 |
AI suggested site for cross-site fulfillment (best for cost, speed) |
| 3.1 |
AI optimal transfer suggestions ("ship from Site A vs Site B") |
| 8.2 |
AI site performance comparison and benchmarking |
| 8.10 |
AI site capacity utilization analysis |
| 10.9 |
AI conflict resolution suggestions |
| 11.6 |
AI predictive maintenance for site infrastructure |
All AI features route via AIService (AI / Intelligence module; model-as-config; AWS Bedrock Claude Haiku 4.5 is the default model). Multi-location does not call Bedrock directly.
Events Emitted
multi_loc.site_createdmulti_loc.site_updatedmulti_loc.site_activatedmulti_loc.site_deactivatedmulti_loc.site_decommissionedmulti_loc.site_hierarchy_changedmulti_loc.transfer_createdmulti_loc.transfer_sentmulti_loc.transfer_receivedmulti_loc.transfer_completedmulti_loc.transfer_discrepancymulti_loc.cross_site_sale_executedmulti_loc.cross_site_reservation_fulfilledmulti_loc.staff_assignedmulti_loc.site_capacity_alertmulti_loc.sync_conflict_detectedmulti_loc.sync_conflict_resolvedmulti_loc.site_compliance_filing_completed
Events Consumed
All modules emit per-site events that Multi-location aggregates and routes:
inventory.stock_changed (per site)pos.sale_completed (per site)orders.reservation_created (per site)purchasing.receipt_recorded (per site)production.lot_completed (per site)crm.customer_created (always tenant-wide)billing.subscription_changed (enforce multi-site tier limits)
API Contract (MultiLocService — public methods)
High-level surface (detailed signatures during implementation):
- Site management:
createSite, updateSite, activateSite, deactivateSite, decommissionSite, manageHierarchy
- Transfers:
createTransfer, recordReceiving, recordDiscrepancy, getTransferHistory
- Cross-site sales:
findSiteWithStock, executeSaleAtSite, crossSiteRefund, crossSiteFulfill
- Staff & permissions:
assignStaffToSite, getStaffPermissions, transferStaff
- Production:
linkProductionToSite, transferProductionToSite
- Reporting:
getMultiSiteDashboard, compareSites, getConsolidatedReport, getSiteUtilization
- Sync & conflict:
detectSyncConflict, resolveConflict
- Merchant & finance:
setMerchantAccount, setQuickBooksFile
Out of Scope
| Capability |
Why excluded |
| Real-time inter-site live video feeds |
Out of scope (security category) |
| Site-specific environmental controls (HVAC, sensors) |
Out of scope (IoT category) |
| Drone deliveries between sites |
Out of scope |
| Self-driving vehicle integration for transfers |
Out of scope |
| Cross-tenant operations (different Vrida tenants sharing inventory) |
Out of scope (privacy) |
| Real-time site location tracking for staff |
Future v2.0 |
| Per-site customer accounts (vs unified across sites) |
Architectural decision: customer account is tenant-wide |
| Multi-site real-time WebSocket sync |
Pro+ tier; basic polling-based sync in v1.0 |
| Site failover / disaster recovery automation |
Future v2.0 |
| Site rollback / undo capability |
Future |