opensourcepos/AGENTS.md

# Agent Instructions

This document is the single source of truth for all AI agents working on the Open Source Point of Sale (OSPOS) codebase. Read it fully before making any changes.

## Project Overview

OpenSourcePOS is a web-based Point of Sale system built on **CodeIgniter 4** (PHP 8.2+) with MySQL/MariaDB. Frontend uses Bootstrap 3 (Bootstrap 5 migration in progress) and jQuery, with assets built via Gulp.

## Common Commands

```bash
# PHP dependencies
composer install

# Frontend dependencies and asset build
npm install
npm run build          # Runs Gulp: compiles and copies all CSS/JS to public/resources/

# Run full test suite
composer test

# Run a single test file
vendor/bin/phpunit tests/unit/AppTest.php

# Lint / code style check
vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.no-header.php --dry-run

# Apply code style fixes
vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.no-header.php
```

Tests require a MariaDB/MySQL database (see CI config in `.github/workflows/phpunit.yml`).

## Architecture

### Framework & Entry Point

- **Framework**: CodeIgniter 4 — MVC with QueryBuilder ORM, no Eloquent
- **Web root**: `public/` — `public/index.php` is the only entry point
- **Routes**: `app/Config/Routes.php`
- **App config**: `app/Config/App.php` (version, session, security settings)
- **Environment**: `.env` file (copy from `.env.example`); `CI_ENVIRONMENT` controls dev/prod/test mode

### Directory Layout

```text
app/
├── Config/         # CI4 config classes
├── Controllers/    # ~27 controllers (Sales, Items, Reports, Customers, etc.)
├── Models/         # ~28 models (Sale, Item, Customer, Supplier, etc.)
├── Views/          # PHP view templates
├── Libraries/      # Business logic (Sale_lib, Tax_lib, Receiving_lib, etc.)
├── Plugins/        # Plugin system — each plugin is a subdirectory here
├── Database/       # Migrations (ospos_ prefix) and seeds
├── Language/       # i18n files (IETF BCP 47 locale names)
├── Filters/        # Request/response filters (auth, HTTPS, etc.)
└── Events/         # CI4 event subscribers
public/
└── resources/      # Built CSS/JS (do not edit directly — generated by npm run build)
tests/              # PHPUnit test suite
```

### Key Libraries

`app/Libraries/` holds core business logic:
- `Sale_lib.php` — sale cart state, pricing, discounts, tax calculation
- `Tax_lib.php` — multi-tier tax engine
- `Receiving_lib.php` — purchase orders / receivings
- `Barcode_lib.php` — barcode generation
- `Email_lib.php` — email delivery
- `Token_lib.php` — CSRF/session token management

### Database

- Table prefix: `ospos_` (defined in `app/Config/Database.php`)
- Migrations live in `app/Database/Migrations/` and run automatically on first access
- CodeIgniter QueryBuilder throughout — no raw SQL unless necessary

### Plugin System

Plugins live in `app/Plugins/<PluginName>/` and are auto-discovered by `PluginManager`. Each plugin:
- Extends `BasePlugin` or implements `PluginInterface`
- Registers event hooks (e.g., `item_sale`, `customer_saved`, view hooks like `customer_tabs`)
- Can include its own `Views/`, `Models/`, `Controllers/`, and `Language/` subdirectories
- Configuration stored in `ospos_plugin_config` table
- See `app/Plugins/README.md` for plugin structure, event hooks, and LICENSE requirements

### Frontend Build

`gulpfile.js` (Gulp 5) copies vendor CSS/JS from `node_modules/` into `public/resources/`. Run `npm run build` after installing npm packages or changing gulp tasks. Do not manually edit files under `public/resources/`.

## Code Style

- **PSR-12** enforced via PHP-CS-Fixer (config: `.php-cs-fixer.no-header.php`)
- `camelCase` for variables and methods; `PascalCase` for classes; `UPPER_CASE` for constants
- PHP 8.2+ features acceptable (named arguments, enums, readonly properties)
- Views in `app/Views/errors/html/` are excluded from the fixer
- Run fixer before committing: `vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.no-header.php`

## Development Workflow

- Create a new git worktree for each issue, based on the latest state of `origin/master`
- Commit fixes to the worktree and push to the remote
- Tests must pass before submitting changes (`composer test`)
- Minimum PHPUnit version: 10.5.16+. Default config: `phpunit.xml.dist`

## Conventions

- Controllers → `app/Controllers/`
- Models → `app/Models/`
- Views → `app/Views/`
- Migrations → `app/Database/Migrations/`
- Plugins → `app/Plugins/` (see `app/Plugins/README.md` for plugin structure, event hooks, and LICENSE requirements)
- Use CodeIgniter 4 framework patterns and helpers
- Sanitize user input; escape output using `esc()` helper

## Security

- `app.allowedHostnames` **must** be set in production (host header injection protection)
- HTMLPurifier for HTML sanitization; Laminas Escaper for output escaping
- CSRF tokens managed via `Token_lib` — do not bypass CI4's CSRF filter
- Session storage is database-backed (`ospos_sessions` table) for multi-instance support
- Never commit secrets, credentials, or `.env` files
- Use parameterized queries to prevent SQL injection
- Validate and sanitize all user input