86 lines
4.9 KiB
Markdown
86 lines
4.9 KiB
Markdown
# 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 .`
|