Welcome to POSTrack

Complete Point of Sale System Documentation

About POSTrack

POSTrack is a comprehensive inventory operations platform that unifies product catalogs, suppliers, clients, orders, and warehouse stock levels into a single command center. Built with modern web technologies, it gives operations teams a real-time view of inventory health across every location.

The application combines operational workflows with analytics and AI-assisted recommendations so teams can forecast demand, avoid stockouts, and streamline procurement-to-fulfillment cycles.

Operations teams monitor stock positions, transfers, and order fulfillment without leaving the dashboard.
Supply chain leaders track KPIs, analyze movement trends, and leverage forecasting to plan replenishment.
Administrators configure organizations, roles, and automation rules to fit each business unit.

Core Capabilities

Dashboard & Analytics: At-a-glance KPIs, category insights, supplier contribution charts, and recent activity feeds.
Product & Catalog Management: SKU-level controls, category hierarchies, pricing, media attachments, and bulk actions.
Multi-Location Inventory: Automatic quantity tracking per site, reserved stock calculations, and granular stock movement history.
Order Lifecycle: Purchase and sales order pipelines with receiving, cancellation, and fulfillment workflows that sync with inventory.
Partners Directory: Dedicated supplier and client modules with searchable contact information and role-based permissions.
Reporting & Insights: Critical stock alerts, stock summaries, purchase/sales performance, slow-moving goods, and OpenAI-powered forecasts.
Governance & Audit: Role-based access control, configurable settings, activity logs, and secure file/document management.

System Requirements

Node.js: Version 20 or higher (tested with Node 20 and 22) plus npm 10+
MySQL: Version 8.0+ (minimum 5.7) with a user that can create databases, tables, and triggers
Developer Tools: Git for version control and a terminal with Bash or PowerShell
RAM: Minimum 4GB (8GB recommended for running client and server simultaneously)
Storage: At least 3GB free space for dependencies, database files, and build artifacts
Optional Integrations: OpenAI API key for advanced forecasting, cross-sell, and pricing insights
Operating System: Windows 10+, macOS 10.15+, or Linux (Ubuntu 20.04+)

Frontend

React 19 with TypeScript

Vite dev/build tooling with Tailwind CSS + RTL support

Radix UI, TanStack Query, React Hook Form, Zod validation

Backend

Node.js (Express 5) REST API

Sequelize ORM with MySQL2 driver and migrations

JWT auth, Multer file uploads, OpenAI-assisted insights

Data & Automation

MySQL schema with seeders for roles, users, and defaults

Inventory & reserved quantity calculators kept in sync via hooks

Utility scripts for data maintenance and status reconciliation

Operations

Multi-location inventory with stock movement tracking

Purchase & sales order lifecycle with automatic reservations

Comprehensive reporting, forecasting, and audit history

Quick Start Guide

Install system prerequisites (Node.js 20+, npm 10+, Git, and MySQL 8+) if they are not already available.
Clone or download the POSTrack repository and open the project in your preferred editor.
Start MySQL and create an empty database to match your desired
```
DB_NAME
```
(the defaults use
```
common_project_dev
```
).
Navigate to the
```
server
```
directory and run
```
npm install
```
to install backend dependencies.

Create

server/.env

with values such as

DB_HOST

DB_PORT

DB_NAME

DB_USERNAME

DB_PASSWORD

JWT_SECRET

, and optionally

OPENAI_API_KEY

plus cache toggles.

Run
```
npm run db:migrate
```
to apply Sequelize migrations and create the schema.
Run
```
npm run db:seed
```
to bootstrap roles, the admin user, and sample configuration.
Launch the backend with
```
npm run dev
```
; the API listens on
```
http://localhost:3000
```
by default.
Open a new terminal, navigate to the
```
client
```
directory, and run
```
npm install
```
to install frontend dependencies.
Create
```
client/.env
```
and set
```
VITE_API_URL=http://localhost:3000/api
```
(adjust if the server runs on another host or port).
Start the client with
```
npm run dev
```
and visit
```
http://localhost:5173
```
to load the app.
Sign in with the seeded admin credentials
```
admin@example.com
```
/
```
admin123
```
, then update organization settings, locations, and users as needed.

Windows Setup

Complete installation guide for Windows 10/11 systems with step-by-step instructions

View Windows Guide

Linux Setup

Detailed setup instructions for Ubuntu, CentOS, and other Linux distributions

View Linux Guide

macOS Setup

Installation guide for macOS systems including Homebrew setup

View macOS Guide

Server Configuration

Production deployment, security, and server optimization guide

View Server Guide