# IMS — Claude Code Instructions ## Project HSE Incident Management System for Setia Corporation (3PL warehouse). Replaces WhatsApp/Excel safety reporting. Client: Ms. Agnes, Mr. Terence, Mr. Yap, Mr. Jensen. ## Stack - **Frontend + API routes:** Next.js (App Router) - **DB + Auth + Storage:** Supabase (Postgres + RLS + pgvector) - **Hosting:** VPS at `http://64.176.82.100/ims/` + Supabase cloud - **AI:** Claude API — server-side only, never client-side - **Email:** Resend - **WhatsApp:** Meta WhatsApp Business Cloud API - **PDF:** pdf-lib (JKKP form fill) - **QR:** qrcode npm package ## Current Phase **All phases (0–6) complete as of 2026-07-12.** Remaining work is ops: production env vars (`SUPABASE_SERVICE_ROLE_KEY`, Meta WhatsApp, Resend, `CRON_SECRET`), VPS cron registration (`docs/vps-cron.md`), optional Supabase Pro for image thumbnails. See `[[phases]]` memory for full phase breakdown and deliverables. ## Deployment (Production) **Deploy path for ims.setia.com.my is `/var/www/ims` on 175.136.239.121:9321.** ```bash # Correct deployment: tar -czf - package.json package-lock.json .next | \ ssh -p 9321 setia@175.136.239.121 "cd /var/www/ims && tar -xzf -" pm2 restart wsims ``` PM2 process `wsims` runs from `/var/www/ims`. Nginx proxies `ims.setia.com.my` → `http://127.0.0.1:3003`. ## Dev Conventions - Never commit `.env` or API keys. All secrets in env vars only. - RLS enforced at DB level for every table — never rely on UI-only hiding. - Claude API calls: server-side API routes only (`/app/api/...`). - Incident reference format: `SITE-YYYYMM-####` - Every DB mutation writes to `audit_log` (table, record_id, action, changed_by, changed_at, old/new value). - Evidence files: never hard-delete; retain minimum 5 years (DOSH JKKP 8 requirement). - AI suggestions logged to `audit_log` — capture what Claude suggested + what human chose. ## File Structure (target) ``` IMS/ ├── docs/ # PRD, tech spec, roadmap, specs — source of truth ├── app/ # Next.js App Router pages + API routes ├── components/ # Shared UI components ├── lib/ │ ├── supabase/ # Supabase client + server helpers │ ├── claude/ # Claude API wrappers (server-side) │ └── notifications/ # Resend + WhatsApp senders ├── supabase/ │ └── migrations/ # SQL migration files └── public/ ``` ## Deep Context (memory files — load instead of re-reading raw docs) - `[[project_overview]]` — objectives, roles, success metrics - `[[architecture]]` — module diagram, stack rationale, deployment - `[[db_schema]]` — all 10 tables, fields, RLS, pgvector - `[[phases]]` — 4 phases + deliverables, current phase - `[[compliance]]` — NADOPOD 2004, JKKP 6/7/8 rules ## Design system (Modernist) Source of truth: the Modernist `readme.md` and `styles.css` under `design-system/_ds/`. Tokens live in `app/globals.css` (`@theme static`). Do not use `design-system/IMS Admin.dc.html` as a style reference. - Flat and architectural: Archivo, ink on a `#f3f2f2` ground, one accent `#ec3013`. Zero corner radius, visible grid, strong 2px rules between major sections (`border-divider`, `border-b-2`). - Use tokens, never hard-coded hex, font names or px values the tokens carry: `bg-ground`, `bg-surface`, `text-ink`, `bg-accent`, `border-divider`, `accent-100…900`, `neutral-100…900`. `gray-*`, `blue-*` and `red-*` are remapped onto the neutral and accent ramps. - No `rounded-*` (except circular avatars, allowlisted in `scripts/check-design-gates.mjs`). Labels and headings are flush left, including button labels. No centered hero copy. - Body-size accent text uses `accent-700`; the accent itself is for buttons, icons and large text. - Icons: Lucide (`lucide-react`). Interaction: hover tint, pressed step from the accent ramp, `:focus-visible` 2px accent ring (global), disabled at 45% opacity. - Build UI with `components/ui/*`: `Button`, `Tag`, `StatusTag`, `PriorityTag`, `Field`/`Input`/`Select`/`Textarea`, `Card`, `Modal`, and the `TABLE/TH/TR/TD` class constants. - Status is never color alone. Needs attention, open, overdue, reported or severity 4-5 = accent tag; in progress = outline tag; done, closed, verified, low = neutral tag. Always keep the text label and an icon. Add new statuses in `components/ui/status-tag.tsx`, not per page. - Incident evidence photos stay full color. `.grayscale` is for decorative photography only. - Gotcha: never write `*/` inside a CSS comment in `globals.css` (for example a glob like `modernist-*/`); it ends the comment and silently swallows the `@theme` block. - Run `npm run check:design` before committing UI changes; it must print `design gates: clean`. ## graphify When graphify-out/graph.json exists: - Run `graphify query ""` before browsing source. - Use `graphify path "" ""` for relationships. - Use `graphify explain ""` for focused concepts. - After code changes: `graphify update .`