ClientSphere – SaaS Admin Dashboard

A full-stack SaaS admin dashboard built with the MERN stack. ClientSphere gives administrators a central hub to manage clients, track key performance indicators, and control access — all in a clean, responsive interface.

---

Table of Contents

• Features
• Tech Stack
• Getting Started
  • Prerequisites
  • Installation
  • Configuration
  • Running the App
• Project Structure
• API Reference
• Deployment
• Contributing
• Support
• Author

---

Features

• Authentication – JWT-based login with 7-day token expiry and bcrypt password hashing
• Role-Based Access Control – Admin and User roles; admin-only routes enforced on both client and server
• Client Management – Create, view, and list clients with attributes: name, email, phone, plan, and status
• Analytics Dashboard – KPI cards (total clients, active clients, monthly revenue) and interactive charts powered by Recharts
• Responsive UI – Collapsible sidebar, adaptive grid layouts, and mobile-friendly components built with Tailwind CSS
• CI/CD Pipeline – Automated builds and deployments to Vercel (frontend) and Render (backend) via GitHub Actions

---

Tech Stack

Layer	Technology
Frontend	React 19, Vite, Tailwind CSS, React Router DOM, Recharts, Axios
Backend	Node.js 20, Express 4, MongoDB 8 (Mongoose), JWT, bcryptjs
DevOps	GitHub Actions, Vercel (frontend), Render (backend)

---

Getting Started

Prerequisites

• Node.js v20 or later
• npm v9 or later
• MongoDB – a running local instance or a MongoDB Atlas cluster

Installation

1. Clone the repository

   git clone https://github.com/anan5093/saas-admin-dashboard.git
   cd saas-admin-dashboard

2. Install server dependencies

   cd server
   npm install

3. Install client dependencies

   cd ../client
   npm install

Configuration

Create a .env file in the server/ directory:

PORT=5000
MONGO_URI=mongodb://127.0.0.1:27017/saas_admin
JWT_SECRET=your_jwt_secret_here

Variable	Description
PORT	Port the Express server listens on
MONGO_URI	MongoDB connection string
JWT_SECRET	Secret key used to sign JWT tokens

Note: Never commit .env to version control. A .env.example file is recommended for sharing the required variable names.

Running the App

Open two terminals and start both services simultaneously:

Terminal 1 – Backend

cd server
npm run dev
# Server running on http://localhost:5000

Terminal 2 – Frontend

cd client
npm run dev
# App running on http://localhost:5173

Open http://localhost:5173 in your browser. Register an account (available in development) or log in if you already have credentials.

Other useful commands:

# Lint the frontend code
cd client && npm run lint

# Build the frontend for production
cd client && npm run build

# Preview the production build locally
cd client && npm run preview

# Start the server in production mode
cd server && npm start

---

Project Structure

saas-admin-dashboard/
├── .github/
│   └── workflows/
│       └── main.yml          # CI/CD: build & deploy on push to main
├── client/                   # React frontend (Vite)
│   └── src/
│       ├── components/       # Reusable UI and layout components
│       │   ├── dashboard/    # Charts, RecentActivity
│       │   ├── layout/       # Layout, Navbar, Sidebar, Footer
│       │   └── ui/           # Button, Input, Badge, KpiCard
│       ├── context/          # AuthContext, LayoutContext (Context API)
│       ├── data/             # Static seed data for KPIs and clients
│       ├── pages/            # Route-level page components
│       │   ├── auth/         # Login, Register
│       │   ├── clients/      # Clients list, AddClient, ClientDetails
│       │   ├── dashboard/    # Main Dashboard
│       │   └── settings/     # Profile
│       ├── routes/           # AppRoutes, ProtectedRoute
│       └── services/         # Axios wrappers for API calls
└── server/                   # Express backend
    └── src/
        ├── config/           # MongoDB connection (db.js)
        ├── controllers/      # authController, clientController
        ├── middleware/        # JWT protect(), adminOnly()
        ├── models/           # User, Client Mongoose schemas
        └── routes/           # authRoutes, clientRoutes

---

API Reference

All client endpoints require a valid JWT token in the Authorization: Bearer <token> header and the caller must have the admin role.

Method	Endpoint	Auth Required	Description
POST	/api/auth/register	No	Register a new user (dev only)
POST	/api/auth/login	No	Log in, returns JWT + user object
GET	/api/clients	Admin	List all clients
POST	/api/clients	Admin	Create a new client
GET	/api/clients/:id	Admin	Get a single client by ID

Login request example:

curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "yourpassword"}'

Authenticated request example:

curl http://localhost:5000/api/clients \
  -H "Authorization: Bearer <your_token>"

---

Deployment

The project deploys automatically on every push to main via GitHub Actions (see .github/workflows/main.yml).

Service	Target	Trigger
Frontend	Vercel	Push to main
Backend	Render	Push to main (deploy hook)

Required GitHub Secrets:

Secret	Description
VERCEL_TOKEN	Vercel API token
VERCEL_ORG_ID	Vercel organization ID
VERCEL_PROJECT_ID	Vercel project ID
RENDER_DEPLOY_HOOK	Render deploy hook URL

---

Contributing

Contributions are welcome! Please open an issue to discuss your idea before submitting a pull request.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit your changes: git commit -m "feat: add your feature"
4. Push to your fork: git push origin feature/your-feature
5. Open a pull request against main

---

Support

If you run into any issues or have questions:

• Open an issue on the GitHub Issues page
• Check existing issues before opening a new one

---

Author

Anand Raj

• GitHub: @anan5093
• LinkedIn: Anand Raj