NEXUS Support Ticket System

NEXUS - A full-featured support ticket system with MongoDB integration and GitHub issue synchronization.

Features

Ticket Management: Create, read, update, and delete support tickets
GitHub Integration:
- Sync tickets with GitHub issues
- Receive GitHub webhooks to automatically create/update tickets from GitHub issues
- Two-way synchronization between tickets and GitHub issues
User Authentication: JWT-based authentication system with role-based access
Comment System: Add comments to tickets
Filtering: Filter tickets by status, priority, and category
Priority Levels: Low, Medium, High, Critical
Status Tracking: Open, In Progress, Resolved, Closed
Modern Web Interface: Clean, responsive UI for ticket management

Tech Stack

Backend: Node.js, Express.js
Database: MongoDB with Mongoose ODM
Authentication: JWT (JSON Web Tokens)
GitHub API: Axios for GitHub integration
Security: Helmet, CORS, Rate Limiting
Frontend: Vanilla HTML/CSS/JavaScript

Installation

Quick Start (Automated Installer)

The system includes automated installation scripts for easy setup:

Linux/macOS:

chmod +x install.sh
./install.sh

Windows:

.\install.ps1

Cross-Platform (Node.js):

node install.js

Docker:

docker-compose up -d

For detailed installation instructions, see docs/QUICKSTART.md or docs/SETUP.md.

Manual Installation

Prerequisites

Node.js (v14 or higher)
MongoDB (v4.4 or higher)
GitHub Account (for webhook integration)

Steps

Clone the repository:

git clone <repository-url>
cd nexus

Install dependencies:

npm install

Configure environment variables:

cp .env.example .env

Edit .env with your configuration:

PORT=3000
NODE_ENV=development
MONGODB_URI=mongodb://localhost:27017/nexus-support
GITHUB_WEBHOOK_SECRET=your_webhook_secret_here
GITHUB_TOKEN=your_github_personal_access_token_here
GITHUB_REPO_OWNER=your_github_username
GITHUB_REPO_NAME=your_repository_name
JWT_SECRET=your_jwt_secret_here_change_this_in_production

Start MongoDB (if not already running):

mongod

Start the server:

npm start

For development with auto-reload:

npm run dev

Access the application: Open your browser and navigate to http://localhost:3000

API Endpoints

Authentication

Register User

POST /api/users/register
Content-Type: application/json

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "securepassword",
  "role": "user"
}

Login

POST /api/users/login
Content-Type: application/json

{
  "username": "john_doe",
  "password": "securepassword"
}

Get Current User

GET /api/users/me
Authorization: Bearer <token>

Tickets

Create Ticket

POST /api/tickets
Content-Type: application/json

{
  "title": "Bug in login system",
  "description": "Users cannot login with special characters in password",
  "priority": "high",
  "category": "bug",
  "tags": ["frontend", "auth"],
  "createdBy": "John Doe",
  "createdByEmail": "john@example.com"
}

Get All Tickets

GET /api/tickets?status=open&priority=high

Query parameters:

status: Filter by status (open, in_progress, resolved, closed)
priority: Filter by priority (low, medium, high, critical)
category: Filter by category
assignedTo: Filter by assignee

Get Single Ticket

GET /api/tickets/:ticketId

Update Ticket

PUT /api/tickets/:ticketId
Content-Type: application/json

{
  "status": "in_progress",
  "assignedTo": "support_agent",
  "priority": "high"
}

Delete Ticket

DELETE /api/tickets/:ticketId

Add Comment

POST /api/tickets/:ticketId/comments
Content-Type: application/json

{
  "author": "John Doe",
  "authorEmail": "john@example.com",
  "content": "This issue has been reproduced"
}

Link to GitHub Issue

POST /api/tickets/:ticketId/link-github
Content-Type: application/json

{
  "issueNumber": 123,
  "issueUrl": "https://github.com/owner/repo/issues/123"
}

GitHub Integration

Handle Webhook

POST /api/github/webhook
X-GitHub-Event: issues
X-Hub-Signature-256: <signature>

Sync Ticket to GitHub

POST /api/github/sync-ticket/:ticketId
Authorization: Bearer <token>

GitHub Webhook Setup

Setting up GitHub Webhooks

Go to your GitHub repository settings
Navigate to Webhooks → Add webhook
Configure the webhook:
- Payload URL: https://your-domain.com/api/github/webhook
- Content type: application/json
- Secret: Use the value from GITHUB_WEBHOOK_SECRET in your .env
- Events: Select "Issues" and "Issue comments"

Supported GitHub Events

issues: Created, opened, closed, edited, labeled
issue_comment: Created

Creating GitHub Personal Access Token

Go to GitHub Settings → Developer settings → Personal access tokens
Generate a new token with repo scope
Add the token to your .env as GITHUB_TOKEN

Database Schema

Ticket Model

{
  ticketId: String (unique),
  title: String (required),
  description: String (required),
  status: Enum ['open', 'in_progress', 'resolved', 'closed'],
  priority: Enum ['low', 'medium', 'high', 'critical'],
  category: String,
  createdBy: String (required),
  createdByEmail: String (required),
  assignedTo: String,
  githubIssueNumber: Number,
  githubIssueUrl: String,
  comments: [{
    author: String,
    authorEmail: String,
    content: String,
    createdAt: Date
  }],
  tags: [String],
  createdAt: Date,
  updatedAt: Date,
  resolvedAt: Date
}

User Model

{
  username: String (unique, required),
  email: String (unique, required),
  password: String (required),
  role: Enum ['admin', 'support_agent', 'user'],
  githubUsername: String,
  createdAt: Date
}

Security Features

Helmet: Security headers for Express with explicit Content Security Policy
CORS: Cross-Origin Resource Sharing configuration with origin control
Rate Limiting: 100 requests per 15 minutes per IP
Login Rate Limiting: 5 login attempts per 15 minutes per IP
JWT Authentication: Secure token-based authentication with 1-hour expiration
Password Hashing: Bcrypt for secure password storage
Password Complexity: Minimum 8 characters with uppercase, lowercase, number, and special character requirements
Webhook Verification: GitHub signature verification
Input Validation: Comprehensive input validation on all endpoints
Environment Variable Validation: Checks for required environment variables
Input Sanitization: NoSQL injection protection, XSS protection, parameter pollution prevention
HTTPS Enforcement: Automatic redirect to HTTPS in production
HSTS: HTTP Strict Transport Security enabled
MongoDB SSL/TLS: Configurable encrypted database connections
Security Audit Logging: Logs authentication attempts, rate limits, and suspicious activities
Body Size Limits: 10kb limit on request bodies

Recent Improvements

System Enhancements

Automated Installation Scripts: Cross-platform installers for Linux, macOS, and Windows
Docker Support: Complete containerized setup with Docker Compose
Enhanced Error Handling: Improved error messages and validation
Input Validation: Added comprehensive validation to all API endpoints
Security Hardening: Added environment variable checks and improved authentication
Sci-Fi Theme: Modern, futuristic user interface theme

Documentation

Quick Start Guide: Get running in under 10 minutes
Platform-Specific Setup: Dedicated guides for Windows, Linux, and macOS
Comprehensive API Docs: Complete API reference with examples
Architecture Documentation: System design and component overview
Automated Installer Docs: Guide for using automated installation scripts

Project Structure

nexus/
├── config/
│   └── database.js          # MongoDB connection
├── controllers/
│   ├── ticketController.js   # Ticket business logic
│   ├── githubController.js   # GitHub integration logic
│   └── userController.js     # User authentication logic
├── middleware/
│   ├── auth.js               # JWT authentication middleware
│   └── githubWebhook.js      # GitHub webhook verification
├── models/
│   ├── Ticket.js             # Ticket MongoDB model
│   └── User.js               # User MongoDB model
├── public/
│   └── index.html            # Frontend interface (sci-fi theme)
├── routes/
│   ├── ticketRoutes.js       # Ticket API routes
│   ├── githubRoutes.js       # GitHub API routes
│   └── userRoutes.js         # User API routes
├── docs/                     # Documentation
│   ├── QUICKSTART.md         # NEXUS Quick Start Guide
│   ├── SETUP.md               # NEXUS Detailed Setup Guide
│   ├── SETUP-WINDOWS.md       # NEXUS Windows Setup Guide
│   ├── SETUP-LINUX.md         # NEXUS Linux Setup Guide
│   ├── SETUP-MAC.md           # NEXUS macOS Setup Guide
│   ├── INSTALLATION.md        # NEXUS Installation Documentation
│   ├── DEVELOPER.md           # NEXUS Developer Guide
│   ├── API.md                 # NEXUS API Documentation
│   ├── DEPLOYMENT.md          # NEXUS Deployment Guide
│   ├── TROUBLESHOOTING.md     # NEXUS Troubleshooting Guide
│   ├── FAQ.md                 # NEXUS Frequently Asked Questions
│   ├── ARCHITECTURE.md        # NEXUS Architecture Documentation
├── .env.example              # Environment variables template
├── .gitignore                # Git ignore rules
├── .dockerignore              # Docker ignore rules
├── package.json              # Project dependencies
├── install.sh                 # Automated installer (Linux/macOS)
├── install.ps1               # Automated installer (Windows)
├── install.js                 # Automated installer (Cross-platform)
├── docker-compose.yml         # Docker Compose setup
├── Dockerfile                 # Docker image definition
├── README.md                 # This file
└── server.js                 # Main application entry point

Usage Examples

Creating a Ticket via Web Interface

Navigate to http://localhost:3000
Click "Create Ticket"
Fill in the ticket details:
- Title: Brief description of the issue
- Description: Detailed explanation
- Your Name: Your display name
- Your Email: Your email address
- Priority: Select from dropdown
- Category: Optional category
- Tags: Comma-separated tags
Click "Create Ticket"

Syncing a Ticket to GitHub

View a ticket from the ticket list
If the ticket is not linked to GitHub, you can sync it
Click "Sync with GitHub" button
A GitHub issue will be created and linked to the ticket

Viewing GitHub-Linked Tickets

Tickets created from GitHub webhooks will have a GitHub link
Click the "View on GitHub" button to open the issue on GitHub
Comments from GitHub will sync to the ticket

Development

Adding New Features

Add models in models/ directory
Create controllers in controllers/ directory
Define routes in routes/ directory
Add middleware in middleware/ directory if needed
Register routes in server.js

Testing API Endpoints

Use tools like Postman or cURL to test API endpoints:

# Create a ticket
curl -X POST http://localhost:3000/api/tickets \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Ticket",
    "description": "This is a test",
    "createdBy": "Test User",
    "createdByEmail": "test@example.com"
  }'

# Get all tickets
curl http://localhost:3000/api/tickets

# Get specific ticket
curl http://localhost:3000/api/tickets/TCK-ABC123

Troubleshooting

MongoDB Connection Issues

Ensure MongoDB is running: mongod
Check your MONGODB_URI in .env
Verify MongoDB is accessible on the specified port

GitHub Webhook Not Working

Verify webhook URL is publicly accessible (use ngrok for local testing)
Check webhook secret matches in both GitHub and .env
Review GitHub webhook delivery logs in repository settings

Authentication Errors

Ensure JWT_SECRET is set in .env
Verify token is being sent in Authorization header
Check token expiration (default: 7 days)

License

MIT

Support

For issues and questions, please open an issue on the GitHub repository.

FilesExpand file tree

README.md

Latest commit

History