# MASTER_PRINCIPLES.md — Habib Cables ERP

Core development philosophy shared by every component. Referenced by all `CLAUDE.md` files.

## 1. Development philosophy
- **Convention over configuration.** This is idiomatic Laravel 12 — follow framework conventions
  before inventing patterns. If Laravel has a way (FormRequest, Resource, Event, Policy), use it.
- **DRY, but not prematurely.** Extract shared logic into `app/Helpers`, model methods, or events
  once it is used in 2+ places — not before.
- **KISS.** A readable controller action beats a clever abstraction. This team is small.
- **SOLID where it pays.** Fat models / thin controllers; single-responsibility FormRequests;
  event listeners for side effects (ledger posting) rather than inline controller code.

## 2. Decision-making framework
When choosing an approach, prefer in this order:
1. The pattern already used elsewhere in this repo (consistency wins).
2. The stock Laravel 12 mechanism.
3. A well-maintained package already in `composer.json` (Spatie, Yajra, dompdf).
4. Only then, a new custom abstraction — and document it in the relevant `CLAUDE.md`.

## 3. Quality standards
- Code passes `./vendor/bin/pint` (PSR-12) with no diff.
- Every mutation path is validated (FormRequest) and audited (activitylog).
- Every DB schema change ships as a reversible migration.
- New behaviour ships with at least one Pest feature test.

## 4. Error-handling philosophy
- Validate at the edge with FormRequests; never trust request input in the action body.
- Wrap multi-table writes (stock + ledger, GRN + inventory) in `DB::transaction()`.
- Return structured JSON errors for API/desktop/POS routes; redirect-with-errors for web routes
  (mirror the pattern in `CheckRole` middleware).
- Fail loudly in logs (`Log::error` / `pail`), gracefully in the UI.

## 5. Testing philosophy
- Feature tests over unit tests for this domain — the value is in the workflows
  (PR→PO→GRN→QC, sync round-trips, ledger balance).
- The custom `Test*` artisan commands (`TestChartOfAccountsIntegration`, `TestDualLedgerIntegration`,
  `TestQcImplementation`, `TestRolesPermissions`, …) are living integration checks — keep them working.
- Dusk covers critical browser flows.

## 6. Performance principles
- No N+1: eager-load relationships (`with()`) on index/report queries.
- DataTables endpoints must use Yajra **server-side** processing, never load-all-then-filter.
- Push slow work (PDF batches, sync reconciliation, notifications) onto the queue.
- Stock-ledger reads should hit the maintained balance tables, not recompute from movements.

## 7. Data integrity is sacred
This is an ERP — money and stock must reconcile.
- Stock movements, `StockLedger`, and `WarehouseCurrentStock`/`StockBalance` must stay consistent.
- Accounting must stay **double-entry balanced**; the dual-ledger integration is the source of truth.
- Never "fix" a balance by editing a row — post a correcting transaction.

## 8. Collaboration & ethics
- Small team, feature-branch → PR into `main`. Keep PRs reviewable.
- Leave the tree cleaner than you found it — but delete legacy `copy`/`backup` files in a dedicated
  commit, never silently mixed into a feature.
- Never commit secrets; `.env` stays local.