first commit

2026-07-17 21:48:37 +05:30
commit f85599dac5
124 changed files with 10775 additions and 0 deletions
@@ -0,0 +1,86 @@
+# 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`