StoreStock: Vision & Concept

Tier Mix Assumptions Used

• Starter: 60% of merchants @ $79/month
• Professional: 30% of merchants @ $249/month
• Business: 10% of merchants @ $549/month

This reflects realistic adoption: most merchants start on Starter, fewer graduate to higher tiers.

Tier Mix Assumptions Used

• Starter: 60% of merchants @ $79/month
• Professional: 30% of merchants @ $249/month
• Business: 10% of merchants @ $549/month

Used consistently across all projections below.

Customer Journey (pre-location permission):

1. Lands on product page
2. Sees “Available at V&A Waterfront · 5 in stock” (no distance)
3. Clicks “View all locations”
4. Drawer opens with store list (no distance, no proximity sorting)
5. Clicks “Get directions” (destination-only link)

Customer Journey (after allowing location):

1. Customer taps “Enable location to sort by distance” (CTA in block or drawer)
2. Browser requests location permission
3. Distances appear and list can sort by closest/farthest
4. Google Maps opens with route (start + end) when tapping directions
5. Customer can Update location or Clear location at any time

Technical flow: Theme App Extension → App proxy → Fetch inventory from Shopify → Merge with location data → (If lat/lng) calculate distances → Return list + permission state

Customer Journey:

1. Visits store locator page/section
2. Sees interactive map with pins for all locations
3. Searches “Sandton” or uses “Use my location”
4. Filters by “Open now” and store attributes
5. Clicks store card to view details (hours, contact, mall context)
6. Clicks “Get directions” or “Check stock”

Customer Journey:

1. On product page, selects store for pickup (pre-checkout) and chooses a time slot
2. Adds to cart with store preference
3. At checkout, local pickup is aligned to the chosen store
4. Completes checkout
5. Receives email confirmation, then WhatsApp/email when ready

Staff Journey:

1. Staff views pickup queue (dashboard or POS tile)
2. Staff picks items, then marks ready
3. Customer receives WhatsApp + email
4. Customer collects, staff marks collected

Staff Journey (POS):

1. Staff opens POS, sees “StoreStock Pickups” tile with badge
2. Taps tile, sees pickup queue for this location
3. Marks ready from POS
4. Customer gets WhatsApp notification
5. Marks collected when customer arrives

Network Stock Visibility:

1. Customer asks in-store about a size/variant
2. Staff checks StoreStock network view
3. Shows which store has stock
4. Staff initiates transfer request if needed

• Remix: React framework for Shopify apps (official template)
• Polaris: Shopify's design system for admin UI
• Theme App Extensions: Liquid + JavaScript for storefront blocks
• Vanilla JavaScript: For storefront drawer/modal (no framework bloat)

• Node.js: Runtime environment
• Remix (server): Routing, loaders, actions
• Prisma ORM: Type-safe queries and migrations
• PostgreSQL: Multi-tenant database for shops, locations, settings

• GCP Cloud Run: Containerized hosting (auto-scaling)
• GCP Cloud SQL: Managed PostgreSQL database
• GCP Secret Manager: API keys and credentials
• GCP Cloud Build: CI/CD pipeline

• Admin API (GraphQL): Locations, inventory levels, webhooks
• Storefront API (GraphQL): Inventory + product/variant context
• App Proxy: Storefront requests routed to our backend
• Billing API: Subscription management and plan gating
• POS Extensions API: Tiles and actions (Business plan)

• Google Geocoding API: Address → coordinates
• Google Maps JavaScript API: Locator map
• Twilio/MessageBird WhatsApp API: Pickup notifications (Business plan)

Required Webhooks

• APP_UNINSTALLED - Clean up shop data
• LOCATIONS_CREATE - New location added (prompt to import)
• LOCATIONS_UPDATE - Location details changed
• LOCATIONS_DELETE - Location removed
• INVENTORY_LEVELS_UPDATE - Optional for caching optimisations

Project Context

PROJECT: StoreStock - Shopify App
PURPOSE: Store availability + locator + omnichannel ops (Click & Collect + POS)
TARGET: Multi-location retailers
MARKET: SA-first UX improvements
TECH: Remix + Prisma + Postgres + GCP + Shopify APIs

PHASES:
1) Starter MVP: availability + drawer + email alerts + privacy-first location
2) Professional: locator map + SA search + schema + dashboard + billing
3) Business: Click & Collect ops + POS tile + network stock + transfers + WhatsApp notifications

PRICING:
- Starter: $79/mo (~R1,500)
- Professional: $249/mo (~R4,700)
- Business: $549/mo (~R10,500)

Key Technical Decisions

FRAMEWORK: Remix (Shopify official template)
DATABASE: PostgreSQL (Cloud SQL)
ORM: Prisma
ADMIN UI: Shopify Polaris
STOREFRONT: Theme App Extensions + Vanilla JS
HOSTING: GCP Cloud Run

SECURITY:
- Filter all DB queries by shopId
- Encrypt tokens/keys at rest
- Validate webhook signatures

PERFORMANCE:
- Cache geocoding results
- Debounce storefront requests
- Index by shopId, suburb, city
- Only compute distances after explicit customer permission (lat/lng present)

API Contract (Availability Check)

// GET /apps/store-availability/check

Request:
  ?product_id=123
  &variant_id=456
  &lat=-33.9036 (optional; only after permission)
  &lng=18.4208 (optional; only after permission)

Response:
{
  "hasCustomerLocation": false,
  "locations": [
    {
      "id": "uuid",
      "name": "Sandton City",
      "address": "...",
      "suburb": "Sandton",
      "latitude": -26.1076,
      "longitude": 28.0567,
      "distance": null,
      "stockLevel": 5,
      "businessHours": { "mon": { "open": "09:00", "close": "18:00" } },
      "isOpen": true,
      "phone": "...",
      "whatsAppNumber": "..."
    }
  ]
}