Globussoft Enterprise CRM

# Globussoft Enterprise CRM

> A full-stack enterprise CRM built by Globussoft Technologies. Multi-tenant
> with **vertical configurations** (generic B2B / **wellness**). Tenant-driven
> currency + locale. External partner API for sister products (Callified.ai,
> AdsGPT). Embeddable lead-capture widget. AI orchestration engine. Mobile-
> responsive UI. Email delivery via SendGrid. CAPTCHA via Cloudflare Turnstile.
> Canonical `{error, code}` envelope on every JSON failure.

**At a glance** *(counts auto-derived from the codebase; refresh on every release)*

| Surface | Count |
|---|---|
| API routes | 157 (`backend/routes/*.js`) |
| Data models | 211 (`prisma/schema.prisma`) |
| UI pages | 261 (`frontend/src/pages/`) |
| Automation engines | 38 (`backend/cron/`) |
| Playwright spec files | 282 (`e2e/tests/`) — per-push gate runs a subset, e2e-full runs all |
| Backend vitest files | 543 (`backend/test/`) |
| Frontend vitest files | 258 (`frontend/src/__tests__/`) |
| Reusable Claude Skills | 20 (`.claude/skills/`) |

**Deploy pipeline** *(GitHub Actions)*

- **Per-push gate** — 6 mandatory deploy gates on every `main` push: build / lint / api_tests / unit_tests / frontend_unit_tests / migration_check. Auto-deploy on green with health-check rollback. Concurrency-group-serialized so sibling pushes queue.
- **PR pre-merge gate** — vite build + ESLint on every PR before squash-merge.
- **Tag-triggered e2e-full** — full chromium release-validation suite (4-shard parallel) fires on every `git tag v*` push.
- **Demo monitor** — 30-min health cron against `crm.globusdemos.com`; auto-opens an issue on failure.
- **Commit-message blessings** (e.g. `[allow-unique]`) waive specific migration-safety detectors for legitimate schema changes.

**Live:** [crm.globusdemos.com](https://crm.globusdemos.com) | **Version:** v3.9.3
**Wellness vertical docs:** [docs/wellness-client/](docs/wellness-client/) | **Partner API docs:** [EXTERNAL_API.md](docs/wellness-client/EXTERNAL_API.md) | **Embed widget docs:** [EMBED_WIDGET.md](docs/wellness-client/EMBED_WIDGET.md) | **API namespacing rules:** [API_NAMESPACING.md](docs/API_NAMESPACING.md) | **Cross-project monitor patterns:** [DEMO_MONITOR_PATTERN.md](docs/DEMO_MONITOR_PATTERN.md) + [LIVE_MONITOR_PATTERN.md](docs/LIVE_MONITOR_PATTERN.md)
**Engineering backlog:** [TODOS.md](TODOS.md) — read this before picking up new work. **QA prompts:** [QA_README.md](docs/QA_README.md) (wellness + generic split).

## Release notes & current work

- **What's changed across releases** → [CHANGELOG.md](CHANGELOG.md) is the canonical version history.
- **What's currently in flight / queued** → [TODOS.md](TODOS.md) is the engineering backlog.

This README documents the product as it stands today. It does not narrate per-version arcs — those live in CHANGELOG.md.

## Tech Stack

| Layer | Technologies |
|-------|-------------|
| Frontend | React 18, Vite, React Router v7, React.lazy() code splitting, Lucide Icons, Recharts, ReactFlow, React Grid Layout, Socket.io-client |
| Backend | Node.js, Express.js, Prisma ORM, MySQL, Socket.io, node-cron, PDFKit, pdf-lib, express-rate-limit, express-validator, Swagger UI |
| AI | Google Gemini 2.5 (@google/generative-ai), sentiment analysis, deal insights, lead scoring, voice transcription, data enrichment |
| Auth | JWT (bcryptjs), RBAC (ADMIN / MANAGER / USER), 2FA (speakeasy), SSO, SCIM |
| Security | Helmet, CSRF (csurf), sanitize-html, field-level permissions, GDPR consent tracking, rate limiting, **Cloudflare Turnstile CAPTCHA on landing-page forms** |
| Payments | Stripe, Razorpay |
| Communications | **SendGrid (transactional email — live on demo)**, Twilio (SMS/Voice), Fast2SMS / MSG91 (Indian SMS providers — DLT-aware), WhatsApp Cloud API, Web Push (VAPID), IMAP inbound email |
| Production | PM2, Nginx reverse proxy, Certbot SSL, Sentry error tracking |
| Testing | Playwright E2E (282 spec files — the per-push gate runs the gated API-spec subset, the rest in `e2e-full.yml` release-validation), vitest (543 backend + 258 frontend unit-test files) |
| Styling | Vanilla CSS with glassmorphism design, dark/light theme support |

---

## Feature Highlights

### Dashboard
Executive analytics overview with closed revenue, expected revenue, total contacts, conversion rate, pipeline chart, and recent deals. Date range filter (All Time / 7d / 30d / 90d / 365d).

![Dashboard](qa_screenshots/feature-dashboard.png)

---

### Agent Assignment on Leads
Assign sales agents to leads directly from the table. Supports individual assignment via dropdown and **bulk assignment** with multi-select checkboxes. Agents are fetched from the Staff directory.

![Agent Assignment - Leads](qa_screenshots/feature-agent-assignment-leads.png)

---

### Agent Assignment on Contacts
Same agent assignment capability on the full Contacts page. Each contact row shows an "Assigned To" dropdown to quickly assign or reassign agents.

![Agent Assignment - Contacts](qa_screenshots/feature-agent-a

... (truncated)