Module 8: Customer-facing App

⛔ 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.

⚠️ Revised 2026-05-13 per Nursery-Only Focus: The consumer-owned tables (plant_library, garden_plan, chat_session, tag_scan_log) live in the customer_app schema directly (this module owns them). The Phase 4B-1 "nursery vertical-extension layer" framing is cancelled. The tables themselves don't move — they remain consumer-owned and cross-tenant; only the layering label is dropped. AI features continue to route via AIService.

Status: ✅ Locked for v1.0 (no structural refactor pending) Schema: customer_app (nursery-facing module; owns consumer-owned cross-tenant tables directly) Feature count: 145 features in v1.0 — unchanged. Build estimate: Strategic spec only — implementation effort TBD Last updated: 2026-05-13 (Nursery-Only Focus revision; extension-layer framing dropped)

Overview

The Customer-facing App is built for end consumers who buy plants — NOT for nursery owners or staff. Customers download the app, create an account (free, no purchase required), and connect to one or many nurseries. They use the app to manage their plant care, chat with AI for advice, place reservations and orders, manage loyalty status, and scan plant tags.

This is a critical differentiator module — the moat. Free for end consumers forever. AI-powered plant care chat is the core engagement feature, drawing customers back to the app daily even when not actively shopping.

The same customer account works across multiple connected nurseries. Customer preferences, plant library, garden plans, and AI chat history are GLOBAL (per customer). Order history, loyalty programs, and notifications are PER-NURSERY (tenant-scoped, with privacy boundaries between nurseries).

Target Customer Profile (End Consumer)

• Hobbyist gardener, $50K-$200K household income
• 1-50 plants in garden (mix of in-ground and containers)
• Asks plant care questions, identifies plants from photos
• Visits 1-3 nurseries per year in person, more during spring
• Active during spring (40-50% of usage Mar-May)
• Mobile-primary user (90%+ of interactions on phone)

Architecture Principles

Multi-nursery customer accounts

• ONE customer account per consumer, regardless of how many nurseries they shop at
• Customer can connect to many nurseries
• Each nursery connection grants that nursery access to the customer's order history AT that nursery
• Customer's plant library, garden plans, AI chat history are global (per customer)
• Customer's order history is unified in app UI; backend keeps tenant-scoped
• Privacy: Nursery A can never see Nursery B's order data or pricing

Deferred access controls

Feature gating, free tier vs paid tier, premium features for connected customers — all deferred. For v1.0, all features are available to all customers EXCEPT white-label theming, which is gated to consumers connected to Enterprise-tier nurseries. No other feature gating beyond what's natural (must connect to nursery to order from it). Access controls and feature limits beyond this will be added later as monetization strategy develops. See PROJECT_DECISIONS "Deferred Decision: Customer-facing App Access Controls" and "White-Label Definition".

Realtime Subscription Strategy

A consumer connected to N nurseries opens a single Supabase Realtime subscription scoped to their primary nursery (most-recently-active or user-designated). Other connected nurseries are polled at 60-second intervals when the consumer is actively browsing that nursery's inventory. See ARCHITECTURE.md Customer App Realtime Pattern.

Layer note (revised 2026-05-13 per Nursery-Only Focus): Behavior is unchanged. The subscriptions are scoped against the consumer-owned cross-tenant tables in the customer_app schema (plant library, garden plans, chat sessions, tag scan log). The Phase 4B-1 "extension layer" framing is dropped — the tables themselves don't move. The Realtime pattern cares about the consumer's primary-nursery scope, which is unchanged.

Architecture Principle: Configurability

Every threshold, default, and customer-facing feature in Customer-facing App is configurable per tenant (the nursery) via the Owner Dashboard (Module 10) for their branded experience.

Table Scope (Tenancy)

Revised 2026-05-13 per Nursery-Only Focus. The Phase 4B-1 "nursery vertical-extension layer" framing is dropped. All customer_app.* tables live in the customer_app schema directly. The consumer-owned cross-tenant property of plant library / garden plans / chat sessions / tag scan log is unchanged — those tables remain cross-tenant and consumer-owned within customer_app.

Table	Schema	Scope	Notes
customer_app.plant_library	customer_app (this module)	Cross-tenant, consumer-owned	Persists across connected nurseries. Joined to consumer identity via the multi-nursery linkage table also in this schema. References inventory.plant (in the nursery's inventory schema) for plant identity where applicable.
customer_app.garden_plan	customer_app (this module)	Cross-tenant, consumer-owned	Persists across connected nurseries.
customer_app.chat_session	customer_app (this module)	Cross-tenant, consumer-owned	Persists across connected nurseries. Chat content is consumer-owned even when reading inventory from a specific tenant.
customer_app.tag_scan_log	customer_app (this module)	Cross-tenant, consumer-owned	Same scope reasoning.
customer_app.nursery_customer_link	customer_app (this module)	Cross-tenant join	Links one consumer identity to multiple tenants. SECURITY DEFINER pattern reserved for writes touching this table.
customer_app.order_link	customer_app (this module)	Tenant-scoped	Links the tenant-scoped crm.customer row to the tenant's orders. Enforces per-tenant privacy. FK to crm.customer (tenant-scoped, in crm schema).

Cross-schema write pattern

• Writes to customer_app.order_link (tenant-scoped) use the standard SET LOCAL app.current_tenant_id = ? + RLS pattern.
• Writes to the consumer-owned cross-tenant tables (plant library, garden plans, chat sessions, tag scan log, nursery_customer_link) use the SECURITY DEFINER pattern — the function validates app.current_tenant_id against the consumer's multi-nursery linkage before allowing the write.

See SCHEMA_CONVENTIONS.md → "Cross-Schema Writes" and "Global Tables (Tenant Scope Exceptions)" for the convention.

Superseded prior framing (preserved for traceability)

customer_app.plant_library — Global. Per PROJECT_DECISIONS Global Tables. Consumer's plant library across all connected nurseries. customer_app.garden_plan — Global. Consumer's garden plans; persist across nursery connections. customer_app.chat_session — Global. AI chat history; consumer-owned. customer_app.tag_scan_log — Global. Consumer's own scan history. customer_app.order_link — Tenant-scoped. Links global customer to tenant's orders; enforces per-tenant privacy.

All five rows above are superseded per the Architecture Redesign. The behaviors are preserved; the layer homes have changed.

AI Routing (Architecture Redesign 2026-05-13)

All AI features in this module — Group 3 Plant Care AI Chat features 3.1–3.15 in particular, plus plant identification, disease/pest identification, care advice, and any consumer-facing AI surface — route through the AIService abstraction owned by the AI / Intelligence module. This module does NOT call AWS Bedrock directly.

• Model selection is model-as-config at the AIService level
• Per-tenant rate limits, fallback paths, and (later) the RAG corpus are owned by AIService
• Chat session history is stored in the extension-layer chat_session table; chat completion calls go to AIService

See ARCHITECTURE.md → "AI Capacity and Cost" and PROJECT_DECISIONS.md → "Architecture Redesign" §5 (new modules / layers).

See PROJECT_DECISIONS.md → "Global Tables (Tenant Scope Exceptions)" and "Customer App Schema Ownership".

Feature Hierarchy (145 features across 15 groups)

Group 1: Onboarding & Account (12 features)

#	Feature	Notes
1.1	App download from app stores	iOS App Store, Google Play
1.2	Anonymous browsing	Use app without account creation; limited functionality
1.3	Account signup via email + password	Standard signup flow
1.4	Account signup via phone + SMS OTP	Mobile-first signup
1.5	Account signup via Apple Sign-In / Google	Social login
1.6	Onboarding tutorial	Tour of app features for new users
1.7	Nursery selection	User selects which nursery they want to connect to
1.8	Auto-detect nursery via QR code	Scan QR at nursery → app auto-configures for that nursery
1.9	Multi-nursery support	Customer can connect to multiple nurseries
1.10	Account merge	If user has multiple accounts, merge them
1.11	Manage nursery connections	View, add, remove nursery connections from settings
1.12	Connect via QR from another nursery (in-app)	Scan QR from new nursery's marketing to add connection

Group 2: User Profile & Preferences (8 features)

#	Feature	Notes
2.1	Profile creation	Name, email, phone, optional photo
2.2	Location / address (optional)	For delivery, plant zone recommendations
2.3	USDA hardiness zone (auto-detected)	Based on address; affects plant recommendations
2.4	Garden type	Indoor / outdoor / both / container / landscape
2.5	Sun exposure of garden	Full sun / part shade / shade
2.6	Soil type	Clay / sandy / loamy / etc.
2.7	Watering availability	Sprinklers / hand-water / drought-tolerant only
2.8	Notification preferences	Email / push / SMS — per category

Group 3: Plant Care AI Chat (15 features)

#	Feature	Notes
3.1	Plant care chat interface	Conversational UI; ask questions in natural language
3.2	Plant identification from photo	Upload photo; AI identifies (Bedrock Haiku 4.5)
3.3	Disease / pest identification from photo	"What's wrong with my plant?"
3.4	Care advice for identified plant	"Your Japanese maple needs..."
3.5	Watering recommendations	Based on plant species + climate
3.6	Fertilizing recommendations	Schedule and product suggestions
3.7	Pruning advice	When and how to prune
3.8	Pest treatment recommendations	Safe products for specific issues
3.9	Plant rescue advice	"My plant is dying — what can I do?"
3.10	Plant-related general questions	Soil mixing, when to plant, etc.
3.11	Chat history persistence	Past conversations saved per user
3.12	Chat-to-purchase conversion	"I should fertilize" → button to buy fertilizer at nursery
3.13	AI chat with voice input	Hands-dirty in garden; speak vs type
3.14	Beginner vs expert mode	Different depth of advice for different users; configurable
3.15	Photo-based plant condition tracking	AI compares photos over time; flags health changes

Group 4: Plant Catalog Browse & Search (11 features)

#	Feature	Notes
4.1	Browse plants by category	Annuals, perennials, trees, shrubs, etc.
4.2	Plant search by name	Common or botanical
4.3	Plant search by attributes	Sun, water, deer-resistant, native, etc.
4.4	Plant detail page	Photos, care info, current price at nursery, availability
4.5	Plant similar / alternative suggestions	"If Bloodgood is out, try..."
4.6	Plant by USDA zone filter	Only show plants suitable for user's zone
4.7	Plant photo gallery	Multiple images per plant
4.8	Plant compatibility recommendations	"Plants that grow well together"
4.9	All-nurseries view toggle	Browse plants at all connected nurseries OR filter to one
4.10	Plant compatibility / companion planting (explicit)	"Tomatoes grow well with basil" with specific reasons
4.11	Pet-safe / Child-safe plant filter	"Show only plants safe for cats" / "safe for kids"

Group 5: Plant Care Library & Personalization (16 features)

#	Feature	Notes
5.1	Plant care articles / guides	Curated content per plant or topic
5.2	"My Garden" plant list	Plants I own / want / have grown
5.3	Plant care reminders	Personalized: "Your roses need fertilizer this week"
5.4	Plant care logbook	User logs watering, fertilizing, pruning
5.5	Plant care problem journal	Track issues encountered over time
5.6	Seasonal care guides	"What to do in your garden this March"
5.7	Climate-aware recommendations	Adjusted for user's specific climate
5.8	Plant care notifications	Push notifications for time-sensitive tasks
5.9	Plant care tips on tag scan	Scan QR on plant tag → see specific care for that variety
5.10	Plant care educational content	Plant care concepts, beginner guides
5.11	Plant care quiz / personalization	Customer answers questions → personalized recommendations
5.12	Plant care milestones / achievements	Gamification — "First sprout!", "10 plants in garden!"
5.13	Plant care library offline mode	Care guides downloadable for offline access
5.14	Plant care recipes / soil recipes	"Make this soil mix for tomatoes" — DIY recipes
5.15	Plant memory / sentimental record	"Plant given by grandmother in 2010" — meaningful records
5.16	National expert curated content	Master Gardener content, national plant experts

Group 6: Shopping & Orders (16 features)

#	Feature	Notes
6.1	Browse current inventory at nursery	What's in stock right now
6.2	Real-time availability	Live inventory data from nursery
6.3	Add to wishlist / favorites	Save plants for later
6.4	Reserve from app	Create reservation for pickup
6.5	Pre-order from app	Reserve for upcoming shipment
6.6	Special order from app	Request item not currently stocked
6.7	View open orders	Status of current orders
6.8	View past purchases	All previous receipts
6.9	Reorder past purchase	Repeat previous order
6.10	Save favorite items list	"My garden essentials"
6.11	Garden plan / wishlist	Saved layout for next planting season
6.12	Cart / checkout (limited)	For pre-orders and reservations; full checkout in v1.5+
6.13	Unified order history across nurseries	All orders from all connected nurseries in one view
6.14	Per-nursery order filter	Filter order history by specific nursery
6.15	Multi-nursery order management	Place orders at multiple nurseries simultaneously if needed
6.16	Wishlist / gift list sharing with friends	Share wishlist URL with family for gift purchases

Group 7: Pickup & Delivery (6 features)

#	Feature	Notes
7.1	Pickup notification	"Your order is ready" with directions
7.2	Pickup verification at register	Show QR code at checkout
7.3	Pickup window selection	Choose date/time
7.4	Delivery scheduling	Choose delivery date/time
7.5	Delivery tracking	Where is my order?
7.6	Delivery confirmation	Customer confirms received

Group 8: Loyalty & Rewards (9 features)

#	Feature	Notes
8.1	Loyalty dashboard	Points balance, tier, progress
8.2	Loyalty rewards available	What I can redeem
8.3	Tier benefits	What unlocks at next tier
8.4	Anniversary rewards	Special offers on signup anniversary
8.5	Birthday rewards	Birthday discount or bonus
8.6	Promotional rewards	Time-limited offers
8.7	Referral rewards	Refer a friend, both get points
8.8	Customer loyalty history	All earnings and redemptions
8.9	All loyalty balances view	View loyalty status across all connected nurseries

Group 9: Plant Tag Scanning (8 features)

#	Feature	Notes
9.1	QR code on plant tag scan	Camera scans tag → plant info opens
9.2	Detailed plant info from tag	Variant info, care instructions, current price
9.3	Plant tag history	All tags I've scanned
9.4	Add scanned plant to "My Garden"	One-tap save
9.5	Plant tag age tracking	When was this plant tagged / propagated
9.6	Tag-based reorder	"Need another of these?" — quick reorder from scanned tag
9.7	Cross-nursery tag scanning	Tag identifies which nursery sold the plant; cross-nursery scan support
9.8	Plant tag save-as-PDF from app	Customer saves plant tag as PDF or PNG to their device. Print is the consumer's responsibility using their own printer. This is distinct from Inventory Group 5 thermal label printing (commercial).

Group 10: Garden Planning Tools (7 features)

#	Feature	Notes
10.1	Save garden plan / layout	Visual planner for upcoming planting
10.2	Plant recommendations for garden plan	"These plants work in your zones"
10.3	Garden plan with timing	"Plant this in spring, this in fall"
10.4	Garden plan shopping list	Auto-generate shopping list from plan
10.5	Garden plan visualization	Sketch / drag-and-drop interface
10.6	Multiple garden plans per user	"Front yard 2026" and "Back yard"
10.7	Garden plan templates	Inspired plans from experts or nursery

Group 11: Community & Engagement (10 features)

#	Feature	Notes
11.1	Plant photos shared by other customers	Inspiration feed
11.2	Tag plants with location	"Where I bought this" — links to nursery
11.3	Photo before/after	Document plant growth over time
11.4	Garden journal sharing (opt-in)	Share garden progress publicly or with friends
11.5	Nursery announcements / events	Workshops, sales, new arrivals
11.6	Event RSVP from app	Sign up for events
11.7	Newsletter / blog content	Read articles from nursery
11.8	Customer-to-customer plant trading (future)	Trade cuttings, share extras (v1.5+)
11.9	Customer review/rating of nursery	Rate nursery and overall experience
11.10	Plant quality rating at purchase	Customer rates individual plant quality

Group 12: Notifications & Communication (10 features)

#	Feature	Notes
12.1	Plant care reminder notifications	Push: "Time to water your tomato plants"
12.2	Order notifications	Ready for pickup, modified, etc.
12.3	Loyalty status notifications	Tier change, anniversary, promotions
12.4	Sale / promotion notifications	Time-limited offers
12.5	Plant warranty notifications	Warranty expiration reminders
12.6	Weather-aware notifications	"Frost tonight, protect your plants"
12.7	Nursery messages	Direct communications from nursery
12.8	Notification settings management	Granular control per notification type
12.9	Notification snooze	"Remind me in 3 hours" instead of dismiss
12.10	Notification time-of-day preferences	Granular: morning vs evening reminders

Group 13: Customer Support (5 features)

#	Feature	Notes
13.1	In-app help center	FAQs, getting started guides
13.2	Contact nursery from app	Email, call, or message nursery
13.3	Submit feedback	App and nursery feedback
13.4	Order issue reporting	"My order has an issue" workflow
13.5	Plant problem reporting	"This plant isn't doing well" — log issue

Group 14: Account Management & Privacy (10 features)

#	Feature	Notes
14.1	Edit profile	Update name, contact, preferences
14.2	Manage saved payment methods	(for online purchases — Pro+)
14.3	View privacy settings	What data is collected, shared
14.4	Export my data	GDPR right to access
14.5	Delete my account	Right to be forgotten
14.6	Logout / sign out	Secure logout
14.7	Manage nursery connections (per-nursery view)	View which nurseries have access to which data
14.8	View per-nursery data permissions	Granular control of what each nursery sees
14.9	App language translation	Support multiple languages (initially: English, Spanish)
14.10	Accessibility features	Screen reader, large text, color blind support, voice navigation

Group 15: Multi-User & Family Sharing (2 features)

#	Feature	Notes
15.1	Family / household sharing of garden	Share My Garden with spouse, partner, kids
15.2	Multi-user garden management	Multiple family members can edit same garden plan

Tier Behavior (Module-Level)

Tier	Customer App capability
Starter	Branded customer app (nursery's name/logo); basic features available
Pro	Full customer app: AI chat, garden planning, full plant care library, community features. Branded experience.
Enterprise	In-app theming (logo, colors, copy) when the connected nursery is Enterprise tier. Single app binary; theming is per-connected-tenant. + advanced personalization + premium content + multi-property garden management. See PROJECT_DECISIONS White-Label Definition.

Configurable Defaults (Owner Dashboard)

Configurable	Default
Customer-facing app enabled	ON (free)
Branded with nursery logo	ON (Pro+)
White-labeled (no Vrida branding)	OFF (Enterprise tier)
AI plant care chat enabled	ON
AI plant identification enabled	ON
AI disease/pest identification enabled	ON
Plant care reminder notifications enabled	ON by user
Order notifications	ON
Marketing notifications	OFF (opt-in)
Multi-nursery support	ON in v1.0 (architectural decision)
Garden planning tools enabled	ON
Community / sharing features enabled	ON (with privacy controls)
Plant photo upload	ON
Plant tag scanning	ON
In-app purchases enabled	OFF for v1.0 (reservations only; full checkout v1.5+)
Customer data export	ON (GDPR compliance)
Account deletion	ON
Family / household sharing	ON
Accessibility features	ON (Pro+ tier)
Language support	English + Spanish (configurable to add more)
Notification snooze	ON
Voice input for AI chat	ON
Beginner / expert mode for AI	"Beginner" default (configurable)
Photo-based condition tracking	ON
Tag printing from app	ON
Wishlist sharing	ON
Customer reviews enabled	ON (with moderation)
Plant quality ratings enabled	ON

AI Features in Customer-facing App

Feature #	AI capability
3.1-3.15	Plant care AI chat (entire conversational interface, voice, photo, condition tracking)
4.5	AI similar plant suggestions
4.8	AI plant compatibility recommendations
4.10	AI companion planting suggestions
5.7	AI climate-aware care recommendations
5.8	AI plant care timing predictions
5.11	AI personalized quiz recommendations
6.10	AI personalized favorite recommendations
9.1-9.8	AI plant identification on tag scan, AI-powered tag printing
10.2	AI garden plan plant recommendations
12.6	AI weather-aware notifications

All AI features use AWS Bedrock with Claude Haiku 4.5 for chat and identification.

Events Emitted

• customer_app.user_signed_up
• customer_app.user_logged_in
• customer_app.nursery_connected
• customer_app.nursery_disconnected
• customer_app.chat_message_sent
• customer_app.chat_voice_input_received
• customer_app.plant_identified
• customer_app.plant_scanned_via_tag
• customer_app.plant_added_to_garden
• customer_app.plant_added_to_wishlist
• customer_app.plant_quality_rated
• customer_app.nursery_reviewed
• customer_app.order_placed
• customer_app.reservation_created
• customer_app.loyalty_points_redeemed
• customer_app.notification_opened
• customer_app.notification_dismissed
• customer_app.notification_snoozed
• customer_app.profile_updated
• customer_app.feedback_submitted
• customer_app.account_deleted
• customer_app.garden_plan_saved
• customer_app.family_member_added
• customer_app.event_rsvp
• customer_app.gift_list_shared
• customer_app.condition_change_detected (AI)

Events Consumed

• inventory.stock_changed (refresh availability in app)
• inventory.variant_updated (refresh plant info)
• pos.sale_completed (update purchase history)
• orders.ready_for_pickup (push notification)
• orders.modified (notify customer of changes)
• crm.loyalty_tier_changed (notify customer)
• crm.payment_promise_made (track in customer's record)
• production.lot_transferred_to_inventory ("New arrivals" notifications)
• notifications.message_sent (deliver to app)

API Contract (CustomerAppService — public methods)

High-level surface (detailed signatures during implementation):

• Account: signUp, login, linkNursery, unlinkNursery, mergeAccount
• Profile: updateProfile, setPreferences, setLocation, setGardenInfo
• Plant Care: sendChatMessage, voiceTranscribe, identifyPlant, identifyDisease, getCareAdvice, getWateringSchedule, getCareReminder, setCareLogEntry
• Library: browseLibrary, getCareGuide, addToGarden, removeFromGarden, markFavorite
• Shopping: browseInventory, searchPlants, addToWishlist, createReservation, viewOrders, reorderPast
• Loyalty: getLoyaltyDashboard, redeemPoints, getReferralLink
• Tag scanning: scanTag, viewTagHistory, requestTagPrint
• Garden planning: savePlan, getRecommendations, getShoppingList
• Community: submitReview, rateProductQuality, rsvpEvent, joinCommunityGroup
• Notifications: setPreference, snooze, manageSettings
• Family: addFamilyMember, inviteToGarden, managePermissions
• Privacy: exportData, deleteAccount, manageDataPermissions

Out of Scope

Capability	Why excluded
Full e-commerce checkout (credit card payment in app)	Future v1.5+
Subscription / recurring purchases	Future v1.2
Multi-tenant marketplace (browse multiple nurseries actively)	Future v2.0
Plant trading marketplace	Future v1.5+
Augmented reality plant placement	Future v2.0
AI-driven garden design (full layout generation)	v1.2 (basic in v1.0)
Customer financing / BNPL	Future
Wholesale tier viewing for B2B customers	Different product surface
Social media auto-posting	Future
Influencer partnerships	Out of scope
Voice assistant integration (Siri/Alexa)	Future v2.0
Watering automation integration (smart sprinklers)	Future v2.0
Plant identification database licensing	Defer; using AI
Premium content (paid courses)	Defer
Plant care subscription boxes	Defer
Plant photo home screen widgets	Future