# Project Context

## Purpose

TinyPOS (`tnx-pos`) is a single-store Point-of-Sale and back-office management system. It covers the complete retail loop for a single in-store operator: product catalogue, barcode-driven sales, customer relationship management (pricing tiers, reward points, gift redemption, debt tracking), order management with receipt printing, and daily sales statistics rollup. There are no external payment gateway or third-party API integrations — all business logic runs inside the application against its own database.

## Tech Stack

| Layer | Technology | Version |
|---|---|---|
| Language | PHP | 7.4.33 |
| Web framework | Laravel | 5.6.39 (`5.6.*`) |
| Admin shell / auth | salipropham/laravel55-admin | 0.1.x |
| ORM | Eloquent (Laravel built-in) | — |
| Database | MariaDB | 10.11.13 |
| HTML forms | laravelcollective/html | 5.6.x |
| Image processing | intervention/image | ^2.7 |
| Templating | Blade | Laravel built-in |
| Frontend assets | JavaScript / Vue / SCSS | minimal (≈4 JS/Vue files, 2 SCSS files) |
| Testing | PHPUnit | ^7.0 |
| Web server | Apache / mod_php (www-data) | — |
| Containerisation | Docker (Dockerfile + docker-compose) | — |
| CI/CD | GitLab CI | single `pos-dev` deploy job |
| Scheduler | OS cron → `php artisan schedule:run` | every minute, Asia/Ho_Chi_Minh timezone |

## Architecture & Conventions

**Monolith, Laravel standard layering.** There are no domain folders; the application uses Laravel's conventional technical directories (`Controllers`, `Models`, `Middleware`, `Providers`).

**Single user role.** Authentication is provided entirely by the `salipropham/laravel55-admin` package. There is one role — `Administrator` (store cashier / owner). Customers are never authenticated; they exist only as CRM records (`customers` table).

**Route organisation.** All application routes live under the admin middleware group defined by `config('admin.route.*')`. Resources are registered with `$router->resource(...)`. Barcode-scan actions are explicit `GET` routes added before each resource block (`/pos/scan`, `/orders/scan`, `/customers/scan`, `/gifts/scan`). Settings sub-resources (`brand`, `categories`, `units`, `gifts`) are nested under a `settings/` prefix group. The root `/` redirects (301) to `/pos`.

**Domain modules (inferred from controllers + models):**

| Module | Key routes |
|---|---|
| `pos` | `resource /pos`, `GET /pos/scan` |
| `products` | `resource /products`, `GET /products/get-price` |
| `customers` | `resource /customers`, scan, orders, gift check, debt, points redemption |
| `orders` | `resource /orders`, scan, print, note |
| `debts` | `GET /debts` |
| `gifts` | `resource settings/gifts`, `GET settings/gifts/scan` |
| `brand` / `categories` / `units` | `resource settings/*` |
| `dashboard` | `resource /dashboard` |

**Background scheduling.** `App\Console\Kernel` registers a daily closure that calls `Order::summaryLogging()`, which rolls up per-customer order statistics. A dedicated Artisan command (`CustomerOrderSummaryLogging`) also exists for manual triggering.

**Database migrations** (27 total) span 2016–2026. Recent additions (2022–2026) cover reward points, wholesale pricing, gifts with a customer-gift pivot, customer order summary, a settings table, product units, and customer debts.

**Deployment.** GitLab CI runs a single `pos-dev` job that redeploys the app and reinstalls the cron file (`deploy/cron.d/tnx-pos-dev`). Docker images use Apache/mod_php.

**Test coverage is minimal.** One feature test file exists (`tests/Feature/OrderControllerTest.php`); there is no broad automated test suite.

**No external integrations.** Payments, tax, e-invoicing, and loyalty are all handled internally. Any future third-party integration would be greenfield.