# Master CLAUDE.md — Habib Cables ERP

> Entry point for AI assistants and developers. **Always read this file first**, then load the
> component file for the area you are working in, then apply the shared rules in `docs/`.

## Project Overview

Habib Cables ERP is a **modular Laravel 12 monolith** that also acts as the hub of a small
distributed ecosystem:

- **Web ERP** — server-rendered Blade + Alpine.js UI covering Inventory, Purchasing,
  Manufacturing, Warehouse Management (WMS), Quality Control, and Accounting.
- **Desktop sync client** — an offline Windows app that authenticates, validates a license, and
  performs bidirectional pull/push sync against the `api/desktop/*` endpoints.
- **Shop POS** — retail point-of-sale (factory shop) backed by the `Shop*` models and API.

Everything lives in **one repository**, so the "components" below are **logical boundaries**. All
documentation lives in a single [docs/](docs/) folder — this root `CLAUDE.md` is the only doc file
outside it (Claude Code auto-loads it as the entry point).

## Documentation map (organized by build phase)

All documentation lives under `docs/phases/`, one folder per phase of the CLAUDE.md build-out.
This root `CLAUDE.md` is the only doc outside it (Claude Code auto-loads it as the entry point) and
is itself the **Phase 4** deliverable. Start at [docs/phases/README.md](docs/phases/README.md) for
the phase index.

```
CLAUDE.md                              ← you are here (Phase 4 master orchestrator, at repo root)
docs/phases/
├── README.md                          ← index of all phases
├── phase-1-analysis/
│   └── ANALYSIS.md                    ← project analysis & architecture proposal
├── phase-2-components/
│   ├── COMPONENT_ERP_WEB_CORE.md      ← web ERP + accounting-ledger module
│   ├── COMPONENT_SHOP_POS_API.md      ← shop POS + REST v1 layer
│   └── COMPONENT_DESKTOP_SYNC_API.md  ← offline desktop sync
├── phase-3-shared/
│   ├── MASTER_PRINCIPLES.md           ← development philosophy & quality bar
│   ├── MASTER_RULES.md                ← hard, actionable rules
│   ├── MASTER_COMMANDS.md             ← every command
│   ├── MASTER_INTEGRATION.md          ← how components talk (sync, POS, ledger)
│   └── MASTER_TOOLS.md                ← packages, helpers, tooling
├── phase-4-master/
│   └── ORCHESTRATOR.md                ← notes on this root CLAUDE.md (the live orchestrator)
├── phase-5-validation/
│   └── VALIDATION.md                  ← consistency/completeness/usability checks
└── phase-6-implementation/
    └── IMPLEMENTATION_GUIDE.md        ← placement, adoption, maintenance
```

## Component Directory

| Component | Purpose | Tech | Doc |
|-----------|---------|------|-----|
| **erp-web-core** | Inventory, Purchasing (PR→PO→GRN→QC→Gatepass), Manufacturing, WMS, and the Accounting/Ledger module | Laravel 12, Blade, Alpine, Yajra DataTables, dompdf | [docs/COMPONENT_ERP_WEB_CORE.md](docs/phases/phase-2-components/COMPONENT_ERP_WEB_CORE.md) |
| **desktop-sync-api** | License validation + offline bidirectional sync with the Windows desktop client | Sanctum tokens, JSON pull/push | [docs/COMPONENT_DESKTOP_SYNC_API.md](docs/phases/phase-2-components/COMPONENT_DESKTOP_SYNC_API.md) |
| **shop-pos-api & REST API** | Retail POS, shop dashboard, payments, and the general v1 REST surface | Laravel API, Sanctum, `web` session API | [docs/COMPONENT_SHOP_POS_API.md](docs/phases/phase-2-components/COMPONENT_SHOP_POS_API.md) |
| **accounting-ledger** | Chart of accounts hierarchy, cost centers, dual-ledger posting, weighted-average costing | Eloquent, Events/Listeners | Module inside [docs/COMPONENT_ERP_WEB_CORE.md](docs/phases/phase-2-components/COMPONENT_ERP_WEB_CORE.md#accounting-ledger-module) |

> **Why accounting has no folder of its own:** its controllers (`ChartOfAccountController`,
> `AccountController`, `CostCenterController`, `ManualTransactionController`) live in the root
> `app/Http/Controllers/` and its behaviour is event-driven, so it is a cross-cutting module rather
> than a foldered boundary. Treat it as first-class regardless.

## Shared Resources

Read these for any non-trivial task. They are the single source of truth for cross-component rules.

- [@docs/MASTER_PRINCIPLES.md](docs/phases/phase-3-shared/MASTER_PRINCIPLES.md) — development philosophy & quality bar
- [@docs/MASTER_RULES.md](docs/phases/phase-3-shared/MASTER_RULES.md) — hard, actionable rules (read before edit)
- [@docs/MASTER_COMMANDS.md](docs/phases/phase-3-shared/MASTER_COMMANDS.md) — every command you'll need
- [@docs/MASTER_INTEGRATION.md](docs/phases/phase-3-shared/MASTER_INTEGRATION.md) — how components talk (sync, POS, ledger events)
- [@docs/MASTER_TOOLS.md](docs/phases/phase-3-shared/MASTER_TOOLS.md) — packages, helpers, and dev tooling

## Context-Based Routing

| If the task is about… | Go to |
|-----------------------|-------|
| Blade views, controllers, modules, DataTables, PDFs | [docs/COMPONENT_ERP_WEB_CORE.md](docs/phases/phase-2-components/COMPONENT_ERP_WEB_CORE.md) |
| Desktop client login, license, pull/push sync, attachments | [docs/COMPONENT_DESKTOP_SYNC_API.md](docs/phases/phase-2-components/COMPONENT_DESKTOP_SYNC_API.md) |
| Shop POS, shop dashboard, payments, `v1` REST endpoints | [docs/COMPONENT_SHOP_POS_API.md](docs/phases/phase-2-components/COMPONENT_SHOP_POS_API.md) |
| Chart of accounts, transactions, cost centers, costing | [docs/COMPONENT_ERP_WEB_CORE.md](docs/phases/phase-2-components/COMPONENT_ERP_WEB_CORE.md#accounting-ledger-module) |
| A change that spans two or more of the above | [docs/MASTER_INTEGRATION.md](docs/phases/phase-3-shared/MASTER_INTEGRATION.md) |

## Development Workflows

### Starting development
1. Read this file → identify the component → open that component's `CLAUDE.md`.
2. Apply [@docs/MASTER_RULES.md](docs/phases/phase-3-shared/MASTER_RULES.md) and [@docs/MASTER_PRINCIPLES.md](docs/phases/phase-3-shared/MASTER_PRINCIPLES.md).
3. Follow the component's conventions and examples.

### New module development (the canonical path)
`migration → model → FormRequest(s) → controller → routes → Blade view → permission/role → activity log → test`
See the worked example in [docs/COMPONENT_ERP_WEB_CORE.md](docs/phases/phase-2-components/COMPONENT_ERP_WEB_CORE.md#9-common-workflow--add-a-module-canonical-path).

### Cross-component changes
1. Read [@docs/MASTER_INTEGRATION.md](docs/phases/phase-3-shared/MASTER_INTEGRATION.md).
2. Identify every component that touches the shared model (Item, ItemVariation, StockLedger, ChartOfAccount, Shop*).
3. Update the contract on both sides (e.g. a new sync field must be added to the Push/Pull payload AND the desktop expectations).
4. Test the integration point (sync round-trip, POS→ledger post).

### Bug investigation
Start from the symptom's component, then trace across boundaries via the event/sync contracts in
[@docs/MASTER_INTEGRATION.md](docs/phases/phase-3-shared/MASTER_INTEGRATION.md). Check `spatie/activitylog` and the
`storage/logs` (via `php artisan pail`) for the audit trail.

## Quality Gates (all components)

- ✅ `./vendor/bin/pint` clean (PSR-12).
- ✅ `php artisan test` (Pest) green.
- ✅ Every route is permission/role gated (`check.role`, `check.active.user`, or `auth:sanctum`).
- ✅ Every data mutation is validated by a FormRequest and audited by activitylog.
- ✅ Every migration is reversible (`down()` implemented) and does one thing.
- ❌ No `*Controller copy.php`, `*_backup.php`, or `Backup/` files committed. Use git.

## Emergency Protocols

- **Production incident:** disable the affected route group, check `pail`/activitylog, roll back the
  last migration only if reversible, coordinate desktop clients (they queue offline and re-sync).
- **Rollback:** `php artisan migrate:rollback --step=1`; redeploy previous tag; rebuild assets.
- **Sync corruption:** pause `api/desktop/*`, reconcile via `pullServerChanges` / `markSynced`.

## Meta-Instructions for Claude

- Always start here for context, then load the component `CLAUDE.md`.
- Apply `docs/MASTER_*` rules consistently; they override component defaults only where a component
  explicitly documents an override.
- For cross-repo/cross-component work, consult `MASTER_INTEGRATION.md` before editing either side.
- When something is ambiguous, ask a specific question rather than guessing schema or contracts.
- Ground every claim in the actual code — this is a large codebase with legacy `copy`/`backup`
  files; verify a file is the live one before editing it.