🛍️ Shop-Sense — Shopify Survey App

Know exactly how your customers found you. Shop-Sense drops a lightweight "How did you hear about us?" survey into your Shopify storefront and turns the answers into a clean, Polaris-powered analytics dashboard.

---

✨ Why Shop-Sense?

Attribution is one of the hardest things for a store owner to measure. Ad platforms take credit, referrals go untracked, and "word of mouth" is invisible. Shop-Sense asks the customer directly — right at checkout — and stores every answer so you can see which channels actually drive sales.

• 📋 One-tap survey injected into your storefront cart/checkout — no theme rebuild required.
• 🎯 Source attribution (Social Media · Search Engine · Friend · Other) captured per response.
• 📊 Merchant dashboard built with Shopify Polaris for a native admin look and feel.
• 🧱 Clean REST API you can extend with new questions, product data, or exports.
• 🐳 Dockerized backend for one-command deployment anywhere.

---

🏗️ Architecture

Shopify Storefront                Frontend (Next.js)            Backend (Express + MongoDB)
┌────────────────────┐           ┌────────────────────┐        ┌──────────────────────────┐
│ inject-survey.js   │           │  /            Home │        │  GET  /api/products      │
│  "How did you hear │──POST────▶│  /dashboard  Admin │──────▶ │  POST /api/survey/submit │
│   about us?"       │           │  Polaris UI + proxy│        │  GET  /api/survey/...    │
└────────────────────┘           └────────────────────┘        │        ⇩ Mongoose        │
                                                                │      MongoDB Atlas       │
                                                                └──────────────────────────┘

Layer	Stack	Location
Storefront widget	Vanilla JS injected into the cart	backend/scripts/inject-survey.js
Backend API	Node.js · Express (ESM) · Mongoose	backend/
Frontend	Next.js 15 · React 18 · Shopify Polaris · Tailwind CSS	frontend/
Admin dashboard	Polaris IndexTable	frontend/pages/dashboard.js

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• A MongoDB connection string (local or MongoDB Atlas)

1️⃣ Clone & install

git clone https://github.com/topshopifydev/Shopify-Survey-App.git
cd Shopify-Survey-App

# Backend
cd backend && npm install

# Frontend
cd ../frontend && npm install

2️⃣ Configure environment

Create backend/.env:

MONGO_URI=mongodb+srv://<user>:<password>@<cluster>/shop-sense
PORT=5000

3️⃣ Run in development

# Terminal 1 — API on http://localhost:5000
cd backend && npm run dev

# Terminal 2 — Web app on http://localhost:3000
cd frontend && npm run dev

The frontend proxies /api/* to the backend automatically (see frontend/next.config.js), so no CORS wrangling in dev.

---

🔌 API Reference

Method	Endpoint	Description
GET	/api/products	Returns the demo product catalog
POST	/api/survey/submit	Saves a survey response — body: { "source": "social_media" }
GET	/api/survey/responses	Returns all collected survey responses
GET	/	Health check

Example — submit a response:

curl -X POST http://localhost:5000/api/survey/submit \
  -H "Content-Type: application/json" \
  -d '{"source":"search_engine"}'

---

🧩 Embedding the survey in your Shopify theme

Include inject-survey.js in your theme (or via a script tag / theme app extension). It looks for a .cart element, appends the survey form, and posts answers to /api/survey/submit — no duplicate forms, with inline success/error messaging.

---

🐳 Docker

cd backend
docker build -t shop-sense-backend .
docker run -p 5000:5000 --env-file .env shop-sense-backend

---

🗂️ Project Structure

Shopify-Survey-App/
├── backend/
│   ├── server.js               # Express app + products API
│   ├── routes/survey.js        # Survey submit / responses endpoints
│   ├── models/SurveyResponse.js# Mongoose schema
│   ├── config/db.js            # MongoDB connection
│   ├── scripts/inject-survey.js# Storefront survey widget
│   └── Dockerfile
└── frontend/
    ├── pages/
    │   ├── index.js            # Home + product list
    │   └── dashboard.js        # Polaris survey dashboard
    ├── components/             # SurveyForm · ProductList · DataTable
    └── next.config.js          # API proxy config

---

🛣️ Roadmap

• Wire survey routes + MongoDB into server.js startup
• Configurable, multi-question surveys
• CSV / analytics export from the dashboard
• Official Shopify theme app extension
• Response charts & channel breakdown

---

🤝 Contributing

Contributions are welcome! Open an issue to discuss a feature, or fork the repo and submit a pull request. If Shop-Sense helps you, please ⭐ star the repo — it genuinely helps others discover it.

📄 License

Released under the MIT License.