Mike Sport Messenger + CRM

Overview

Mike Sport Messenger + CRM is a self-built customer-support and CRM platform meant to replace an external chat console for Mike Sport's Shopify storefronts (Lebanon, Iraq, Crocs Lebanon, Service Park). It unifies WhatsApp, Instagram DM, Facebook Messenger, and Email into a single agent inbox, and pairs that inbox with a first-class CRM so every conversation, order, task, and note resolves to one Contact record rather than several disconnected channel identities.

Problem

Mike Sport ran customer support through a third-party console plus separate SaaS pieces for CRM-like functionality, at a real recurring cost, with no single owner of customer identity across several channels and several Shopify stores. Agents had to piece together order history, prior conversations, and customer context by hand across tools that did not talk to each other.

Approach

The project is specified in a versioned build document (MIKESPORT_MESSENGER_SPEC.md) treated as the source of truth ahead of the code, with a companion CLAUDE.md codifying hard engineering rules (mobile-first at 375px, brand tokens, no unreviewed deploys, webhook auth ordering, secrets handling). The build was broken into phases covering schema, each messaging channel, the CRM core, the AI agent, shifts, RBAC, SLA/notifications, campaigns, and mobile polish, with each phase gated on a passing build.

Architecture

• Monorepo with npm workspaces: backend (Express + Prisma + PostgreSQL) and dashboard (Next.js App Router), sharing a root prisma/schema.prisma with 25 models.
• Webhook receivers for WhatsApp, Instagram, Facebook, and email are registered ahead of the auth middleware, since Meta and the email provider call them unauthenticated; each verifies its own signature inside the handler.
• A contact-resolver.ts service deduplicates identity across channels and stores (phone, email, WhatsApp id, Instagram id, Facebook PSID, per-store Shopify customer id) so one Contact aggregates activity from all channels and all stores.
• An activity-recorder.ts helper appends every meaningful event (message, order, note, task, campaign send, CSAT, AI tool call) to a single append-only Activity timeline per Contact.
• Role-based access control (Super Admin, Manager, Agent, Viewer) is enforced through a shared permission catalogue checked on both backend routes and frontend UI gates, plus per-user store/channel scope.
• Encrypted settings table (AES-256-GCM) holds integration secrets (Meta tokens, Shopify admin tokens, email provider keys) instead of committed credentials.

Tech stack

• Backend: Express, Prisma, PostgreSQL, Zod validation, Argon2 password hashing, JWT auth, Anthropic SDK
• Frontend: Next.js (App Router), React 19, Tailwind v4, shadcn-style primitives
• AI: Claude Haiku 4.5 via the Anthropic SDK
• Dev infra: Docker Compose (Postgres 16), local Prisma workflow (generate / push / studio)

Engineering highlights

• 25-model Prisma schema covering messaging (Conversation, Message, Campaign, MessageTemplate, AgentShift) and CRM (Contact, ContactIdentifier, Activity, Task, Note, Segment, CannedResponse, CustomFieldDef, WebhookEvent, ApiKey).
• WebhookEvent idempotency table dedupes Meta's webhook retries and doubles as a dead-letter queue, drained by a retry worker.
• SLA timer engine (first-response, next-response, resolution, per priority) with a 30-second tick worker and breach notifications fanned out via push, desktop, and email digest.
• Outbound API with per-key scopes and rate limiting so Shopify, ERP, or other automations can trigger sends without agent involvement.
• Full audit log covering role changes, conversation reassignment, manual sends, campaign launches, template submissions, settings changes, contact merges, GDPR deletes, and API key rotations, with secrets masked.
• Meta compliance logic built in: 24-hour customer-service window tracking with automatic composer fallback to templates, opt-in proof storage, frequency caps, quiet hours, and quality-rating auto-pause for campaigns.
• Mobile-first rule enforced throughout: every UI change is required to be verified at a 375px viewport before being considered complete.

Outcome

Per the repository's own README, the codebase reached feature-complete status: a Prisma schema of 25 models, a feature-complete backend (auth, RBAC, 24 route files, four channel clients, SLA/CSAT/retry workers, audit log, outbound API), and a feature-complete frontend (22 pages spanning login, inbox, thread view, a 360-degree CRM contact view, segments, snippets, settings, team management, audit log, api keys, and reports). The project's own status describes it as a feature-complete codebase awaiting external integration credentials, meaning the code runs against a local dev database but has not yet been wired to live Meta, Shopify, or email-provider credentials or deployed to production.