Complete doc

📋 Overview

OnMart POS Backend is a full-featured RESTful API for managing retail operations. It provides comprehensive features for product management, transaction processing, inventory tracking, cashier shift management, and customer relationship management.

✨ Key Features

🔐 JWT Authentication & Authorization - Secure role-based access control
👥 Multi-Role User Management - MasterAdmin, SuperAdmin, Admin, Cashier
🏪 Multi-Outlet Support - Manage multiple store locations
📦 Product Management - Categories, brands, barcodes, and inventory
💰 Transaction Processing - Complete POS functionality with void/refund
🕐 Shift Management - Track cashier shifts and sales
🎁 Promotional System - Flexible discount management
👤 Customer Management - Customer profiles and transaction history
📊 Dashboard & Reporting - Sales analytics and insights
📄 Invoice Generation - PDF receipt printing
📥 Import/Export - CSV and Excel support

🚀 Quick Start

Prerequisites

Node.js v16 or higher
PostgreSQL v12 or higher
npm or yarn

Installation

Clone the repository

git clone <repository-url>
cd onmart-pos-backend

Install dependencies
```
npm install
```

Configure environment variables

cp .env.example .env
# Edit .env with your configuration

Set up database

# Create database
createdb onmart_pos_dev

# Run migrations
npx sequelize-cli db:migrate

# Seed initial data
npx sequelize-cli db:seed:all

Start the server
```
npm start
```

The server will be running at http://localhost:3000 🎉

After seeding, you can log in with these accounts:

Role	Email	Password
MasterAdmin	masteradmin@mail.com	password
SuperAdmin	superadmin@mail.com	password
Admin	admin@mail.com	password
Cashier	cashier@mail.com	password

⚠️ Important: Change these passwords in production!

📚 Documentation

Comprehensive documentation is available in the /docs folder:

Backend Documentation - Complete API reference, authentication, and development guide
Database Documentation - Database schema, relationships, and query examples

Quick Links

🏗️ Project Structure

onmart-pos-backend/
├── config/              # Database configuration
├── controllers/         # Business logic
├── docs/               # Documentation
│   ├── BACKEND.md     # Backend & API documentation
│   └── DATABASE.md    # Database documentation
├── helpers/            # Utility functions
├── middlewares/        # Express middlewares
├── migrations/         # Database migrations
├── models/            # Sequelize models
├── routes/            # API routes
├── seeders/           # Database seeders
├── uploads/           # File uploads
├── utils/             # Utilities
├── index.js           # Entry point
└── package.json       # Dependencies

🔑 API Endpoints

Base URL: http://localhost:3000/api

Core Endpoints

Category	Endpoint	Description
Auth	`POST /auth/login`	User login
Auth	`GET /auth/me`	Get current user
Products	`GET /products`	List products
Products	`POST /products`	Create product
Transactions	`POST /transactions`	Create transaction
Cashier	`POST /cashier/shifts/open`	Open shift
Dashboard	`GET /dashboard/summary`	Dashboard stats

For complete API documentation, see BACKEND.md.

🛠️ Tech Stack

Runtime: Node.js
Framework: Express v5.1.0
Database: PostgreSQL
ORM: Sequelize v6.37.7
Authentication: JWT (jsonwebtoken)
Security: Helmet, CORS, bcrypt
File Processing: Multer, Sharp
PDF Generation: PDFKit
Data Processing: fast-csv, xlsx
Logging: Morgan

🔐 Security Features

✅ JWT-based authentication
✅ Password hashing with bcrypt
✅ Role-based authorization
✅ Security headers (Helmet)
✅ CORS protection
✅ Input validation
✅ SQL injection prevention (Sequelize ORM)

💻 Development

Database Commands

# Run migrations
npx sequelize-cli db:migrate

# Undo last migration
npx sequelize-cli db:migrate:undo

# Run seeders
npx sequelize-cli db:seed:all

# Database reset
npx sequelize-cli db:migrate:undo:all
npx sequelize-cli db:migrate
npx sequelize-cli db:seed:all

Environment Variables

Key environment variables (see .env.example for all options):

PORT=3000
NODE_ENV=development
DB_USERNAME=postgres
DB_PASSWORD=your_password
DB_NAME=onmart_pos_dev
DB_HOST=localhost
JWT_SECRET=your_jwt_secret
ORIGIN_CORS=http://localhost:3711

📊 Database Schema

The system uses 16 tables with proper relationships:

Users & Roles - Authentication and authorization
Products - Inventory with categories and brands
Transactions - Sales records with items
Shifts - Cashier working periods
Customers - Customer information
Promos - Promotional campaigns
Outlets - Store locations

For detailed schema information, see DATABASE.md.

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the ISC License.

📧 Support

For questions or support:

Open an issue in the repository
Contact the development team

🗂️ For New Developers

If you're taking over this project, start with these documents:

Backend Documentation - Understand the API architecture and endpoints
Database Documentation - Learn the database structure and relationships
Environment Setup - Follow the Quick Start guide above
Test the API - Use the default credentials to explore the system