Cloudtopiaa_Reseller_Backend/README.md

# Cloudtopiaa Reseller Portal - Backend

A comprehensive Node.js/Express backend for the Cloudtopiaa Reseller Portal, supporting both Channel Partners and Resellers with role-based access control and advanced features.

## 🚀 Features

### **Authentication & Authorization**
- JWT-based authentication with refresh tokens
- Role-based access control (RBAC)
- Multi-factor authentication (MFA) support
- Email verification and password reset
- Session management with Redis
- Comprehensive audit logging

### **User Management**
- **Channel Partner Roles**: Admin, Manager, Sales, Support, Finance, Analyst
- **Reseller Roles**: Admin, Manager, Sales, Support, Finance, Analyst
- **System Roles**: Admin, Support, Analyst
- User hierarchy with manager-subordinate relationships
- Department and position tracking
- Onboarding workflow

### **Organization Management**
- **Channel Partners**: Manage reseller networks, territories, specializations
- **Resellers**: Manage customers, instances, billing
- Tier-based commission structures
- KYC verification workflow
- Performance metrics and analytics

### **Business Features**
- Product catalog management
- Customer lifecycle management
- Cloud instance provisioning
- Billing and invoicing
- Commission calculation and tracking
- Wallet management
- Support ticket system
- Training and certification tracking

### **Security & Compliance**
- Input validation and sanitization
- Rate limiting and DDoS protection
- CORS configuration
- Helmet security headers
- Audit trail for all actions
- Data encryption at rest and in transit

## 🏗️ Architecture

```
src/
├── config/           # Configuration files
├── controllers/      # Business logic controllers
├── middleware/       # Custom middleware
├── migrations/       # Database migrations
├── models/          # Sequelize models
├── routes/          # API route definitions
├── seeders/         # Database seeders
├── utils/           # Utility functions
└── app.js           # Main application file
```

## 🛠️ Technology Stack

- **Runtime**: Node.js 16+
- **Framework**: Express.js
- **Database**: PostgreSQL with Sequelize ORM
- **Cache**: Redis
- **Authentication**: JWT + bcrypt
- **Validation**: express-validator
- **Email**: Nodemailer
- **Security**: Helmet, CORS, Rate limiting
- **Logging**: Morgan + custom audit logs

## 📋 Prerequisites

- Node.js 16.0.0 or higher
- PostgreSQL 12.0 or higher
- Redis 6.0 or higher
- npm or yarn package manager

## 🔧 Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd Cloudtopiaa_Reseller_Backend
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Environment Configuration**
   Create a `.env` file in the root directory:
   ```env
   # Server Configuration
   NODE_ENV=development
   PORT=3000
   HOST=localhost

   # Database Configuration
   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=cloudtopiaa_reseller
   DB_USER=postgres
   DB_PASSWORD=your_password

   # Redis Configuration
   REDIS_HOST=localhost
   REDIS_PORT=6379
   REDIS_PASSWORD=

   # JWT Configuration
   JWT_SECRET=your_super_secret_jwt_key_here
   JWT_EXPIRES_IN=15m
   JWT_REFRESH_EXPIRES_IN=7d

   # Email Configuration
   SMTP_HOST=smtp.gmail.com
   SMTP_PORT=587
   SMTP_SECURE=false
   SMTP_USER=your_email@gmail.com
   SMTP_PASS=your_app_password
   SMTP_FROM=noreply@cloudtopiaa.com

   # Frontend URL
   FRONTEND_URL=http://localhost:3000

   # Rate Limiting
   RATE_LIMIT_WINDOW_MS=900000
   RATE_LIMIT_MAX_REQUESTS=100

   # Security
   BCRYPT_ROUNDS=12
   ```

4. **Database Setup**
   ```bash
   # Create database
   npm run db:create

   # Run migrations
   npm run migrate

   # Seed demo data
   npm run seed
   ```

5. **Start the server**
   ```bash
   # Development mode
   npm run dev

   # Production mode
   npm start
   ```

## 🗄️ Database Schema

### **Users Table**
- Comprehensive user management with role-based access
- Support for Channel Partners, Resellers, and System users
- Hierarchical organization structure
- Audit trail and activity tracking

### **Channel Partners Table**
- Organization details and KYC information
- Territory and specialization management
- Performance metrics and commission structures
- Contract and approval workflow

### **Resellers Table**
- Reseller organization details
- Channel partner relationships
- Commission and margin settings
- Customer and instance management

### **Additional Tables**
- Products, Customers, Instances
- Orders, Invoices, Commissions
- Wallets, Transactions
- Support tickets, Training courses
- Audit logs, User sessions

## 🔐 Role-Based Access Control

### **Channel Partner Roles**
- **Admin**: Full access to channel partner features
- **Manager**: Management access with limited admin functions
- **Sales**: Sales-focused access to resellers and products
- **Support**: Support-focused access to customers and tickets
- **Finance**: Finance-focused access to billing and reports
- **Analyst**: Analytics and reporting access

### **Reseller Roles**
- **Admin**: Full access to reseller features
- **Manager**: Management access with limited admin functions
- **Sales**: Sales-focused access to customers and instances
- **Support**: Support-focused access to instances and tickets
- **Finance**: Finance-focused access to billing and wallet
- **Analyst**: Analytics and reporting access

### **System Roles**
- **Admin**: Full system access
- **Support**: System support access
- **Analyst**: System analytics access

## 📡 API Endpoints

### **Authentication**
- `POST /api/auth/register` - User registration
- `POST /api/auth/login` - User login
- `POST /api/auth/refresh` - Refresh access token
- `POST /api/auth/logout` - User logout
- `GET /api/auth/verify-email/:token` - Email verification
- `POST /api/auth/forgot-password` - Password reset request
- `POST /api/auth/reset-password` - Password reset
- `GET /api/auth/profile` - Get user profile
- `PUT /api/auth/profile` - Update user profile

### **Channel Partners**
- `GET /api/channel-partners` - List channel partners
- `GET /api/channel-partners/:id` - Get channel partner details
- `POST /api/channel-partners` - Create channel partner
- `PUT /api/channel-partners/:id` - Update channel partner
- `DELETE /api/channel-partners/:id` - Delete channel partner
- `POST /api/channel-partners/:id/approve` - Approve channel partner
- `POST /api/channel-partners/:id/reject` - Reject channel partner
- `GET /api/channel-partners/:id/stats` - Get channel partner statistics
- `PUT /api/channel-partners/:id/tier` - Update channel partner tier

### **Resellers**
- `GET /api/resellers` - List resellers
- `GET /api/resellers/:id` - Get reseller details
- `POST /api/resellers` - Create reseller
- `PUT /api/resellers/:id` - Update reseller
- `DELETE /api/resellers/:id` - Delete reseller
- `POST /api/resellers/:id/approve` - Approve reseller
- `POST /api/resellers/:id/reject` - Reject reseller
- `GET /api/resellers/:id/stats` - Get reseller statistics

### **Additional Endpoints**
- Users, Products, Customers, Instances
- Billing, Orders, Commissions
- Reports, Analytics, Dashboard
- Support, Training, Marketplace
- Wallet, Legal documents

## 🔧 Development

### **Running Tests**
```bash
npm test
```

### **Database Operations**
```bash
# Create database
npm run db:create

# Drop database
npm run db:drop

# Run migrations
npm run migrate

# Undo last migration
npm run migrate:undo

# Run seeders
npm run seed

# Undo seeders
npm run seed:undo
```

### **Code Quality**
- ESLint for code linting
- Prettier for code formatting
- Input validation with express-validator
- Comprehensive error handling
- Audit logging for all operations

## 🚀 Deployment

### **Production Setup**
1. Set `NODE_ENV=production`
2. Configure production database and Redis
3. Set up SSL certificates
4. Configure reverse proxy (nginx)
5. Set up process manager (PM2)
6. Configure monitoring and logging

### **Environment Variables**
Ensure all required environment variables are set in production:
- Database credentials
- Redis configuration
- JWT secrets
- SMTP settings
- Security configurations

## 📊 Monitoring & Logging

### **Health Check**
- `GET /health` - System health status
- Database connectivity check
- Redis connectivity check

### **Audit Logging**
- All user actions are logged
- IP address and user agent tracking
- Resource access monitoring
- Security event logging

### **Performance Monitoring**
- Request/response logging
- Database query optimization
- Redis cache utilization
- Error tracking and alerting

## 🔒 Security Features

- **Authentication**: JWT with refresh tokens
- **Authorization**: Role-based access control
- **Input Validation**: Comprehensive validation
- **Rate Limiting**: DDoS protection
- **CORS**: Cross-origin resource sharing
- **Helmet**: Security headers
- **Audit Trail**: Complete action logging
- **Data Encryption**: At rest and in transit

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new features
5. Ensure all tests pass
6. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🆘 Support

For support and questions:
- Email: support@cloudtopiaa.com
- Documentation: [Link to documentation]
- Issues: [GitHub Issues]

## 🔄 Changelog

### Version 1.0.0
- Initial release
- Complete role-based access control
- Channel Partner and Reseller management
- Comprehensive API endpoints
- Security and audit features