# 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 `moonui2` account (`moonui2.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).

`moonui2` is a **parallel development environment** (a second Claude instance runs here on its own branch, DB, and deploy URL). Both code repos on this account are on branch **`hazemdev2`**. See the `parallel-dev` KB topic before doing anything that could collide with the primary `moonui` host — keep DB + URL/deploy + working dir separate per instance; never share a database that isn't binlogged.

## 🧠 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`).

## Repository map

| Path | What | Git remote | Has its own CLAUDE.md |
|---|---|---|---|
| `knowledge-base/` | Canonical project brain (topics + plans) | not a git repo | — |
| `moon-erp/` | **Frontend** — Angular 21 SPA | `hazemhamdytaha/moon-erp-angular` | ✅ + per-module under `src/app/**/CLAUDE.md` |
| `moon-erp-be` → `/home/moonui2/moon-erp-be/public` | symlink to the **Backend** Laravel public dir | the BE repo: `tahadeveloper/moon-erp` | ✅ (41 KB, at `/home/moonui2/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/moonui2/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

- **`hazemdev` / `hazemdev2`** = work/integration branches (this account is on `hazemdev2`). Commit WIP here.
- **`main`** = the release source / stable line. **Work on the dev branch, release from `main`.**
- `git -C /home/moonui2/moon-erp-be …` and `git -C /home/moonui2/public_html/moon-erp …` — both remotes carry embedded tokens; **never print the remote URL with the token.**
- 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/moonui2/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/moonui2/public_html/app/*.js /home/moonui2/public_html/app/*.css /home/moonui2/public_html/app/*.html /home/moonui2/public_html/app/*.ico
\cp -rf /home/moonui2/public_html/moon-erp/dist/moon-erp/browser/* /home/moonui2/public_html/app/
```

### Backend (`/home/moonui2/moon-erp-be`, Laravel 12 / PHP 8.2, nwidart modules)
```bash
cd /home/moonui2/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
```
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.**
- **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.

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

- **Existing FE/BE docs hard-code `/home/moonui/…`; on this account paths are `/home/moonui2/…`.** 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 moonui2:moonui2 <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.