Retail Sales Management System

1. Overview

Retail Sales Management System is a full-stack web application that enables efficient exploration and management of large-scale retail sales data. It provides advanced search, multi-select filtering, sorting, and pagination to analyze sales performance across customers, regions, products, and payment types. The system demonstrates production-grade architecture with clear separation of frontend and backend responsibilities.

2. Tech Stack

Frontend: React (Vite) · TypeScript · Tailwind CSS · shadcn/ui
Backend: Express.js · TypeScript · Pg · PostgresSQL
Utilities: dayjs · fast-csv · node-fetch · react-error-boundary
Build Tools: Vite · ts-node-dev

3. Search Implementation Summary

• Implements full-text search across Customer Name and Phone Number.
• Case-insensitive matching using toLowerCase() comparisons.
• Search integrates seamlessly with filters and sorting.
• Query is debounced (400ms) on the frontend to reduce API calls.
• Executed server-side for performance and scalability.

4. Filter Implementation Summary

• Supports multi-select and range-based filters for:
  • Region, Gender, Product Category, Tags, Payment Method
  • Age Range (Min–Max) and Date Range (From–To)
• Filters work independently and in combination.
• Maintains state with search and sorting parameters.
• Handled using dynamic SQL-like filtering in backend service.
• Robust handling for edge cases (empty, conflicting, invalid filters).

5. Sorting Implementation Summary

• Supports sorting by:
  • Date (Newest First)
  • Quantity (Ascending/Descending)
  • Customer Name (A–Z)
• Sorting logic applied on filtered dataset before pagination.
• Preserves active search and filters between sort operations.

6. Pagination Implementation Summary

• Backend paginates using SQL LIMIT and OFFSET.
• Frontend shows dynamic pagination control with ellipsis (...) and Prev/Next buttons.
• Each page loads 10 items (configurable).
• Maintains search/filter/sort state during navigation.
• Gracefully handles large datasets (1M+ rows) with SQLite.

7. Setup Instructions

🧩 Prerequisites

• Node.js ≥ 18
• npm ≥ 9

Backend Setup

cd backend
npm install
npm run load-csv  # load csv data into db
npm run dev        # run backend server on 4000

Frontend Setup

cd frontend
npm install
npm run dev        

Folder Structure

root/
├── backend/
├── frontend/
└── docs/