CLAUDE.md

Guidance for Claude Code (and humans) working in this repo.

What this is

A static demo (mock data, no real backend) of a Slack-grade messaging + inbox + support product, shipped as a reusable React SDK + a Next.js demo app, styled to match the LynkedUp Pro dashboard (dark + amber #FDA913, plus full light mode). Built on the BFF pattern: the UI only ever calls its own BFF (Next route handlers over an in-memory store), so swapping to a real backend (IIOS / NestJS / Supabase) touches only the BFF.

Commands

pnpm install            # Node >= 20, pnpm >= 8
pnpm dev                # dev server → http://localhost:4300
pnpm build              # production build (all packages)
pnpm typecheck          # type-check SDK + app
pnpm --filter @lynkd/web dev   # run just the web app

There is no packageManager pin on purpose (a pin made corepack try to fetch a pnpm build and fail offline). If corepack nags, run corepack disable once. sharp's build is intentionally skipped (allowBuilds: sharp: false in pnpm-workspace.yaml) — not needed for the static demo.

Two backend modes — BFF_BACKEND in apps/web/.env.local:

mock (default): rich in-memory JSON workspace, everything works. Best for demos.
iios: proxies the live IIOS service. Run IIOS + node scripts/seed-iios.mjs to populate it, then flip the flag. Full steps in docs/IIOS_INTEGRATION.md. Redis not required.

reactStrictMode is off (next.config) so dev matches prod render behaviour (avoids the double-mount that broke imperative DOM effects).

Layout

packages/messaging-inbox-sdk/src/   the SDK (@lynkd/messaging-inbox-sdk)
  types.ts      domain model      config.ts   feature flags + theme tokens + env resolution
  client.ts     BffClient (only fetch seam)   theme.ts   CSS-var applier
  provider.tsx  <MessagingInboxProvider> + useSdk/useTheme/useFeature
  hooks.ts      useMessages/useThread/useInbox/useTickets/useSearch/useNotifications/…
apps/web/
  app/layout.tsx            server: resolves config, no-flash theme script
  app/(app)/…               shell routes: c/[id], inbox, support/[id], threads, saved, …
  app/api/bff/**            the BFF (route handlers) — 1:1 with BffClient methods
  components/nav|message|inbox|support|overlays|ui   presentation
  lib/mock/{data,store}.ts  seed data + in-memory mutable store (the swap seam)
  lib/{config,ui-state,format,rich-text}.ts

Conventions

Components using SDK hooks or useUi need "use client". Route page.tsx are thin server components that render a client view.
Never hard-code colors/radii. Use semantic Tailwind tokens (bg-panel, text-muted, border-border, bg-accent, rounded-card, rounded-control) → they map to CSS vars, which is what keeps light/dark + live theming working.
Feature flags are data: add to FeatureFlags/defaultFlags in config.ts; env override is automatic (NEXT_PUBLIC_FEATURE_<UPPER_SNAKE>); read with useFeature("x").
Overlays/modals/toasts live in lib/ui-state.tsx (useUi): openModal, toast, openThread, openProfile, startHuddle, etc. Escape closes the top-most surface.
The composer is a contentEditable WYSIWYG that serializes to markdown; lib/rich-text.tsx renders that markdown. Keep the two in sync if you add a marker.
Adding a data feature touches, in order: lib/mock/store.ts → app/api/bff/**/route.ts → client.ts → hooks.ts → the component.

Gotchas

The mock store is a globalThis singleton to survive HMR. If you add/rename a store method and get "X is not a function" at runtime, bump the cache key (__lynkdStore_vN) in lib/mock/store.ts or restart pnpm dev.
Next 15 route-handler params are async: { params }: { params: Promise<…> } + await params.
Next.js is pinned at a demo version with a known CVE — bump before any real deploy.
BFF params/mock timestamps are relative to server start; the store resets on restart.

Verifying changes

Drive the real app (Playwright MCP or a browser) — don't rely on types alone. Quick checks: send a message, react via hover, create a channel, resolve a ticket, toggle theme, resize to ~400px. See docs/ for deep dives and .claude/ for project memory.

Docs

README.md · docs/SETUP_LOCAL.md · docs/ARCHITECTURE.md · docs/BFF.md · docs/SDK.md · docs/THEMING.md · docs/FEATURE_FLAGS.md · docs/IIOS_INTEGRATION.md · .claude/ONBOARDING.md

4.4 KiB Raw Blame History