CommercePulse

A production-ready SaaS analytics platform for e-commerce sellers. Multi-provider order synchronization with real-time analytics, revenue tracking, profit analysis, and comprehensive SKU insights.

Overview

CommercePulse provides a unified analytics dashboard that aggregates data from multiple e-commerce providers, enabling sellers to track orders, revenue, profit margins, and product performance across all their sales channels.

Architecture

• Backend: Express.js API with TypeScript, Prisma ORM, and BullMQ for job processing
• Frontend: Next.js 14 with React, Tailwind CSS, and Recharts for data visualization
• Worker: Background job processor for order synchronization
• Database: PostgreSQL with Prisma migrations
• Queue: Redis with BullMQ for distributed job processing
• WebSocket: Real-time metrics broadcasting

Screenshots

Authentication

Secure login interface with email and password authentication

User registration page with form validation

Dashboard & Analytics

Main analytics dashboard with revenue, profit, orders, and profit margin metrics

Comprehensive orders table with filtering, sorting, and pagination

Revenue tracking with daily trends, KPIs, and breakdown analysis

Profit analysis with trend charts, fee breakdown, and margin visualization

Top performing products with revenue and quantity metrics

Real-time sync monitoring with progress tracking and system metrics

Features

Analytics Dashboard

• Revenue Tracking: Daily revenue trends, KPIs, and breakdown analysis
• Profit Analysis: Profit margins, cost breakdown, and fee visualization
• Order Management: Paginated order list with filtering and sorting
• SKU Performance: Top products by revenue and quantity with drill-down details
• Sync Monitoring: Real-time sync job status with progress tracking

Multi-Provider Support

• Provider abstraction layer for easy integration
• Support for multiple e-commerce platforms
• Provider-specific data normalization

Authentication & Security

• JWT-based authentication
• Protected routes with auth guards
• Secure token storage

Data Filtering

• Global date range filtering with localStorage persistence
• Provider-based filtering
• Status-based order filtering

Tech Stack

Backend

• Node.js 18+
• Express.js
• TypeScript
• Prisma ORM
• BullMQ
• PostgreSQL
• Redis

Frontend

• Next.js 14
• React 18
• TypeScript
• Tailwind CSS
• Recharts
• Axios

Infrastructure

• Docker & Docker Compose
• pnpm workspaces (monorepo)

Getting Started

Prerequisites

• Node.js 18+
• pnpm 8+
• PostgreSQL 14+
• Redis 6+
• Docker (optional)

Installation

# Clone the repository
git clone https://github.com/engmaryamameen/commerce-pulse.git
cd commerce-pulse

# Install dependencies
pnpm install

# Generate Prisma client
pnpm prisma:generate

# Set up environment variables
cp apps/backend/.env.example apps/backend/.env
cp apps/frontend/.env.example apps/frontend/.env
cp apps/worker/.env.example apps/worker/.env

# Run database migrations
pnpm prisma:migrate

# Seed the database (optional)
pnpm prisma:seed

Development

# Run all services
pnpm dev:all

# Or run individually
pnpm dev:backend    # Backend API on :4000
pnpm dev:frontend   # Frontend on :3000
pnpm dev:worker     # Worker service

Production Build

# Build all packages
pnpm build

# Start production servers
cd apps/backend && pnpm start
cd apps/frontend && pnpm start
cd apps/worker && pnpm start

Project Structure

commerce-pulse/
├── apps/
│   ├── backend/          # Express API server
│   ├── frontend/         # Next.js application
│   ├── worker/           # Background job processor
│   └── mock-api/         # Mock provider API
├── packages/             # Shared packages
│   ├── config/          # ESLint, Prettier, TypeScript configs
│   ├── types/           # Shared TypeScript types
│   └── utils/           # Shared utilities
├── docker/              # Docker configurations
├── docs/                # Documentation
└── scripts/             # Utility scripts

API Endpoints

Analytics

• GET /api/v1/analytics/revenue - Get total revenue
• GET /api/v1/analytics/profit - Get profit analysis
• GET /api/v1/analytics/orders - Get paginated orders list
• GET /api/v1/analytics/top-skus - Get top performing SKUs
• GET /api/v1/analytics/daily-revenue - Get daily revenue breakdown
• GET /api/v1/analytics/skus/:sku - Get SKU details
• GET /api/v1/analytics/orders/date/:date - Get orders by date

Sync

• POST /api/v1/sync/start - Start sync job
• GET /api/v1/sync/status/:jobId - Get sync job status

Authentication

• POST /api/v1/auth/register - User registration
• POST /api/v1/auth/login - User login

System

• GET /api/v1/system/metrics - Get system metrics
• WS /ws/metrics - WebSocket for real-time metrics

Environment Variables

Backend

DATABASE_URL=postgresql://user:password@localhost:5432/commercepulse
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key
PORT=4000

Frontend

NEXT_PUBLIC_API_URL=http://localhost:4000

Worker

DATABASE_URL=postgresql://user:password@localhost:5432/commercepulse
REDIS_URL=redis://localhost:6379

Docker

# Start all services with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Testing

# Run type checking
pnpm typecheck

# Run linting
pnpm lint

Contributing

1. Create a feature branch from develop
2. Make your changes
3. Ensure all tests pass and linting is clean
4. Submit a pull request

License

See LICENSE file for details.

Author

Maryam Ameen (@engmaryamameen)

---

Built with ❤️ for e-commerce sellers