🛍️ Shopify Insights - Multi-tenant Data Ingestion & Analytics Platform

A production-ready, multi-tenant platform for ingesting Shopify store data and providing actionable business insights through beautiful dashboards and analytics.

Built for the Xeno FDE Internship Assignment 2025

📋 Table of Contents

• Features
• Architecture
• Tech Stack
• Getting Started
• API Documentation
• Database Schema
• Screenshots
• Deployment

✨ Features

Core Features

• Multi-tenant Architecture: Support multiple Shopify stores with complete data isolation
• Shopify Data Ingestion: Sync customers, products, and orders from Shopify API
• Real-time Analytics: Revenue trends, order analytics, customer segmentation
• Beautiful Dashboard: Modern UI with interactive charts and visualizations
• Email Authentication: Secure login with NextAuth.js credentials provider

Data Ingestion

• Full and incremental sync support
• Pagination handling for large datasets
• Webhook support for real-time updates
• Sync logging and error tracking

Analytics & Insights

• Revenue over time (with configurable date ranges)
• Top selling products
• Customer segmentation (New, Returning, Loyal)
• Geographic distribution of orders
• Sales by hour of day
• Order status distribution
• Repeat customer rate

Bonus Features

• Custom event tracking (cart abandonment, checkouts)
• Webhook handler for Shopify events
• Sync history and logging

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                              FRONTEND                                    │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                    Next.js 15 App Router                         │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │   │
│  │  │Dashboard │ │Customers │ │ Products │ │  Orders  │           │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │   │
│  │  ┌──────────┐ ┌──────────┐                                      │   │
│  │  │Analytics │ │ Settings │   Recharts Visualizations            │   │
│  │  └──────────┘ └──────────┘                                      │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                              API LAYER                                   │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                    Next.js API Routes                            │   │
│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │   │
│  │  │  /api/auth   │ │ /api/tenants │ │/api/webhooks │            │   │
│  │  │  - register  │ │ - CRUD       │ │  - shopify   │            │   │
│  │  │  - login     │ │ - sync       │ │              │            │   │
│  │  │  - session   │ │ - analytics  │ │              │            │   │
│  │  └──────────────┘ └──────────────┘ └──────────────┘            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    ▼               ▼               ▼
┌────────────────────────┐ ┌────────────────┐ ┌────────────────────────┐
│    SERVICE LAYER       │ │   SHOPIFY API  │ │     DATABASE           │
│ ┌────────────────────┐ │ │                │ │ ┌────────────────────┐ │
│ │   SyncService      │◄┼─┤  REST API v1   │ │ │    PostgreSQL      │ │
│ │   - syncCustomers  │ │ │  - Customers   │ │ │                    │ │
│ │   - syncProducts   │ │ │  - Products    │ │ │  ┌──────────────┐  │ │
│ │   - syncOrders     │ │ │  - Orders      │ │ │  │   Tenants    │  │ │
│ │   - syncAll        │ │ │  - Webhooks    │ │ │  ├──────────────┤  │ │
│ └────────────────────┘ │ │                │ │ │  │   Users      │  │ │
│ ┌────────────────────┐ │ └────────────────┘ │ │  ├──────────────┤  │ │
│ │ AnalyticsService   │ │                    │ │  │  Customers   │  │ │
│ │   - getStats       │◄┼────────────────────┼─┤  ├──────────────┤  │ │
│ │   - getRevenue     │ │                    │ │  │  Products    │  │ │
│ │   - getTopProducts │ │                    │ │  ├──────────────┤  │ │
│ │   - getSegments    │ │                    │ │  │   Orders     │  │ │
│ └────────────────────┘ │                    │ │  └──────────────┘  │ │
└────────────────────────┘                    │ │  Prisma ORM        │ │
                                              │ └────────────────────┘ │
                                              └────────────────────────┘

Multi-tenant Data Flow

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Tenant A   │     │   Tenant B   │     │   Tenant C   │
│  Store: X    │     │  Store: Y    │     │  Store: Z    │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       ▼                    ▼                    ▼
┌──────────────────────────────────────────────────────────┐
│                    API Layer                              │
│              (Authentication + Authorization)             │
│    - Verify JWT Token                                     │
│    - Check Tenant Access                                  │
│    - Route to Correct Tenant Data                         │
└──────────────────────────────────────────────────────────┘
       │                    │                    │
       ▼                    ▼                    ▼
┌──────────────────────────────────────────────────────────┐
│                   PostgreSQL Database                     │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐        │
│  │  Tenant A   │ │  Tenant B   │ │  Tenant C   │        │
│  │   Data      │ │   Data      │ │   Data      │        │
│  │ (Isolated)  │ │ (Isolated)  │ │ (Isolated)  │        │
│  └─────────────┘ └─────────────┘ └─────────────┘        │
└──────────────────────────────────────────────────────────┘

🛠️ Tech Stack

Category	Technology
Framework	Next.js 15 (App Router)
Language	TypeScript
Database	PostgreSQL
ORM	Prisma
Authentication	NextAuth.js v4
Styling	Tailwind CSS v4
Charts	Recharts
API Client	Axios
Date Utils	date-fns

🚀 Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL database (or use Prisma Postgres)
• Shopify store with Admin API access

Installation

1. Clone the repository

   cd shopify-insights

2. Install dependencies

   npm install

3. Configure environment variables

   cp .env.example .env

   Edit .env with your configuration:

   DATABASE_URL="postgresql://user:password@localhost:5432/shopify_insights"
   NEXTAUTH_URL="http://localhost:3000"
   NEXTAUTH_SECRET="your-secret-key"

4. Initialize the database

   npx prisma db push

5. Start development server

   npm run dev

6. Open the app

   Navigate to http://localhost:3000

Connecting a Shopify Store

1. Create an account or log in
2. Go to Settings → Add Store
3. Enter your Shopify domain (e.g., my-store.myshopify.com)
4. Add your Shopify Admin API access token
5. Click "Connect Store"
6. Go to Dashboard and click "Sync Data"

📡 API Documentation

Authentication

Endpoint	Method	Description
/api/auth/register	POST	Register a new user
/api/auth/[...nextauth]	GET/POST	NextAuth.js authentication

Tenants

Endpoint	Method	Description
/api/tenants	GET	List user's tenants
/api/tenants	POST	Create/connect a new tenant
/api/tenants/[tenantId]	GET	Get tenant details
/api/tenants/[tenantId]	PATCH	Update tenant settings
/api/tenants/[tenantId]	DELETE	Delete a tenant

Data Sync

Endpoint	Method	Description
/api/tenants/[tenantId]/sync	POST	Trigger data sync
/api/tenants/[tenantId]/sync	GET	Get sync logs

Sync Request Body:

{
  "type": "full",       // "full", "customers", "products", "orders"
  "incremental": false  // true for delta sync
}

Analytics

Endpoint	Method	Query Params	Description
/api/tenants/[tenantId]/analytics	GET	metric=dashboard&days=30	Dashboard stats
/api/tenants/[tenantId]/analytics	GET	metric=revenue&days=30	Revenue by date
/api/tenants/[tenantId]/analytics	GET	metric=top-products&limit=10	Top products
/api/tenants/[tenantId]/analytics	GET	metric=customer-segments	Customer segments
/api/tenants/[tenantId]/analytics	GET	metric=geographic&limit=10	Geo distribution
/api/tenants/[tenantId]/analytics	GET	metric=order-status	Order status
/api/tenants/[tenantId]/analytics	GET	metric=sales-by-hour&days=30	Hourly sales

Data Endpoints

Endpoint	Method	Query Params
/api/tenants/[tenantId]/customers	GET	page, limit, search, sortBy, sortOrder
/api/tenants/[tenantId]/products	GET	page, limit, search, status, sortBy, sortOrder
/api/tenants/[tenantId]/orders	GET	page, limit, search, financialStatus, fulfillmentStatus

Webhooks

Endpoint	Method	Description
/api/webhooks/shopify	POST	Shopify webhook handler

📊 Database Schema

Core Entities

User ─────────┬───── TenantUser ─────┬───── Tenant
              │                      │
              │                      ├───── Customer
              │                      │         └── CustomerAddress
              │                      │         └── Order
              │                      │
              │                      ├───── Product
              │                      │         └── ProductVariant
              │                      │         └── OrderLineItem
              │                      │
              │                      ├───── Order
              │                      │         └── OrderLineItem
              │                      │         └── OrderAddress
              │                      │
              │                      ├───── ShopifyEvent
              │                      │
              │                      └───── SyncLog

Key Relationships

• User ↔ Tenant: Many-to-many through TenantUser (with roles)
• Tenant → Customer/Product/Order: One-to-many (tenant isolation)
• Customer ↔ Order: One-to-many
• Product ↔ OrderLineItem: One-to-many
• Order ↔ OrderLineItem: One-to-many

📸 Screenshots

Landing Page

Modern landing page with feature highlights and call-to-action buttons.

Dashboard

Overview with key metrics, revenue charts, and quick insights.

Analytics

Deep dive analytics with multiple chart types and date range filters.

Customers/Products/Orders

Data tables with search, filtering, and pagination.

Settings

Store management and sync history.

🚢 Deployment

Vercel (Recommended)

1. Push to GitHub
2. Import to Vercel
3. Add environment variables
4. Deploy

Docker

# Dockerfile included in repo
docker build -t shopify-insights .
docker run -p 3000:3000 shopify-insights

Environment Variables for Production

DATABASE_URL="postgresql://..."
NEXTAUTH_URL="https://your-domain.com"
NEXTAUTH_SECRET="generate-secure-secret"

📝 License

MIT License - Built for Xeno FDE Internship Assignment 2025

---

Author: Built with ❤️ for Xeno