Client Management System

A production-quality full-stack CRM built as a technical assessment deliverable.

---

Table of Contents

1. Project Overview
2. Architecture
3. Tech Stack
4. Folder Structure
5. Getting Started
6. Environment Variables
7. Database Setup & Seed
8. API Documentation
9. Running Tests
10. Deployment
11. Assumptions & Known Limitations
12. Screenshots

---

Project Overview

A Client Management System (CRM) supporting three roles — Admin, Manager, and Employee/Sales Rep — with the following core features:

• 🔐 JWT authentication (access + refresh tokens), RBAC middleware
• 👥 Client CRUD with full CRM fields and soft-delete
• 📋 Kanban pipeline board with drag-and-drop status updates (dnd-kit)
• 📅 Task & follow-up management with overdue email reminders
• 📎 File attachments (Cloudinary or local disk)
• 🔔 Real-time notifications via Socket.io
• 📊 Role-aware dashboards (Recharts), KPI cards
• 📥 CSV & PDF export for client lists and pipeline reports
• 🔍 Full-text search, filter, sort, and pagination
• 📝 Audit log for all status changes and deletions
• 🌙 Dark/light mode, responsive layout, accessible components

---

Architecture

┌───────────────────────────────────────────────────────────┐
│  Browser (React + Vite)                                    │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ Auth    │  │ Clients  │  │Dashboard │  │ Reports  │  │
│  │ Pages   │  │ Kanban   │  │ Charts   │  │ Export   │  │
│  └────┬────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘  │
│       │            │              │              │         │
│  Zustand + TanStack Query + Axios + Socket.io client       │
└───────────────────────┬───────────────────────────────────┘
                        │ HTTP / WebSocket
┌───────────────────────▼───────────────────────────────────┐
│  Express.js API (Node.js 20)                               │
│  ┌──────┐ ┌────────┐ ┌───────┐ ┌──────────┐ ┌────────┐  │
│  │ Auth │ │Clients │ │Tasks  │ │Reports   │ │Audit   │  │
│  └──────┘ └────────┘ └───────┘ └──────────┘ └────────┘  │
│  Helmet · CORS · Rate Limit · JWT · RBAC · Multer         │
│  Socket.io Server · Nodemailer · pdfkit · fast-csv         │
└───────────────────────┬───────────────────────────────────┘
                        │ Mongoose ODM
┌───────────────────────▼───────────────────────────────────┐
│  MongoDB (Atlas in production / localhost in dev)          │
│  Collections: users · clients · activities · tasks        │
│               attachments · notifications · auditlogs     │
└───────────────────────────────────────────────────────────┘
                 Cloudinary (file storage)

---

Tech Stack

Layer	Technology
Frontend	React 18, Vite, TypeScript, Tailwind CSS, shadcn/ui
State	Zustand (UI/auth), TanStack Query (server state)
Routing	React Router v6
Forms	React Hook Form + Zod
Charts	Recharts
DnD	dnd-kit
HTTP client	Axios (with interceptors)
Backend	Node.js 20, Express.js 5
Database	MongoDB 7 + Mongoose 9
Auth	JWT (access 15m + refresh 7d), bcryptjs
Real-time	Socket.io 4
Files	Multer + Cloudinary (local disk fallback)
Email	Nodemailer + Ethereal (dev)
API docs	Swagger/OpenAPI 3, swagger-jsdoc, swagger-ui-express
Testing	Jest, Supertest, mongodb-memory-server, RTL
Dev tools	ESLint, Prettier, Nodemon
DevOps	Docker, docker-compose (stretch goal)

---

Folder Structure

client-management-system/
├── client/          # React + Vite frontend (Phase 3+)
├── server/          # Express + MongoDB backend
│   ├── src/
│   │   ├── config/      # db, cloudinary, mail, socket
│   │   ├── middleware/  # auth, rbac, errorHandler, rateLimiter, validate, upload
│   │   ├── models/      # 7 Mongoose schemas
│   │   ├── modules/     # Feature modules (auth, clients, tasks…)
│   │   ├── utils/       # asyncHandler, apiResponse, tokenHelpers, emailTemplates
│   │   └── swagger/     # OpenAPI spec
│   ├── tests/       # Jest + Supertest integration tests
│   └── scripts/     # seed.js
├── docs/            # Screenshots, ER diagram, API reference, test results
├── .gitignore
└── README.md

---

Getting Started

Prerequisites

• Node.js 18+ and npm
• MongoDB 6+ running locally (or an Atlas connection string)

Installation

# Clone the repo
git clone <repo-url>
cd client-management-system

# Install backend dependencies
cd server
npm install
cp .env.example .env
# Edit .env with your values

# Start the backend in dev mode
npm run dev

The frontend setup instructions will be added in Phase 3.

---

Environment Variables

See server/.env.example for a full list.

Key variables:

Variable	Description
MONGO_URI	MongoDB connection string
JWT_ACCESS_SECRET	Secret for access token signing (min 32 chars)
JWT_REFRESH_SECRET	Secret for refresh token signing (min 32 chars)
JWT_ACCESS_EXPIRY	Access token TTL (default 15m)
JWT_REFRESH_EXPIRY	Refresh token TTL (default 7d)
USE_LOCAL_STORAGE	true = skip Cloudinary, use local uploads/ dir
CLOUDINARY_*	Cloudinary credentials (if USE_LOCAL_STORAGE=false)
SMTP_*	Email credentials (auto-creates Ethereal account if empty)
CLIENT_URL	Frontend origin for CORS

---

Database Setup & Seed

# Start MongoDB locally
mongod --dbpath /data/db

# Or use Docker
docker run -d -p 27017:27017 --name cms-mongo mongo:7

# Seed the database with realistic demo data
cd server
npm run seed

The seed script creates:

• 3 users (1 admin, 1 manager, 3 employees)
• 30 client records across all pipeline stages
• ~90 activity timeline entries
• ~45 tasks with varied statuses and priorities
• Sample attachments metadata

---

API Documentation

Interactive Swagger UI is available at:

http://localhost:5000/api/docs

Raw OpenAPI JSON: http://localhost:5000/api/docs.json

A static reference copy is saved in docs/api-reference.md.

---

Running Tests

cd server
npm test                # Run all tests
npm run test:coverage   # With coverage report

Test results are documented in docs/test-results.md.

---

Deployment

Full deployment instructions will be added in Phase 9.

Quick Reference

• Database: MongoDB Atlas (free tier)
• Backend: Render or Railway (set all env vars from .env.example)
• Frontend: Vercel or Netlify

Docker (Phase 9)

docker-compose up --build

---

Assumptions & Known Limitations

1. Registration: Public registration is enabled for demo. In production, restrict to admin-only.
2. Manager scope: Managers see clients assigned to users where managerId === manager._id.
3. Revenue: estimatedValue is a deal-value field (USD), not actual revenue.
4. File storage: When USE_LOCAL_STORAGE=true, files are stored in server/uploads/ — not suitable for multi-instance production deployments.
5. Email: Uses Ethereal auto-account in development if SMTP credentials are missing.

Future Enhancements

• Multi-currency support for deal values
• Two-factor authentication (TOTP)
• Google/OAuth SSO
• Granular permission system (beyond role-level RBAC)
• Mobile app (React Native)

---

Screenshots

Screenshots will be added in Phase 8 after the UI is complete.

Screen	Preview
Login	docs/screenshots/login.png
Dashboard	docs/screenshots/dashboard.png
Client List	docs/screenshots/client-list.png
Kanban Board	docs/screenshots/kanban.png
Client Detail	docs/screenshots/client-detail.png
Reports	docs/screenshots/reports.png