# 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

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd onmart-pos-backend
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Configure environment variables**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

4. **Set up database**
   ```bash
   # Create database
   createdb onmart_pos_dev
   
   # Run migrations
   npx sequelize-cli db:migrate
   
   # Seed initial data
   npx sequelize-cli db:seed:all
   ```

5. **Start the server**
   ```bash
   npm start
   ```

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

### Default Login Credentials

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](docs/BACKEND.md)** - Complete API reference, authentication, and development guide
- **[Database Documentation](docs/DATABASE.md)** - Database schema, relationships, and query examples

### Quick Links

- [Installation Guide](docs/BACKEND.md#installation--setup)
- [API Endpoints](docs/BACKEND.md#api-endpoints)
- [Database Schema](docs/DATABASE.md#database-schema)
- [Environment Variables](docs/BACKEND.md#environment-variables)

## 🏗️ 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](docs/BACKEND.md#api-endpoints).

## 🛠️ 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

```bash
# 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):

```env
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](docs/DATABASE.md).

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. 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:

1. **[Backend Documentation](docs/BACKEND.md)** - Understand the API architecture and endpoints
2. **[Database Documentation](docs/DATABASE.md)** - Learn the database structure and relationships
3. **Environment Setup** - Follow the Quick Start guide above
4. **Test the API** - Use the default credentials to explore the system

### Recommended Reading Order

1. Installation & Setup
2. Database Schema Overview
3. Authentication Flow
4. API Endpoints Reference
5. Code Structure & Organization

---

**Version:** 1.0.0  
**Last Updated:** February 9, 2026