opensourcepos/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

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

Common Commands

# 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 for the environment expected).

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

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

The app/Libraries/ directory holds the core business logic that controllers delegate to:

• 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 is used 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 is stored in the ospos_plugin_config table
• See app/Plugins/README.md and AGENTS.md for full plugin development docs

Frontend Build

gulpfile.js (Gulp 5) copies vendor CSS/JS from node_modules/ into public/resources/. Running npm run build is required 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
• Views in app/Views/errors/html/ are excluded from the fixer
• PHP 8.2+ features are acceptable (named arguments, enums, readonly properties)

Security Notes

• app.allowedHostnames must be set in production (host header injection protection)
• HTMLPurifier is used for HTML sanitization; Laminas Escaper for output escaping
• CSRF tokens are managed via Token_lib; do not bypass CI4's CSRF filter
• Session storage is database-backed (ospos_sessions table) for multi-instance support