# Phase 1 — Project Structure Analysis

> **Deliverable:** analysis of the Habib Cables ERP codebase and a high-level architecture proposal
> for the `CLAUDE.md` documentation system. Everything in later phases is derived from this.
> **Index:** [../README.md](../README.md) · **Live entry point:** [../../../CLAUDE.md](../../../CLAUDE.md)

## 1. What this project actually is
A **Laravel 12 (PHP 8.2) modular monolith** that is also the hub of a small distributed ecosystem:
- **Web ERP** — server-rendered Blade + Alpine.js UI and controllers.
- **Windows desktop client** — a separate, offline-first app that syncs via `api/desktop/*`.
- **Shop POS** — retail point-of-sale backed by the `Shop*` models and a `v1` API.

Everything is one repository, so the "components" are **logical boundaries**, not separate repos.

## 2. Technology stack (observed)
- **Backend:** Laravel 12, PHP 8.2. Auth via Breeze (web) + Sanctum (API/desktop).
- **Key packages:** `spatie/laravel-permission` (RBAC), `spatie/laravel-activitylog` (audit),
  `yajra/laravel-datatables` (grids), `barryvdh/laravel-dompdf` (PDF).
- **Frontend:** Blade, Alpine.js 3, Tailwind 3, Vite 7, axios.
- **Data/infra:** MySQL (SQLite for quick local); `SESSION`, `QUEUE`, `CACHE` all default to the
  **database** driver → a queue worker is required for jobs. Laragon (Windows) local; Docker documented.
- **Testing/tooling:** Pest 3, Laravel Dusk, Pint (format), Pail (logs), Debugbar.

## 3. Component boundaries identified
| Component | Code location | Responsibility |
|-----------|---------------|----------------|
| erp-web-core | `app/Http/Controllers/` (root), `app/Models`, `app/Http/Requests` | Inventory, Purchasing (PR→PO→GRN→QC→Gatepass), Manufacturing, WMS, QC |
| accounting-ledger | root controllers + `app/Events`/`app/Listeners` | Chart of accounts, cost centers, dual-ledger, weighted-average costing |
| shop-pos-api | `app/Http/Controllers/Api/` + root `Shop*` controllers | Retail POS, shop dashboard, payments, `v1` REST |
| desktop-sync-api | `app/Http/Controllers/Api/Desktop/` | License + offline pull/push sync |

## 4. Common patterns across the codebase
- **Thin controller → FormRequest → model/`DB::transaction()` → event → activitylog → view.**
- **Status state machines** via the shared `App\Traits\HasStatusManagement` trait (status constants +
  `getEditableStatuses()`/`getCancellableStatuses()` overrides). Reference: `app/Models/Grn.php`.
- **FormRequest validation** in `app/Http/Requests/<Domain>/`, with cross-field business rules in
  `withValidator()` (e.g. received qty ≤ remaining PO qty in `StoreGrnRequest`).
- **Yajra server-side DataTables** for every index grid.
- **Activity logging** on mutating models via `getActivitylogOptions()`
  (`logFillable()->logOnlyDirty()->dontSubmitEmptyLogs()`).
- **RBAC everywhere** via middleware aliases `check.role` / `check.active.user` (`bootstrap/app.php`)
  and Spatie abilities.
- **Event-driven side effects:** `GRNPosted` / `IGPProcessed` → `ProcessGRNPosted` / `ProcessIGP`.

## 5. Integration points (cross-cutting)
1. **ERP → accounting:** GRN/IGP events post balanced double-entry transactions.
2. **Desktop sync:** `api/desktop/*` pull/push with a mark-synced handshake; CSRF-exempt; Sanctum +
   license gated; offline/idempotent.
3. **Shop POS ↔ shared inventory/ledger:** shop stock (`ShopProductStock`) is distinct from central
   inventory (`WarehouseCurrentStock`/`StockBalance`); payments post to the accounting ledger.
4. **Shared domain models** are the true contract: `Item`, `ItemVariation`, `StockLedger`,
   `ChartOfAccount`, `Warehouse`, `Shop*`.

## 6. Technical-debt hotspots (flagged for the rules)
The tree contains **non-routed legacy duplicates** that must never be edited-by-accident or extended:
`*Controller copy.php`, `* copy 2.php`, `*_backup.php`, `Models/*copy.php`,
`app/Http/Controllers/Api/Backup/`, `extra/GatepassController1.php`. The `MASTER_RULES` file encodes
"verify the live file via `php artisan route:list`; never add new copy/backup files."

## 7. Architecture proposal (what later phases built)
- **Phase 2** — a component doc per boundary, placed by folder.
- **Phase 3** — five shared `MASTER_*` files (principles, rules, commands, integration, tools).
- **Phase 4** — a root `CLAUDE.md` orchestrator that routes tasks to the right component + shared rules.
- **Phase 5** — validation of consistency/completeness/usability.
- **Phase 6** — an implementation & maintenance guide.

> Note: on the user's request the whole system was later reorganized **by phase** under
> `docs/phases/` (this folder). The root `CLAUDE.md` remains at the repo root so Claude Code can
> auto-load it.