Pulse Commerce OS

Pulse Commerce OS is a full-stack e-commerce decision intelligence platform built to showcase modern data science, analytics engineering, and product-thinking inside a clean operator-facing application.

Instead of acting like a generic store dashboard, the project is framed as a command center for growth, retention, demand planning, inventory monitoring, and decision support.

Why this project exists

This repo is designed as a portfolio-grade build that demonstrates how data science concepts can live inside a real product experience:

• business KPI design
• descriptive analytics and cohort analysis
• customer intelligence and churn-risk storytelling
• demand forecasting and operational alerts
• authentication and protected data workflows
• polished frontend and API-backed architecture

What it includes

• frontend/ - Next.js dashboard UI with login/signup, multi-view analytics workspace, and API-driven data loading
• backend/ - FastAPI service with auth, dashboard endpoints, CSV upload support, and SQLite persistence
• data/ - seeded CSVs for revenue, churn watchlist, and demand forecast
• analysis/ - Python utility script for quick metric validation
• docs/ - product blueprint and roadmap for future expansion

Product capabilities

• Executive KPIs for revenue, margin, retention, and refund health
• Cohort retention and RFM-style customer intelligence
• Churn watchlist and demand forecasting
• Inventory, fraud, and anomaly alerting
• Growth experiment queue and AI recommendation feed
• Local signup/login flow with persisted sessions
• Revenue CSV upload flow through the Data Studio workspace

Architecture

Frontend

• Next.js App Router
• TypeScript
• custom dashboard components
• local session persistence in the browser

Backend

• FastAPI
• Pydantic schemas
• SQLite for lightweight local persistence
• CSV-backed initial seeding

Data layer

• weekly_revenue.csv
• customer_risk.csv
• demand_forecast.csv

These are seeded into the backend and exposed through API responses for the dashboard.

Current workflow

1. Create an account or sign in from the frontend.
2. Load the dashboard views for overview, customers, demand, growth, risk, AI recommendations, and data studio.
3. Upload a revenue CSV from the Data Studio tab.
4. Refresh the dashboard to see KPI and trend changes based on the imported data.

Run the backend

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8001

Run the frontend

In a second terminal:

cd frontend
npm install
npm run dev

Then open:

http://localhost:3000

If port 8001 is busy, run the backend on 8002 and start the frontend like this:

cd frontend
NEXT_PUBLIC_API_URL=http://127.0.0.1:8002 npm run dev

API endpoints

• GET /health - service health check
• POST /auth/signup - create a local user
• POST /auth/login - sign in and receive a bearer token
• GET /auth/me - get the current authenticated user
• GET /dashboard - load dashboard data
• POST /uploads/revenue - upload a weekly revenue CSV