# CLAUDE.md

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

## What this is

This is **not a single codebase** — it is the cPanel docroot / working host for the **Moon ERP** project on the `moonui3` account (`moonui3.elbaset.com`). Moon ERP is a bilingual (Arabic/English, RTL-first) healthcare + manufacturing + accounting ERP, with a strong **LIS (Laboratory Information System)** focus, distributed to self-hosted clients via **MoonStack** (a self-host updater/installer).

`moonui3` is a **parallel development environment** — the **third** Claude instance, running on its own branch, database, and deploy URL alongside `moonui` (Claude #1, branch `hazemdev`) and `moonui2` (Claude #2, branch `hazemdev2`). Both code repos on this account are on branch **`hazemdev3`**. See the [`parallel-dev`](knowledge-base/topics/parallel-dev.md) KB topic before doing anything that could collide with the other hosts — keep DB + URL/deploy + working dir separate per instance; **never touch another instance's database** (they are not binlogged — a wipe is unrecoverable), and agree the module split up front.

| | moonui (Claude #1) | moonui2 (Claude #2) | **moonui3 (this instance)** |
|---|---|---|---|
| URL | moonui.elbaset.com | moonui2.elbaset.com | **moonui3.elbaset.com** |
| Branch (BE + FE) | `hazemdev` | `hazemdev2` | **`hazemdev3`** |
| Database | `moonui_dev_be` | `moonui2_dev_be` | **`moonui3_dev_be`** |
| Home | `/home/moonui` | `/home/moonui2` | **`/home/moonui3`** |

## 🧠 Read the Knowledge Base FIRST

`knowledge-base/` is the **canonical home for all project context, decisions, and "why"** — read it before the code, not after.

1. Start at [`knowledge-base/INDEX.md`](knowledge-base/INDEX.md) → open the relevant topic in `knowledge-base/topics/` → then read the code/docs it links.
2. [`knowledge-base/README.md`](knowledge-base/README.md) explains how the KB works and how to add/update topics.
3. **Update rule (standing):** after any substantial work on a topic, update its `topics/<slug>.md` (`updated:` date + a line under `Decisions`/`Open`). **🔴 Before any `/clear` or `/compact`, update the topics you touched with current state + a resume point** — this is when context is most likely to be lost.

The code is the source of truth for *behavior*; the KB is the source of truth for *context and decisions*. HTML deep-dives/plans live in `knowledge-base/plans/` (served at `…/knowledge-base/plans/<name>.html`).

⚠️ **The KB does NOT sync between instances.** It is not inside the FE/BE repos and has no git remote, so it never travels with a clone or a `main` merge — and **an agent is hard-blocked from ever pushing it to GitHub** (it is internal proprietary docs). This copy was `cp -a`-ed + union-merged from `moonui` + `moonui2` on 2026-07-13. Syncing back is a manual, human-coordinated `rsync` between the homes. Details + the definitive ruling: [`parallel-dev`](knowledge-base/topics/parallel-dev.md).

## Repository map

| Path | What | Git remote | Has its own CLAUDE.md |
|---|---|---|---|
| `knowledge-base/` | Canonical project brain (topics + plans) | local git repo, **no remote — never push it** | — |
| `moon-erp/` | **Frontend** — Angular 21 SPA | `hazemhamdytaha/moon-erp-angular` | ✅ + per-module under `src/app/**/CLAUDE.md` |
| `moon-erp-be` → `/home/moonui3/moon-erp-be/public` | symlink to the **Backend** Laravel public dir | the BE repo: `tahadeveloper/moon-erp` | ✅ (at `/home/moonui3/moon-erp-be/CLAUDE.md`) + `AGENTS.md`, `.ai-instructions.md` |
| `app/` | the **built/deployed** Angular bundle served at `/app` | (build output — do not hand-edit) | — |

**The backend repo itself lives at `/home/moonui3/moon-erp-be`** (only its `public/` is symlinked into the docroot). Read that repo's `CLAUDE.md` (Laravel Boost guidelines, PHP conventions, module structure) and `.ai-instructions.md` (the production task workflow triggered by "start working on tasks") before backend work.

## Branch & release model

- **`hazemdev3`** = this account's work/integration branch on **both** repos (tracks `origin/hazemdev3`; `hazemdev`/`hazemdev2` belong to the other instances). Commit WIP here.
- **`main`** = the release source / stable line. **Work on the dev branch, release from `main`.** Merge early + often so conflicts with the other instances stay tiny.
- `git -C /home/moonui3/moon-erp-be …` and `git -C /home/moonui3/public_html/moon-erp …` — both remotes carry embedded tokens; **never print the remote URL with the token.**
- **Release-note gate:** both repos run a versioned `.githooks/pre-push` hook (`core.hooksPath=.githooks`) that requires a `[Unreleased]` bullet in the BE's `docs/moonstack/CHANGELOG.md` for any user-facing change. Legitimate bypass for internal/refactor commits: put `[skip-changelog]` in a commit message, or `SKIP_CHANGELOG=1 git push`. **Do not use `--no-verify`.**
- `/fullpush` (project command, `.claude/commands/fullpush.md`) runs the sync-and-merge flow for both repos with this account's values.
- Distribution is handled by MoonStack (`php artisan moonstack:ship`). The full release pipeline, env vars, and the hard-won composer/CageFS/SAPI gotchas are in the [`dev-workflow`](knowledge-base/topics/dev-workflow.md) and [`moonstack-update`](knowledge-base/topics/moonstack-update.md) KB topics — **read them before cutting a release.**

## Commands

### Frontend (`moon-erp/`, Angular 21 — no test runner; `skipTests: true`)
```bash
cd /home/moonui3/public_html/moon-erp
npx ng serve                              # dev server at http://localhost:4200
npx ng build --base-href /app/            # production build → dist/moon-erp/browser/

# Deploy to /app (clean stale chunks first — they accumulate):
rm -f /home/moonui3/public_html/app/*.js /home/moonui3/public_html/app/*.css /home/moonui3/public_html/app/*.html /home/moonui3/public_html/app/*.ico
\cp -rf /home/moonui3/public_html/moon-erp/dist/moon-erp/browser/* /home/moonui3/public_html/app/
chown -R moonui3:moonui3 /home/moonui3/public_html/app
```
**Deploy to `/app` after EVERY frontend change** — the owner tests on the live `/app` (`https://moonui3.elbaset.com/app/…`), so a committed-but-undeployed fix looks broken. Keep `app/assets/config.json` `apiUrl` pointed at **moonui3**'s backend (it is *runtime* config, not baked into the build).

### Backend (`/home/moonui3/moon-erp-be`, Laravel 12 / PHP 8.2, nwidart modules)
```bash
cd /home/moonui3/moon-erp-be
bash local-deploy.sh                      # ALWAYS run after BE edits: dump-autoload + optimize:clear + migrate
php composer.phar test   # or: php artisan test   (Pest 3 / PHPUnit 11)
php artisan test --filter=<TestName>      # single test
./vendor/bin/pint                         # format (Laravel Pint)
php artisan scribe:generate               # regenerate API docs
```
⛔ **NEVER** run `migrate:fresh` / `migrate:refresh` / `db:wipe` on `moonui3_dev_be` — it is not binlogged; a wipe is unrecoverable.

Modules (nwidart) live under `Modules/`: Accounting, CMMS, Core, CRM, EInvoicing, HRM, Inventory, LIS, NPHIES, POS, Production, Purchases, QMS, Sales, WebStore.

## Architecture (big picture)

- **Frontend → Backend** over a REST API. The FE is Angular 21 standalone components + **NgRx** (`@ngrx/entity` per feature) + PrimeNG v21. Every CRUD feature flows **Component → Action → Effect → Service → API → Reducer → Selector → Component**. Auth uses a non-standard **`X-Authorization: Bearer <token>`** header and a `listAll()` auto-paginator (the API caps pages at 25). These and other API quirks are documented in `moon-erp/CLAUDE.md` — **do not re-derive them.** (Note: the Production/factory feature deliberately uses services + signals, **no NgRx**.)
- **Backend** is modular Laravel (nwidart), Sanctum auth, Spatie permissions/activitylog/query-builder, DomPDF. Per-module conventions and the Laravel Boost workflow are in the BE `CLAUDE.md`.
- **MoonStack** packages the BE + built FE into a signed updater zip and a docroot-ready installer zip, published to a `versions.json` manifest that self-hosted clients poll. Lives in `app/MoonStack/` of the BE repo.
- **LIS analyzer middleware** (on-prem Python, in the BE repo's `lis-middleware/`) bridges lab analyzers (Maglumi/VITROS/Dymind/Udichem) over ASTM/HL7 to the ERP. See the `middleware` and `client-pc-tunnel` KB topics.

## Working rules (standing, owner-set)

- **Fix in the shared layer, not screen-by-screen.** If an issue hits 3+ documents (quotation/order/invoice/return, purchase bill/order…), fix it ONCE in the shared trait/service/component they all use (BE: `Modules/Core/app/Support/*`, `Services/*`, base API Resources; FE: `TransactionLineItemsComponent`, shared directives/services/models) — never patch one screen at a time.
- **Diagnose before fixing.** Reproduce by reading the exact code path (FE component + service → BE endpoint/validation → data), name the true root cause, *then* make the minimal correct fix. Correctness over speed.
- **Use Fable 5 for design/UX ("الشكل").** Dispatch a Fable agent (`model: "fable"`) for any screen/dialog/flow with a visual or UX surface, rather than designing solo.

## Host & deployment gotchas (cPanel, this account)

- **Existing FE/BE docs and KB pages hard-code `/home/moonui/…` or `/home/moonui2/…`; on this account paths are `/home/moonui3/…`.** Translate accordingly.
- **`chown` after editing as root:** files this session edits as root become root-owned → suexec 500s and `moonstack:ship` silently fails to write `docs/moonstack/CHANGELOG.md`. Run `chown moonui3:moonui3 <file>` after editing BE/page files as root, then `bash local-deploy.sh`.
- PHP is **`ea-php82`** (`AddHandler application/x-httpd-ea-php82 .php`). Composer must run under a **CLI** SAPI php — invoke as `php composer.phar …`, never the bare phar (FPM SAPI aborts). See `dev-workflow` for the full composer/CageFS analysis.
- Use `\cp -rf` to bypass the `cp` alias prompt on this host. `mod_proxy` is not available in `.htaccess` here.