87 lines
4.4 KiB
Markdown
87 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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`
|