Telerus - Customer Analytics Platform

A modern full-stack web application for analyzing customer value based on order data. Built with React, Node.js, Express, and Tailwind CSS.

Features

• 🎯 Synthetic Data Generation: Automatically generates 1,000 customers and 10,000 orders on startup
• 📊 Customer Value Analysis: Identify top 10 most valuable customers within any date range
• 🎨 Beautiful UI: Modern, responsive interface built with Tailwind CSS
• ⚡ Real-time Search: Instant filtering and ranking of customers
• 📱 Responsive Design: Works seamlessly on desktop, tablet, and mobile devices

Tech Stack

Frontend

• React 18
• Tailwind CSS 3
• Axios
• Modern ES6+ JavaScript

Backend

• Node.js
• Express
• CORS
• dotenv for environment configuration

Project Structure

telerus/
├── client/                 # React frontend
│   ├── public/
│   │   └── index.html
│   ├── src/
│   │   ├── components/
│   │   │   ├── Header.js
│   │   │   ├── DateRangePicker.js
│   │   │   └── CustomerList.js
│   │   ├── App.js
│   │   ├── index.js
│   │   └── index.css
│   ├── package.json
│   ├── tailwind.config.js
│   └── postcss.config.js
├── server/                 # Node.js backend
│   ├── index.js
│   └── dataGenerator.js
├── package.json
├── .env                    # Environment variables (create this!)
├── .gitignore
└── README.md

Data Model

Customer

• id (Primary Key)
• firstName
• lastName
• street
• city
• state
• zipCode

Order

• id (Primary Key)
• customerId (Foreign Key to Customer.id)
• date (ISO 8601 formatted string)
• total (USD, range: $1.00 - $999.00)

Setup Instructions

Prerequisites

• Node.js (v14 or higher)
• npm or yarn

1. Install Dependencies

First, install the root dependencies:

npm install

Then install both server and client dependencies:

npm run install-all

Or manually:

# Install server dependencies
npm install

# Install client dependencies
cd client
npm install
cd ..

2. Configure Environment Variables

Create a .env file in the root directory:

# Server Configuration
PORT=5000
NODE_ENV=development

# Data Generation Configuration
NUM_CUSTOMERS=1000
NUM_ORDERS=10000

# Order Configuration
MIN_ORDER_TOTAL=1.00
MAX_ORDER_TOTAL=999.00

# Date Range (for synthetic data generation)
START_DATE=2024-01-01
END_DATE=2024-12-31

3. Run the Application

Development Mode (Recommended)

Run both server and client concurrently:

npm run dev

This will start:

• Backend API on http://localhost:5000
• React frontend on http://localhost:3000

Production Mode

Build the frontend:

npm run build

Start the server:

npm start

Then serve the built frontend using a static file server or configure Express to serve the build folder.

Usage

1. Open your browser to http://localhost:3000
2. Select a start date and end date using the date pickers
3. Click the "Search" button
4. View the top 10 most valuable customers ranked by their total order value within the selected date range

Example Queries

• Q1 Analysis: January 1 - March 31, 2024
• Full Year: January 1 - December 31, 2024
• Holiday Season: November 1 - December 31, 2024

API Endpoints

GET /api/health

Health check endpoint

Response:

{
  "status": "ok",
  "customers": 1000,
  "orders": 10000
}

GET /api/top-customers

Get top customers by date range

Query Parameters:

• startDate (required): Start date in YYYY-MM-DD format
• endDate (required): End date in YYYY-MM-DD format

Example:

GET /api/top-customers?startDate=2024-01-01&endDate=2024-12-31

Response:

[
  {
    "id": 42,
    "firstName": "John",
    "lastName": "Smith",
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "totalValue": 8542.50,
    "orderCount": 15
  },
  ...
]

Configuration

All configurable values are stored in the .env file:

Development Scripts

Features in Detail

Synthetic Data Generation

• Realistic customer names using common first and last names
• Random but realistic US addresses (street, city, state, ZIP)
• Orders distributed evenly across the year
• Random order totals between $1.00 and $999.00

Customer Value Calculation

• Filters orders within the specified date range
• Aggregates total order value per customer
• Ranks customers by total value in descending order
• Returns top 10 customers with order counts

UI/UX Features

• Gradient backgrounds for visual appeal
• Medal icons (🥇🥈🥉) for top 3 customers
• Responsive grid layouts
• Loading states with animated spinners
• Error handling with user-friendly messages
• Empty state handling
• Smooth transitions and hover effects

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT

Contributing

Feel free to submit issues and enhancement requests!

Notes

• All data is generated synthetically on server startup
• Data is stored in memory (no database required)
• Server restart will regenerate new random data
• The .env file is excluded from git for security

Troubleshooting

Port Already in Use

If port 5000 or 3000 is already in use, modify the PORT variable in .env or change the React port by setting PORT=3001 before running npm run client.

CORS Issues

The client is configured to proxy API requests to the backend. If you encounter CORS issues, ensure the proxy is correctly set in client/package.json.

Module Not Found

Run npm run install-all to ensure all dependencies are installed for both frontend and backend.