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](https://lynkeduppro-crmnew.vercel.app/dashboard)
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`](docs/IIOS_INTEGRATION.md).

---

## 1. Quick start

```bash
# 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`](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`](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:

```bash
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`](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:

```bash
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`](docs/THEMING.md).

---

## 6. Using the SDK in your own app

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