Signal — Social Intent Radar

An AI social-listening & reply-approval workspace. Find people publicly asking for a product like yours, score how relevant each conversation is, and approve or reject an AI-drafted reply before any human posts it. Every reply is human-approved — the app NEVER posts autonomously.

Demo tenant: "Join All Bettors", a FREE-TO-PLAY social prediction game (no real money, no deposits, 18+).

---

Quick start

bun install            # or: npm install
bun run dev            # http://localhost:3000
bun run lint           # ESLint
bun test src/lib/__tests__/scoring.test.ts   # unit tests for the scoring engine

First-run users see a 4-step onboarding wizard (pick platforms → pick countries → seed keywords → set voice). Skip anytime — re-runnable from the Safety view.

---

Tech stack

Concern	Choice
Framework	Next.js 16 (App Router) + TypeScript (strict)
Styling	Tailwind CSS 4 + shadcn/ui + Radix primitives
Motion	Framer Motion (150–200ms, ease-out)
State	Zustand (client) + Zod (schemas)
Charts	Recharts
Data grids	TanStack Table
Command palette	cmdk
Fonts	Inter (UI), JetBrains Mono (numerals & IDs)

All data is mocked through /lib/mockApi.ts — typed promises with 300–700ms simulated latency. User config + decisions persist to localStorage under the key signal.v1 and hydrate on mount to avoid SSR mismatch.

---

Design system — "Signal"

Calm, warm, editorial analyst tool. Soft depth, lots of whitespace, one accent per screen.

Color tokens (CSS variables in src/app/globals.css)

Token	Light	Dark	Use
--canvas	#FAF9F6	#16181A	page background (warm off-white / charcoal, NOT pure black)
--surface	#FFFFFF	#1E2124	cards
--surface-sunk	#F4F2ED	#262A2E	inputs, table stripes
--border	#E6E2DA	#32373C	hairline borders
--text	#1C1B19	#F2F0EC	body text
--text-muted	#6B6862	#9AA0A6	secondary text
--primary	#0F766E	#2DD4BF	deep teal — actions, links, active nav
--primary-soft	#E6F2F0	#1B2D2B	teal tint backgrounds
--success	#15803D	#4ADE80	approved, OK
--warning	#B45309	#FBBF24	medium intent, awaiting review
--risk	#B4405A	#F4728E	muted rose — NEVER pure red
--info	#1D4ED8	#60A5FA	charts, links

Type scale

11 / 12 / 14 / 16 / 20 / 28 / 40 / 56px. Sentence case for ALL labels. Micro-labels are 12px, --text-muted, medium weight, letter-spacing: 0.01em. Score numerals: JetBrains Mono, tabular-nums, tracking: -0.02em.

Shape & depth

• Radius: 8px inputs/badges · 12px cards · 16px modals · 999px pills
• Shadows: shadow-sm-signal, shadow-md-signal, shadow-lg-signal
• Spacing on an 8px grid. Card padding 20–24px. Max content width 1440px.

Intent color mapping (used everywhere, consistently)

Band	Score range	Style
High	80–100	teal solid pill
Medium	60–79	amber outline pill
Low	40–59	grey outline pill
Not relevant	0–39	muted grey text
Risk-flagged	(any)	rose pill with shield icon, always overrides score color

Accessibility (hard requirements, all met)

• WCAG 2.1 AA contrast on all text. Minimum body size 14px.
• Full keyboard operability; visible 2px --primary focus ring on every control.
• All icon-only buttons have aria-label.
• Live regions announce score updates.
• prefers-reduced-motion disables all transforms and auto-animations.
• Never encodes meaning in color alone — always paired with an icon or label.

---

Information architecture

Persistent left sidebar (collapsible to 64px icon rail), top bar with global search, ⌘K command palette, theme toggle, scan status chip and "Run scan".

1. Inbox (G I) — the triage surface
2. Triage (G T) — full-screen focused card stack
3. Insights (G N) — analytics
4. Playground (G P) — test a single message
5. Tuning (G U) — the config layer
6. Safety (G S) — compliance & guardrails
7. Activity (G A) — audit log

Mobile (<768px): sidebar becomes a bottom tab bar; Inbox becomes a single stacked list; the inspector opens as a full-screen sheet; triage mode becomes swipe-based. All KPI cards become a 2×2 grid. Fully usable. Tablet (768–1024px): two panes, inspector as an overlay drawer.

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗