# CLAUDE.md — ERP

This file is read automatically by Claude Code at the start of every
session in this project. It exists so Claude never has to guess at
conventions, architecture, or the things it must not touch. It is the
authoritative engineering instruction set for this repository — when it
conflicts with a stale assumption elsewhere, this file (kept current) and
the actual code win.

## 1. Project identity

This is a custom-built PHP school ERP designed as a **multi-school /
multi-tenant platform**, not a single-school product. The architecture
(`erp/schools/<CODE>/` for tenant-specific code, `erp/modules/` for
shared code) already supports multiple tenants running on one codebase
and one deployment.

**Do not describe this project as being "for" one named school**, in
documentation, comments, or generated output. A school may exist as a
**configured production tenant** — that is configuration data, not the
identity of the product. Where an example needs a school, use neutral
language: "a tenant", "the current production tenant", "School A",
"an example school".

There is one developer/maintainer on this project. There is no team to
catch a mistake before it reaches production — be conservative, and
prefer asking or flagging over guessing on anything risky or ambiguous.

## 2. Multi-tenant architecture

```
erp/
├── modules/            # shared PHP helpers — used by EVERY tenant, must stay tenant-agnostic
└── schools/
    └── <SCHOOL_CODE>/  # one folder per tenant
        ├── config.php    # this tenant's DB connection + school_info/branding
        ├── admin/        # desktop admin panel
        ├── app/          # mobile app-shell portals
        ├── payment_gateway/
        └── automated/    # cron/, webhook/, api/, google_sync/
```

- Shared logic (auth helpers, `sql()`/`config()`/`get_storage_path()`,
  payment/payout abstractions, etc.) lives in `erp/modules/` and must
  never hardcode a school-specific value — a prior audit found and fixed
  exactly this (`security: stop hardcoding SHPS identity in shared,
  tenant-agnostic modules`). Treat that as a pattern to watch for, not a
  closed issue.
- Tenant-specific values (name, logo, address, affiliation number, social
  links) come from `$school_info`, built from `config('school', ...)` /
  `config('branding', ...)` in `erp/schools/<CODE>/config.php` — never
  hardcode a tenant's name/branding into shared code or into a new
  module.
- Only one tenant folder exists in this repository today. That does not
  make single-tenant assumptions safe to bake into new shared code.

## 3. Technology philosophy

**PHP is the core backend/application language of this project** — most
business logic, routing, and rendering is plain PHP with no external MVC
framework (a few libraries like PHPMailer and TCPDF are vendored
directly under `erp/assets/`, not pulled in via Composer).

That does not mean every future task must be solved in PHP. Choose
technology pragmatically:

- Backend/business logic → PHP, following existing patterns.
- Database/schema → SQL, through the project's parameterized helpers.
- Browser interaction → vanilla JavaScript (see `erp/assets/app/portal.js`)
  — no framework has been introduced, and none should be without cause.
- CI → GitHub Actions (YAML).
- Load testing → k6 (`docs/load-testing/`).
- Utility/one-off scripts → whichever language is safest and simplest for
  the job (Bash, Python, PowerShell on this Windows dev environment —
  see the platform note in the harness's own system context — are all
  fine for a scratch/investigation script that never ships as part of the
  application).

Rules of thumb:

- Do not introduce a new language or framework "because it's better" —
  justify it from the actual problem.
- Do not force a PHP-only solution onto something PHP is a poor fit for.
- Prefer the simplest technology that fits the task and the existing
  architecture over a fashionable alternative.
- Inspect how a similar problem was already solved in this codebase
  before introducing a new pattern.

## 4. Repository structure

```
erp/
├── config.php          # the ONE config entry point, zero secrets — loads config.local.php
├── config.local.php    # real DB credentials + encryption key — gitignored, never committed
├── storage/            # production storage — gitignored except its own .htaccess
├── assets/
│   ├── PHPMailer/         # vendored (not Composer)
│   ├── tcpdf/              # vendored (not Composer)
│   ├── fonts/              # vendored fonts (see THIRD_PARTY_NOTICES.md)
│   └── app/                # shared mobile-portal design system (portal.css/js)
├── modules/               # shared PHP helpers, auto-loaded by base.php (scandir, alphabetical)
├── schools/<CODE>/        # per-tenant application code
└── url_shortner/          # standalone internal tool, own database (shpsramp_url)

docs/                      # see the doc index in README.md
```

Production keeps two things inside `erp/` that are **never in this
repository**: `erp/config.local.php` (DB credentials + encryption key)
and `erp/storage/` (uploads/generated files). Both are gitignored, so no
deploy can create or overwrite them; `erp/storage/.htaccess` is the one
deliberate exception so the storage tree's hardening ships with the code.
See section 8 and `docs/storage.md`.

## 5. Backend conventions

- Database access goes through the project's own parameterized helpers —
  `sql()`, `sql_fetch()`, `sql_fetch_all()`. **Never build raw
  string-concatenated SQL.** (The one standalone exception,
  `erp/url_shortner/`, has its own separate database and used raw mysqli
  historically — it was migrated to parameterized `mysqli_prepare()`
  calls directly, not the shared `sql()` helpers, since those are wired
  to a different connection global. New code there should follow that
  same parameterized pattern.)
- `erp/modules/base.php` auto-loads every file in `erp/modules/` via
  `scandir()` in alphabetical order — a module that runs a query or
  depends on another module at *load time* (not inside a function) can
  break depending on filename ordering. Prefer defining logic inside
  functions, called later, over top-level executable code in a module
  file.
- **Current time always comes from `base.php`'s canonical values — never
  from a fresh `date()` call.** `base.php` captures the request's time
  once, under `Asia/Kolkata`, and exposes it as:
  - `$time`  — `d-m-Y h:i:s A` (exactly 22 characters). **This is the
    ERP's standard timestamp format and the default choice.** Use it for
    user-facing display *and* for application-managed timestamps stored
    in `varchar` columns.
  - `$time5` — `Y-m-d H:i:s`, `$today` — `Y-m-d`, plus `$time2`/`$time3`/
    `$time4` for shorter display forms.

  Rules, in order:

  1. **Never call `date()` again to get "now".** Reuse the canonical
     value, so every row written by one request carries the same instant
     and timestamps cannot drift mid-request. Inside a function that
     cannot rely on the global, read `$GLOBALS['time']` (or `$time5`)
     with a same-format fallback — see `activity_now()` in
     `erp/modules/activity_log.php` and `staff_attendance_now()` in
     `erp/modules/staff_attendance.php` for the established pattern.
  2. **`$time` is the standard.** `activity_log.al_at` is `VARCHAR(22)`
     sized precisely for it; `attendance_staff`'s `as_in_datetime`,
     `as_out_datetime`, `as_created_at` and `as_updated_at` are
     `varchar(100)` and store it.
  3. **A real `DATETIME`/`DATE` column cannot hold `$time`** — MySQL
     rejects `d-m-Y h:i:s A` and stores a zero date. Those columns take
     `$time5` (still the canonical value, just the representation the
     column accepts). `attendance_staff_correction.asc_*`,
     `cron_job_log.cjl_started_at`, `admin_action_audit.aaa_created_at`
     and similar are `DATETIME` and stay on `$time5`. **Check the column
     type before choosing.**
  4. **`NOW()` stays** where it is a database-side expression — a
     `WHERE ... > NOW() - INTERVAL` comparison, or a column `DEFAULT`.
     Do not replace those with a PHP value.
  5. **Only "now" is standardised.** Business dates keep their own
     values: dates of birth, selected attendance dates, fee due dates,
     academic session dates, report dates, and timestamps supplied by an
     external provider (a payment gateway's event time) are data, not
     the current time. Never overwrite them with `$time`.
  6. A `varchar` column holding `d-m-Y h:i:s A` does not sort or
     range-compare correctly in SQL. Convert with
     `STR_TO_DATE(col, '%d-%m-%Y %h:%i:%s %p')` before any `ORDER BY`,
     `BETWEEN` or `<`/`>` on such a column. In PHP, `strtotime()` parses
     the format correctly, including AM/PM, midnight and noon.
  7. **When in doubt about an existing column**, check its type and how
     it is already queried before assuming either representation.

- No `#` prefix on any UI-facing identifier.

## 5a. Comment policy — write none

**This codebase contains no comments, and none may be added.** As of
2026-08-30 every comment was deliberately stripped from all project code
(PHP, JavaScript, CSS) — roughly 3,900 of them — and the count is now
zero. This is the maintainer's explicit standing decision, not an
oversight to be corrected.

Rules:

- Do not add `//`, `#`, `/* */`, `/** */` or `<!-- -->` comments to any
  project file, for any reason — not a "why", not a security note, not a
  TODO, not a heading or section banner, not a docblock, and not a
  one-line explanation of something subtle. There is no exception
  category.
- Do not reintroduce a comment that a previous pass removed.
- If code needs explanation, express it in the code: a clear function
  name, a named intermediate variable, a small extracted function.
- Where something genuinely cannot be expressed in code (a schema
  change, a licensing constraint, a known limitation, an operational
  caveat), put it in `docs/`, in the commit message, or in the pull
  request — never in the source file.
- Vendored third-party code under `erp/assets/` (tcpdf, PHPMailer,
  fonts) is the sole exception: it is upstream code, its comments and
  copyright/licence headers must be left exactly as shipped, and it must
  never be comment-stripped. Several of those files carry LGPL notices
  the licence requires retaining.

This applies to new files as much as edits to existing ones.

## 6. Frontend conventions

- Admin list views: DataTables.js (CDN-loaded — see
  `THIRD_PARTY_NOTICES.md`).
- PDF generation: TCPDF (`erp/assets/tcpdf/`).
- The mobile app-shell portals (`erp/schools/<CODE>/app/`) are a
  **separate frontend** from the desktop admin panel, sharing one design
  system (`erp/assets/app/portal.css` + `portal.js`). Full
  token/component reference: `docs/frontend.md`. Do not
  invent a new one-off `<style>` block on a portal page when an existing
  `bc-` component already covers the pattern.
- The desktop admin panel (`erp/schools/<CODE>/admin/`) has its own,
  separate shared foundation (`erp/assets/admin/admin-core.css`,
  `admin-components.css`, `admin-core.js` / `window.AX`) — started
  2026-08, still a progressive, in-progress consolidation of what was
  previously duplicated inline `<style>`/`<script>` per page, **not** a
  rewrite. See `docs/frontend.md`'s Part 2 for the full reference,
  including which per-page patterns it consolidates and its "Known gaps"
  section (most pages are not yet migrated — don't assume otherwise).
  Check there (component catalogue, `ax-` prefix convention) before
  writing new dashboard/card/pill/modal/empty-state markup by hand on an
  admin page.
- **PHP is the core backend language; this repo is not restricted to
  PHP for frontend work.** TypeScript, modern JS modules, and frontend
  build tooling are all permitted **when they provide a genuine,
  justified benefit** for real reusable-logic complexity — not adopted
  to look modern. As of this pass, neither shared JS file (`portal.js`,
  `admin-core.js`) uses a build step or TypeScript: both are plain
  global-scope JS, matching each other and matching this repo's actual
  zero-build-tooling deployment model (`docs/deployment.md` — a plain
  rsync of `erp/` to a traditional cPanel host, no `npm install`/build
  stage anywhere in that pipeline or in CI). If TypeScript is ever
  introduced, Node.js must stay a **development/build-time-only**
  dependency — production must never require a persistent Node.js
  process — and the built output must be plain, deployable static
  files following this repo's existing asset conventions
  (`erp/assets/<portal>/...`), documented in `docs/frontend.md` at the
  time it's added. Do not introduce React/Vue/Angular, convert any
  portal into an SPA, or otherwise replace the working PHP-rendered
  architecture — see section 2's multi-tenant rules and section 13's
  security rules, both of which apply to frontend code exactly as much
  as backend code (CSRF, tenant isolation, and server-side
  authorization/validation are never something frontend JS can
  substitute for).
- Frontend code follows the same comment discipline as the rest of this
  file: see section 5a — this codebase carries no comments at all.
- A pure visual/UI pass over any page must preserve every PHP
  business-logic block (queries, conditionals, auth/redirect checks)
  byte-for-byte. Verify with `php -l` plus a diff of the PHP block
  against the pre-change version.

## 7. Database conventions

- MariaDB, one database per tenant (e.g. the current production tenant's
  DB is named after its school code) plus a separate shared database for
  `erp/url_shortner/`.
- Full schema/config architecture: `docs/database.md`.
- Schema-change workflow and policy (there is no automated migration
  runner): `docs/database/README.md`. **Read that file before proposing
  any schema change.**

## 8. Storage conventions

Production storage lives at `erp/storage/<CODE>/`, per tenant, and is
never part of this repository (gitignored, except `erp/storage/.htaccess`
which hardens the tree and must ship). Always read/write through
`get_storage_path($module)` — never hardcode `/storage/`, `/erp/storage/`,
or a relative-`../`-counting path. A prior incident (silently broken
homework uploads) happened specifically because several files bypassed
this helper with hand-built paths — see `docs/storage.md` for the full
history, and search broadly (not just for the literal string
`erp/storage/`) before assuming no other file does this. One deliberate,
owner-approved exception exists and is documented there — don't "fix" it
without being asked.

Uploaded media (classroom photos/videos) resolves through
`get_storage_path('media')`. It used to live on a separate storage server
reached over HTTP; that server was removed entirely — see
`docs/media-upload.md`. Do not reintroduce a remote-upload path.

## 9. Authentication / authorization

Identity is unified through `staff` + `staff_history` + `ld` — not
`admin_users`, which was removed as an identity source; don't reintroduce
logic that treats it as authoritative. Four role-scoped portals
(admin/principal/teacher/student) share this identity source. Full model:
`docs/authentication.md`. Security controls (CSRF, login throttling, IP
gating, OTP gating) are documented with implementation status in
`SECURITY.md` — do not assume a control exists without checking there or
in the actual module.

## 10. Payments / payouts

Payment collection (Razorpay, PhonePe) and payouts (Cashfree, Zwitch)
each sit behind a provider-abstraction layer in `erp/modules/` — new code
must not call a gateway directly. Payment/payout webhooks must verify
their signature before trusting the payload (a missing signature check on
a payout webhook was a prior confirmed bug). This is the highest-stakes
part of the app — extra care and verification applies whenever touching
it, and idempotency for anything that moves money or sends an external
notification is not optional.

## 11. Cron / background processing

One master dispatcher per tenant
(`erp/schools/<CODE>/automated/cron/1_master_cron.php`) runs on a fixed
external schedule and dispatches individual job files from a `$tasks`
array based on time-of-day conditions, logging every run to
`cron_job_log` via `cron_job_log_record()`. **Do not create a second,
independent cron entry point for a new scheduled task** — add it to the
existing dispatcher's `$tasks` array following the established pattern
(its own `require_once .../config.php` + cron-secret check at the top so
it's also safe if hit directly by URL, wrapped in the dispatcher's
try/catch). Full job-by-job reference: `docs/cron.md`.

## 12. Logging / auditing

- `cron_job_log` — every dispatched cron job's start/end/duration/status/
  output/error.
- `sql_log` — every database query app-wide (pruned periodically).
- `api_activity_log` — every outbound/inbound/webhook HTTP call, via
  `api_request()` / `log_outbound_activity()`.
- `admin_action_audit`, `admin_auth_log`, `app_config_audit_log` — admin
  action history, admin auth events, and config-value change history
  (masked, not plaintext) respectively.
- Never log a credential, cron secret, session token, or other sensitive
  auth material — mask it first (see `mask_secret()` in
  `erp/modules/config.php` for the existing pattern).

## 13. Security

See **`SECURITY.md`** for the complete policy. Summary of what to check
before considering security-sensitive work done:

- SQL: parameterized queries only.
- State-changing POST forms: CSRF token issued + verified.
- Webhooks: signature verified before the payload is trusted.
- New secrets: added to `app_config` (optionally encrypted/marked
  secret), never hardcoded in a PHP file.
- File uploads: extension allowlist enforced, never trust the
  client-supplied MIME type/extension alone.
- OTP-gated flows: the gate is enforced server-side on every page
  load/refresh, never solely via a client-supplied parameter.

## 14. Testing

See `docs/testing.md` for current strategy, what exists, and what's
deliberately not built yet. Do not fabricate tests to make the repository
look more mature than it is — an honest "not yet tested" is more useful
than a fake green checkmark.

## 15. CI

`.github/workflows/php-check.yml` runs PHP syntax validation and PHPStan
(informational only, `continue-on-error`, until a baseline exists — see
`docs/static-analysis.md`) on every push/PR. There is no automated test
suite in this repository — keep the blocking syntax-check job passing;
extend CI deliberately (see `docs/testing.md`) rather than adding
heavyweight tooling for its own sake.

## 16. Deployment

Production is moving to a self-hosted **Windows 11 + XAMPP** server
(Apache + PHP + MariaDB + local filesystem) reached at
`erp.shpsrampuraphul.com`, with the application at
`D:\xampp\htdocs\erp`, `BASE_PATH = D:/xampp/htdocs`. Full build,
cutover, verification and rollback runbook:
`docs/deployment-windows-xampp.md`.

The previous flow — Git → GitHub → cPanel Git Version Control → a
deliberate deploy step into `public_html/erp/` — is documented in
`docs/deployment.md` and remains the rollback path until the old
deployment is retired.

**`git push` is not a deployment step** on either platform — treat it as
moving code to GitHub only, never as "this is now live."

## 17. Git workflow

`main` is worked on directly — there is no `feature/<name>` branch step
for normal work, including multi-file or risky changes (auth, payments,
schema). The established convention is:

```
current local codebase → implement → validate → commit directly to
main → push directly to origin/main
```

Rules:

1. Work directly on `main`.
2. Run `git status` first, before making changes.
3. Preserve unrelated local changes already present — don't discard or
   overwrite them.
4. Complete one logical unit of work at a time.
5. Validate it (see section 25, "How to validate changes").
6. Commit it.
7. Push directly to `origin/main`.
8. For a larger task, split it into multiple meaningful commits and push
   each completed logical unit separately, rather than one large commit
   at the end.
9. Never force-push or rewrite history.
10. Do not create a branch or a pull request unless the maintainer
    explicitly asks for one.

Create new commits rather than amending; never skip hooks unless
explicitly asked. Review `git status` and the actual `git diff` before
every commit.

## 18. Schema-change policy

There is no automated migration runner. Every schema change must be
written out as an explicit `.sql` statement and shown before or alongside
the PHP change that needs it — never silently assumed to already exist in
production, and never applied by Claude directly. Full workflow,
including the project's actual (numbered-file, apply-then-remove)
convention: `docs/database/README.md`.

## 19. Delivery pattern

The maintainer works in checkpoints: build → review → confirm stable →
continue. Prefer finishing one reviewable, working slice over a large
multi-file change that can't be checked in one pass. When a change is
risky or touches many files, say so up front and propose splitting it.

## 20. File-change discipline

- Keep changes scoped to the minimum set of files needed for the task.
- Do not reformat or restyle a file that isn't part of the current task,
  even if it looks inconsistent — that hides the real diff.
- Search for references before changing a shared function's signature or
  behavior (`sql()`, `config()`, `get_storage_path()`, and every
  `erp/modules/base.php` helper are used everywhere).
- Run `php -l` on every changed PHP file before calling a task done,
  where a PHP CLI is actually available in the working environment; if it
  is not, say so explicitly rather than claiming a check was run.

## 21. Safe operating rules

- Treat production data and production storage as real, non-disposable
  systems — never assume either is test data.
- Before any command that could discard uncommitted work, run `git
  status` first.
- Never delete, recursively replace, or "clean up" the storage folder.

## 22. Things Claude must NEVER do

- Reintroduce real credentials into `erp/config.php` — it must stay a
  thin, secret-free wrapper.
- Hardcode a new storage path/URL instead of calling `get_storage_path()`.
- Hardcode a new secret in a PHP file instead of adding it to
  `app_config`.
- Generate the current time with a fresh `date()` call instead of reusing
  `base.php`'s canonical `$time` (or `$time5` for a real `DATETIME`
  column) — see section 5.
- Hardcode a specific school's identity into shared (`erp/modules/`)
  code, or into documentation as the product's identity.
- Push directly to production, or treat `git push` as a deployment step.
- Change database schema without writing out the exact SQL and flagging
  it — and never apply a destructive migration (`DROP`, `TRUNCATE`,
  data-losing `ALTER`) without explicit confirmation.
- Add a comment of any kind to project code, or reintroduce one a
  previous pass removed (section 5a).
- Comment-strip vendored third-party code under `erp/assets/`, or remove
  a copyright/licence header from it.
- Touch files outside the minimum needed for the current task.
- Assume production database or storage is disposable/test data.
- Fabricate a test result, a validation step, or a fact not evidenced by
  the code or an explicit check that was actually run.

## 23. Things Claude SHOULD ALWAYS do

- Read before writing: check how similar existing modules/pages solve
  the same problem, and match that pattern.
- Inspect neighboring implementations before adding a new one.
- Search broadly (not just the exact literal string expected) before
  assuming a pattern is used consistently everywhere.
- Keep changes scoped, diff-reviewable, and explained.
- Preserve existing logic exactly during a pure UI/design-system pass.
- Show a diff-reviewable summary of what changed and why.

## 24. How to investigate an unfamiliar module

1. Read the module file itself in full. The code carries no comments
   (section 5a), so intent has to be read from naming, structure and
   call sites; `docs/` and `git log` hold the reasoning that used to sit
   in comments.
2. Grep for its public functions' call sites across the repo before
   assuming how it's used.
3. Check `docs/` for an existing write-up before writing a new one from
   scratch — `docs/architecture.md`, `docs/database.md`,
   `docs/authentication.md`, `docs/storage.md`, `docs/cron.md`,
   `docs/features.md` cover most subsystems.
4. If the module touches money, auth, or scheduled/background execution,
   treat it as high-stakes by default.

## 25. How to validate changes

- PHP: `php -l <file>` on every changed file, when a PHP CLI is available
  in the environment.
- SQL: read the statement carefully for parameter binding and type-string
  correctness; never execute a schema change directly against production.
- Cron/dispatcher changes: trace the dispatch path by hand (the
  `$tasks` array condition, the try/catch, the log call) since there is
  usually no way to trigger a real cron run from a coding session.
- UI/visual changes: diff the PHP business-logic block against the
  pre-change version; where a live browser is available, actually load
  the page and exercise the golden path plus at least one edge case.
- Where no live PHP/DB/browser is available in the working environment
  (common in this project's actual development setup), say so plainly in
  the summary rather than implying a check ran that didn't.

## 26. How to summarize changes

- State what changed and why, in the terms of the actual task — not a
  restated diff.
- Name genuine limitations plainly (e.g. "could not verify rendered
  output — no live PHP available") rather than omitting them.
- If a schema change is included, restate that it has not been applied
  and needs manual review/application per `docs/database/README.md`.
- Keep it proportional to the change — a one-file fix doesn't need a
  ten-point report.

## More detail

See the documentation index in `README.md` for the full set of `docs/`
references (architecture, database, storage, authentication, deployment,
frontend, cron, operations, runbooks, testing, features) and the
project-root policy documents (`SECURITY.md`, `THIRD_PARTY_NOTICES.md`,
`CHANGELOG.md`).