CLAUDE.md — Claude Code Implementation Guide

SOP Governance Tool (Stage 1, single-tenant)

You are pair-programming with a coding beginner, solo founder, 3PL logistics domain expert. Optimize for his learning and maintainability, never cleverness.

Project description

Web app for ONE company (founder's own warehouse) replacing manual SOP governance: Editors draft SOPs (AI-assisted), Approvers approve/reject, Admin publishes versioned snapshots, Staff view on phone in EN/BM/ZH and tap-acknowledge with a typed-name signature. Dashboard tracks acknowledgement %. Staff also report floor incidents (photo + severity) feeding SOP revisions. Every governance action is audit-logged.

Fixed stack (never substitute)

Next.js 14+ App Router + TypeScript · Supabase (Postgres + Auth + Storage + RLS) · Vercel · Anthropic API (server-side only) · Tailwind + shadcn/ui. No other DB, ORM (use supabase-js directly), state library, or i18n framework. Ask before adding ANY dependency not already in this list.

Hard rules

org_id on every table, RLS enabled on every table — non-negotiable even with 1 org.
State machine (canTransition(), nextVersion()) lives ONLY in lib/workflow.ts. No status transition logic duplicated elsewhere.
AI calls are server-side only (/api/ai/* routes), never from the client. ANTHROPIC_API_KEY and SUPABASE_SERVICE_ROLE_KEY only in server files / Vercel env vars.
Every mutation writes an audit_log row in the same transaction (route handler using service-role client).
Published SOP content is a frozen snapshot in sop_versions — never edit it; edits happen on the draft row only.
No secrets client-side, never disable RLS "temporarily", never mock away auth to make something work.

Spec-review decisions (apply when the relevant milestone is built)

Storage: sop-photos bucket, path-scoped policy — Editor+ write to SOP step paths; Staff insert-own under incidents/{user_id}/* (needed for FR-7.1 staff photo upload). Apply at M6.5/S19.
Approver scope: Approver acts org-wide, not department-scoped — PRD "in their scope" language is dropped, matches existing RLS/schema. No dept filter needed on approvals.
FR-3.2 notification: "Editor notified in-app" = visible via SOP status change + History (audit) tab. No separate notifications table/UI.
sop_status enum: drop archived — unused in Stage 1, remove from create type sop_status in db/schema.sql at S2.

Directory layout (from 03-architecture §4)

/app
  /(auth)/login
  /(admin)/dashboard  /sops  /sops/[id]/edit  /approvals  /users  /audit
  /(staff)/my-sops  /my-sops/[id]
  /api/sops/... /api/ai/... /api/ack ...
/components   (ui/ = shadcn, sop/ = editor pieces, staff/ = mobile viewer)
/lib
  supabase/ (browser client, server client, service client)
  ai/ (anthropic client, prompts, parsers)
  workflow.ts (status machine)
  audit.ts (writeAudit())
/db
  schema.sql  policies.sql  seed.sql
/docs (spec pack)
CLAUDE.md

How we work together

One milestone at a time, per docs/07-development-plan.md session plan (S1...S22). Don't build ahead.
Before writing code for a step: explain the plan in plain English first, wait if it's non-trivial.
After writing code: 3–5 line plain-English summary of what it does and why. If asked "explain", go line-by-line.
Ask before: adding a dependency, changing the schema, deviating from a spec, deleting more than ~30 lines.
When something fails: show the error, plain-English diagnosis, then the fix.
Test in the browser after each small step before moving to the next.

Conventions

TypeScript strict; server components by default, "use client" only when needed.
Reads use the user-scoped client under RLS; writes/workflow mutations go through /app/api/* with the service-role client.
Errors: { error: { code, message } } with correct HTTP status (05-api-spec §6).
Commits: imperative plain English, after each working step ("Add SOP publish route with version snapshot").
Files: kebab-case; components PascalCase; one component per file.

Current milestone

M0 — Setup (S1). Scaffold Next.js + TypeScript + Tailwind + shadcn/ui; create Supabase project (Singapore region); Supabase clients in lib/supabase/; env wiring; deploy hello world to Vercel.

Definition of done (any task)

Works in the browser · matches its FRD acceptance criteria · no TypeScript errors · explained in plain English · committed · deployed preview checked.

Scratch — next session goal

(Write 1–2 lines here before each session.)

Ignore the add-module skill — it targets a different stack.

4.6 KiB Raw Blame History Unescape Escape