Files
ims/CLAUDE.md

4.9 KiB
Raw Permalink Blame History

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.

# 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 .