TuckShop

A modern point-of-sale (POS) and inventory management system designed for small convenience stores and tuck shops. Built with React, TypeScript, Express, and PostgreSQL.

Features

Core Functionality

• Point of Sale (POS): Quick checkout system for processing sales
• Inventory Management: Track products with real-time stock levels
• Category Management: Organize products by categories
• Stock Movement Tracking: Complete audit trail of all inventory changes
• Dashboard Analytics: Real-time business metrics and insights

Advanced Features

• Refund & Return System: Reversible operations instead of deletions
• Stock Validation: Prevents negative stock levels across all operations
• Date Filtering: Filter stock movements by date range
• PDF Reports: Export data from inventory, stock movements, and dashboard
• Low Stock Alerts: Automatic notifications when items fall below safety levels
• Audit Trail: Product names preserved even after deletion

Tech Stack

Frontend

• React 19 with TypeScript
• Material-UI (MUI) v7
• Vite for build tooling
• jsPDF for PDF generation

Backend

• Node.js with Express
• TypeScript
• Knex.js for database migrations and queries
• PostgreSQL database

Project Structure

TuckShop/
├── server/                    # Backend application
│   ├── src/
│   │   ├── handlers/         # Route handlers
│   │   ├── services/         # Business logic
│   │   ├── index.ts          # Server entry point
│   │   └── knex.ts           # Database configuration
│   ├── migrations/           # Database migrations
│   └── seeds/                # Initial data
└── tuckshop_client/          # Frontend application
    └── src/
        ├── components/       # Reusable UI components
        ├── pages/            # Main application pages
        ├── api/              # API service layer
        └── types/            # TypeScript definitions

Getting Started (Local Development)

Prerequisites

• Node.js (v22 or higher)
• PostgreSQL database
• npm or yarn package manager

Installation

1. Clone the repository

   git clone <repository-url>
   cd TuckShop

2. Setup Backend

   cd server
   npm install

Create a .env file in the server directory:

   PG_HOST=localhost
   PG_USER=your_db_user
   PG_PASSWORD=your_db_password
   PG_DATABASE=tuckshop_db
   PG_PORT=5432
   SERVER_PORT=5000

Run migrations:

   npx knex migrate:latest
   npx knex seed:run

3. Setup Frontend

   cd ../tuckshop_client
   npm install

Running the Application

1. Start the backend server (from server directory):

   npm run start

Server runs on http://localhost:5000

2. Start the frontend (from tuckshop_client directory):

   npm run dev

Application runs on http://localhost:5173

Deployment

This project is deployed across three free cloud services:

Service	Role	URL
Neon	PostgreSQL database	—
Render	Node.js backend	—
Vercel	React frontend	—

1. Database — Neon

• Sign up at neon.tech
• Create a new project and copy your connection credentials
• Update knexfile.ts to include ssl: { rejectUnauthorized: false } in the connection object
• Run migrations against Neon: npx knex migrate:latest && npx knex seed:run

2. Backend — Render

• Sign up at render.com and create a Web Service
• Connect your GitHub repository, set root directory to server
• Build command: npm install && npm run build
• Start command: node dist/src/index.js
• Add all PG_* and SERVER_PORT environment variables in the Render dashboard

3. Frontend — Vercel

• Sign up at vercel.com and import your GitHub repository
• Set root directory to tuckshop_client
• Add environment variable: VITE_API_URL=https://your-render-url.onrender.com

Important Notes

• Never commit your .env file — it is listed in .gitignore
• All secrets should be set as environment variables in Render and Vercel dashboards
• The university/corporate network may block port 5432 — use a hotspot for local DB operations

Usage Guide

Dashboard

View key business metrics including:

• Daily revenue and transaction count
• Refunds processed today
• Total inventory value
• Active categories
• Low stock alerts
• Most popular items (last 30 days)

Point of Sale (POS)

1. Select products from the catalog
2. Adjust quantities as needed
3. Process sale with automatic stock deduction
4. Generate refunds for returned items

Inventory Management

• Add, edit products
• View current stock levels
• Export inventory reports to PDF
• Monitor product categories

Admin Panel

• Categories: Create and manage product categories
• Stock Movements: View complete history of all stock changes
  • Filter by date range
  • Track SALE, PURCHASE, REFUND, RETURN, ADJUSTMENT types
  • Export to PDF for reporting

Stock Movement Types

• SALE: Deducts stock when items are sold
• PURCHASE: Adds stock when inventory is received
• REFUND: Reverses a SALE (adds stock back)
• RETURN: Reverses a PURCHASE (removes stock)
• ADJUSTMENT: Manual corrections (positive or negative)

Key Design Decisions

1. No Hard Deletes: Products can't be permanently deleted; audit trail is preserved
2. Reversible Operations: Refunds and returns instead of delete operations
3. Stock Validation: Database and application-level checks prevent negative stock
4. Audit Trail: Product names stored in stock movements survive product deletion

Database Schema

Key tables:

• categories: Product categories
• products: Product catalog with pricing and stock levels
• sales: Transaction records
• sale_items: Individual items in each sale
• stockmovements: Complete audit trail of inventory changes

Development Notes

• TypeScript strict mode enabled
• ESLint configured for code quality
• No use of any type or innerHTML
• Material-UI custom theme applied
• Responsive design for mobile and desktop