# Shippero POS & Inventory System - Full Specification

## 1. Overview

Multi-branch POS + Inventory + Accounting system.

Business:

- 2 branches (each has independent inventory)
- Selling ready-to-cook food (cheese, pastrami, strips, sauces, etc.)
- Purchases from suppliers (resellers)
- Full accounting system (double-entry)

Tech Stack:

- Backend: Laravel 11
- Frontend: Blade + Livewire 3 + Alpine.js
- UI: Bootstrap 5 + FontAwesome
- Charts: Chart.js
- UX Help: Intro.js
- Permissions: Spatie Laravel Permission

---

## 2. Core Modules

### 2.1 Authentication

- Login باستخدام:
    - phone (Egyptian format validation)
    - password

- No registration / no password reset
- Redirect to dashboard

---

### 2.2 Users & Roles

Roles:

- Admin
- Manager
- Cashier

Permissions:

- Managed باستخدام Spatie
- Role-based

---

### 2.3 Branches

- id
- name
- address

Each branch:

- has its own inventory
- has its own POS

---

### 2.4 Products System

#### Products

- id
- name
- sku (unique)
- barcode
- category_id
- is_active

#### Units

- piece / kg / box ... (multi-units supported)

#### Product Units

- conversion system (optional later)

#### Variants

- example:
    - size
    - flavor

- stored as:
  product_variants:
    - id
    - product_id
    - name (e.g. "Large", "Spicy")

---

### 2.5 Inventory (Critical)

#### Batches (IMPORTANT)

Each purchase creates a batch:

batches:

- id
- product_id
- variant_id (nullable)
- branch_id
- quantity
- remaining_quantity
- cost_price
- expiry_date
- created_at

#### Rules:

- FIFO selling
- Auto-select oldest valid batch
- Skip expired batches
- Prevent selling expired products

---

### 2.6 POS System

### UX:

- Full screen
- Touch friendly
- Fast operations
- Barcode scanner support

### Features:

- Scan barcode → auto add
- Search with Select2
- Add new customer inline:
    - name
    - phone

### Sale Flow:

1. Add items
2. System selects batches (FIFO)
3. Calculate totals
4. Apply discount (optional)
5. Choose payment method(s)
6. Complete sale

---

### 2.7 Customers

- id
- name
- phone
- created_from_pos (boolean)

---

### 2.8 Payment System

Dynamic payment methods:

payment_methods:

- id
- name
- type:
    - cash
    - installment

Invoice status:

- paid
- unpaid
- partial

---

### 2.9 Installments (Important)

If not fully paid:
→ create vouchers

vouchers:

- id
- invoice_id
- amount
- due_date
- status (paid/unpaid)

---

### 2.10 Sales

sales_invoices:

- id
- branch_id
- customer_id (nullable)
- total
- paid
- remaining
- status
- created_by

sales_items:

- id
- invoice_id
- product_id
- variant_id
- quantity
- price

---

### 2.11 Purchases

purchase_invoices:

- id
- supplier_id
- branch_id
- total
- created_by

purchase_items:

- product_id
- quantity
- cost_price
- expiry_date

→ On save:
Create batches

---

### 2.12 Suppliers (Resellers)

- id
- name
- phone
- notes

---

### 2.13 Inventory Transfer

transfers:

- from_branch_id
- to_branch_id
- created_by

transfer_items:

- product_id
- quantity

Rules:

- Permission required
- Deduct from source batches (FIFO)
- Create new batches in destination

---

### 2.14 Inventory Count (Stock Taking)

manual only

stock_counts:

- branch_id
- created_by

stock_count_items:

- product_id
- actual_quantity
- system_quantity
- difference

If difference:
→ create accounting entry:

- loss OR gain

---

### 2.15 Accounting System (DOUBLE ENTRY)

#### Chart of Accounts

accounts:

- id
- name
- type:
    - asset
    - liability
    - equity
    - revenue
    - expense

- parent_id

---

#### Journal Entries

journal_entries:

- id
- date
- description

journal_entry_lines:

- id
- journal_entry_id
- account_id
- debit
- credit

---

### Auto Entries:

#### Sale:

- Debit: Cash / Receivable
- Credit: Sales Revenue

#### Purchase:

- Debit: Inventory
- Credit: Supplier

#### Inventory Loss:

- Debit: Loss
- Credit: Inventory

---

### Reports:

- Trial Balance
- Profit & Loss
- Daily sales

---

### 2.16 Reports

- Daily Sales
- Profit
- Inventory movement
- Expiry report

---

### 2.17 Audit Logs

Track EVERYTHING:

- create
- update
- delete

Use:

- activity_log table

---

### 2.18 Soft Deletes + Restore

All main tables:

- soft deletes

Recycle bin page:

- restore
- force delete

---

## 3. UI/UX

### Dashboard

- Simple modern design
- Cards:
    - sales today
    - profit
    - low stock

- Charts (Chart.js)

### Sidebar:

- Based on permissions

### POS:

- Fullscreen
- Back button

### Features:

- Dark mode
- Arabic RTL

---

## 4. Performance

- 200–300 invoices/day supported
- Use:
    - eager loading
    - indexes on:
        - product_id
        - branch_id
        - expiry_date

---

## 5. Livewire Structure

Example:

- Products/
    - Index.php
    - Form.php

- POS/
    - PosScreen.php

- Sales/

- Purchases/

- Inventory/

- Reports/

---

## 6. Traits Integration

Use existing traits:

- GeneralTrait
- JodaResource
- livewireResource
- ResourceHelpers

For:

- CRUD generation
- validation
- responses

---

## 7. Routes

- /login
- /dashboard
- /pos (fullscreen)

Modules:

- products
- purchases
- sales
- inventory
- accounting
- reports
- users

---

## 8. Important Rules

- No selling expired products
- Always FIFO
- Every financial action → journal entry
- All changes logged

---

## 9. Future Extensions

- Supplier portal
- Excel import
- Mobile app
- API

---

## 10. Claude Instructions

Build step-by-step:

1. Setup Laravel project
2. Install packages:
    - spatie/laravel-permission
    - spatie/laravel-activitylog

3. Build migrations
4. Build models & relationships
5. Build Livewire components
6. Implement POS
7. Implement accounting engine
8. Add reports
9. Optimize performance

Follow clean architecture and reusable components
and use any package you need .