message-inbox-web-frontend-sdk/README.md

Messaging · Inbox · Support — Web Frontend SDK + Demo

A Slack-grade team-messaging experience delivered as a reusable React SDK plus a Next.js demo app, styled to match the LynkedUp Pro dashboard (dark + amber, with full light/dark support).

Everything runs as a static demo — no database, no external services. A BFF (Backend-For-Frontend) layer serves realistic mock data, so every feature works (send, react, thread, resolve tickets, search, theme…) with nothing to stand up.

Why an SDK + a BFF? The product surfaces (chat, inbox, support) are headless React hooks in @lynkd/messaging-inbox-sdk. They never talk to a backend directly — they call your BFF. Today the BFF is a set of Next.js route handlers returning mock data; tomorrow the same routes proxy the real IIOS service (or NestJS, Supabase, etc.) with zero changes to the UI. See docs/IIOS_INTEGRATION.md.

---

1. Quick start

# from the repo root
pnpm install
pnpm dev
# → http://localhost:4300

That's it. The app boots into #general with a full workspace of mock data.

Requirements: Node ≥ 20, pnpm ≥ 8. If pnpm dev complains about a pinned package manager, run corepack disable once (this repo intentionally has no packageManager pin so your local pnpm is used).

Full step-by-step local setup, troubleshooting, and a demo tour: docs/SETUP_LOCAL.md.

What to click in a demo (2-minute tour):

1. Send a message in #general — it appears instantly (BFF persists it in-memory).
2. Hover a message → react 🔥, reply in thread (opens the right panel), pin, save.
3. ⌘K / Ctrl+K → command palette; search "sync", "ava", "general".
4. Inbox (sidebar) → a unified "needs-reply / mentions / reactions" queue; mark done / snooze.
5. Support Center (rail) → tickets master-detail; open TCK-1042 (SLA breached), reply, resolve.
6. Theme toggle (top-right ☀️/🌙) and the Appearance panel (⚙️ next to your name) → switch accent, radius, gradient live.
7. Start a huddle (video icon in a channel header) → floating call bar.

---

2. Repository layout

message-inbox-web-frontend-sdk/
├─ packages/
│  └─ messaging-inbox-sdk/        # ← the SDK (publishable): @lynkd/messaging-inbox-sdk
│     └─ src/
│        ├─ types.ts              # domain model (User, Channel, Message, InboxItem, Ticket…)
│        ├─ config.ts             # feature flags + theme tokens + env resolution
│        ├─ theme.ts              # CSS-variable applier (light/dark, runtime)
│        ├─ client.ts             # BffClient — typed fetch wrapper (the only network seam)
│        ├─ provider.tsx          # <MessagingInboxProvider> + useSdk/useTheme/useFeature
│        ├─ hooks.ts              # useChannels/useMessages/useInbox/useTickets/useSearch…
│        └─ index.ts              # public API barrel
│
├─ apps/
│  └─ web/                        # ← the Next.js demo (@lynkd/web)
│     ├─ app/
│     │  ├─ layout.tsx            # resolves config on the server, injects theme, no-flash
│     │  ├─ (app)/                # the authenticated shell (rail + sidebar + header)
│     │  │  ├─ c/[id]/            # channel & DM view
│     │  │  ├─ inbox/             # inbox queue
│     │  │  └─ support/[id]/      # Support Center (master-detail)
│     │  └─ api/bff/**            # ← the BFF: route handlers over the mock store
│     ├─ components/              # nav, message, inbox, support, overlays, ui primitives
│     └─ lib/
│        ├─ mock/data.ts          # the seed dataset (users, channels, messages, tickets…)
│        ├─ mock/store.ts         # in-memory mutable store (swap for real backend)
│        ├─ config.ts             # getServerConfig() — env → SdkConfig
│        └─ ui-state.tsx          # app UI state (thread panel, palette, drawers, huddle)
│
├─ docs/                          # deep-dive docs (start with ARCHITECTURE.md)
└─ .claude/                       # project-local memory + notes for future devs & Claude Code

---

3. The three product surfaces

Surface	Route	What it is	Slack analogue
Messaging	/c/[id]	Channels, private channels, DMs, group DMs, threads, reactions, pins, mentions, presence, typing, huddles, rich composer, scheduled send	Channels + DMs
Inbox	/inbox	One queue for everything needing you — needs-reply, mentions, reactions, thread replies, saved, support & meeting follow-ups; snooze / done / archive	Activity + Later
Support Center	/support	Ticket console: list + filters + SLA, ticket detail with conversation, escalate / resolve / callback, agent availability	Intercom-style support

All three are built on the same kernel (the SDK + BFF), mirroring the IIOS idea that everything is an interaction behind the same gates. See docs/ARCHITECTURE.md.

---

4. Feature flags (turn anything on/off)

Every feature is gated by a NEXT_PUBLIC_FEATURE_* env var (defaults on). Copy apps/web/.env.example → apps/web/.env.local and flip flags:

NEXT_PUBLIC_FEATURE_HUDDLES="false"     # hides huddle buttons + bar
NEXT_PUBLIC_FEATURE_SUPPORT="false"     # removes the whole Support surface
NEXT_PUBLIC_FEATURE_SCHEDULED_SEND="false"

Full list + behaviour: docs/FEATURE_FLAGS.md.

---

5. Theming (match any brand, light + dark)

The default theme is sampled from LynkedUp Pro (accent #FDA913, dark surfaces, 20px cards). Restyle via env or the live Appearance panel in-app:

NEXT_PUBLIC_THEME_MODE="light"
NEXT_PUBLIC_THEME_ACCENT="#5b9dff"
NEXT_PUBLIC_THEME_RADIUS_CARD="28px"

Every color/radius/gradient is a CSS variable, so a brand swap is one env change. Full token reference: docs/THEMING.md.

---

6. Using the SDK in your own app

import {
  MessagingInboxProvider,
  useChannels,
  useMessages,
} from "@lynkd/messaging-inbox-sdk";

<MessagingInboxProvider bffBaseUrl="" theme={{ mode: "dark", accent: "#FDA913" }}>
  <YourChat />
</MessagingInboxProvider>;

function YourChat() {
  const { channels } = useChannels();
  const { messages, send } = useMessages(channels[0]?.id ?? null);
  // …render your own UI, or reuse the demo components
}

API reference + composition patterns: docs/SDK.md.

---

7. Going to a real backend

The UI only ever calls the BFF. To make it real, edit the handlers in apps/web/app/api/bff/** (or point NEXT_PUBLIC_BFF_BASE_URL at a standalone NestJS BFF) to call the IIOS service instead of the mock store. The request/response shapes already line up with the IIOS API. Step-by-step: docs/IIOS_INTEGRATION.md and docs/BFF.md.

---

8. Scripts

Command	What
pnpm dev	Run the demo at :4300
pnpm build	Production build of every package
pnpm typecheck	Type-check the SDK + app
pnpm start	Serve the production build

---

9. Docs index

• docs/SETUP_LOCAL.md — full local setup, config, demo tour, troubleshooting
• CLAUDE.md — project guide for Claude Code / contributors (commands, conventions, gotchas)
• docs/ARCHITECTURE.md — layers, data flow, BFF pattern, why-this
• docs/FEATURE_FLAGS.md — every flag and what it toggles
• docs/THEMING.md — token reference, light/dark, brand swap
• docs/SDK.md — hooks + provider API, composition
• docs/BFF.md — BFF contract + how the mock store works
• docs/IIOS_INTEGRATION.md — wire it to the real IIOS service
• .claude/ONBOARDING.md — start-here for new developers

Status: static demo (mock data). Not production-hardened. The Next.js version is pinned for the demo; upgrade to a patched release before any real deployment.