River — Helpdesk Ticket Management System

A helpdesk backend for organizing technical support requests and managing ticket workflows.

---

About

River is a helpdesk ticket management system designed to organize technical support requests, track ticket progress, and provide a foundation for role-based support workflows.

The project is being developed incrementally, starting with a secure REST API and expanding toward a complete helpdesk application.

Architecture & Workflow

_{Ticket creation workflow — from request validation to database storage.}

Current ticket creation flow

1. Receive a ticket creation request.
2. Authenticate the user using a JWT.
3. Verify that the account is active.
4. Validate the submitted ticket data.
5. Apply default values and associate the creator.
6. Save the ticket to MongoDB.
7. Return a 201 Created response.

Technology Stack

Technology	Purpose
Node.js	JavaScript runtime
Express 5	REST API and routing
TypeScript	Type-safe backend development
MongoDB	Database
JWT	Authentication
bcrypt	Password hashing
Zod	Request validation

Implemented Features

• User registration and login
• Password hashing with bcrypt
• JWT-based authentication
• Active-account verification
• Role definitions for employees, agents, and administrators
• Ticket creation with validated input
• Ticket categories and priorities
• Default ticket status and priority
• MongoDB indexes for user lookup and ticket queries

Development note: River is a work in progress. Ticket assignment, status management, and the frontend are planned but are not yet implemented.

API Overview

Base URL for local development:

http://localhost:5000

Method	Endpoint	Description
GET	/api/health	Health check
POST	/api/auth/register	Register an account
POST	/api/auth/login	Log in
GET	/api/auth/me	Get the authenticated identity
POST	/api/tickets	Create a ticket

Protected endpoints require a valid bearer token:

Authorization: Bearer <your-token>

Getting Started

Prerequisites

• Node.js and npm
• MongoDB
• Git

1. Clone the repository

git clone https://github.com/feeridev/River.git
cd River/server

2. Install dependencies

npm install

3. Configure environment variables

Copy the example environment file:

cp .env.example .env

Configure the values in .env:

PORT=5000
MONGODB_URI=mongodb://127.0.0.1:27017/river
JWT_SECRET=replace_with_a_long_random_secret

Generate a strong secret locally:

openssl rand -hex 32

Use the generated value for JWT_SECRET. Never commit your real .env file.

4. Start MongoDB

Ensure your MongoDB service is running before starting the API.

On systems using systemd:

sudo systemctl start mongod

5. Start the development server

npm run dev

The API will run at:

http://localhost:5000

6. Build for production

npm run build
npm start

Project Structure

River/
├── .gitignore
└── server/
    ├── scripts/
    ├── src/
    │   ├── config/
    │   ├── middleware/
    │   ├── models/
    │   ├── repositories/
    │   ├── routes/
    │   ├── services/
    │   ├── utils/
    │   ├── validation/
    │   ├── app.ts
    │   └── server.ts
    ├── .env.example
    ├── package.json
    └── tsconfig.json

Roadmap

• Ticket listing and filtering
• Ticket assignment to support agents
• Ticket status updates and resolution
• Role-based authorization for helpdesk operations
• Ticket history and comments
• Automated tests
• React and TypeScript frontend
• Deployment and installation documentation

Development Philosophy

River is built step by step, with an emphasis on understanding the implementation, validating inputs, protecting user accounts, and keeping the codebase maintainable.

The goal is to build a practical helpdesk system while documenting the engineering decisions and development process along the way.

Author

Farshad Safarkhanloo

• GitHub: @feeridev

---

_{River is an independent portfolio project and is actively being developed.}