diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..622835b27
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,104 @@
+# 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
+
+```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` 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
\ No newline at end of file