Files
ims/CLAUDE.md

86 lines
4.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 "<question>"` before browsing source.
- Use `graphify path "<A>" "<B>"` for relationships.
- Use `graphify explain "<concept>"` for focused concepts.
- After code changes: `graphify update .`