Job Card Management System

A comprehensive web application for managing job cards, vehicles/machinery, and issued materials for maintenance operations. Built for Edward and Christie to streamline their vehicle and machinery maintenance workflow.

📋 Table of Contents

Features
Technology Stack
Requirements
Installation
Usage
Project Structure
API Endpoints
Database Schema
Screenshots
License

✨ Features

🚗 Vehicle/Machinery Management

Add, edit, delete vehicles and machinery
Import from CSV/Excel files
Export to Excel
Search and filter functionality

📦 Material Management

MRN Items - Issued Materials tracking
Lubricants - Oils, grease, hydraulic fluids
Common Items - General/Special items
Filters - Fuel, air, hydraulic filters
Auto-categorization during import
Import/Export functionality
Status tracking (Pending/In Job Card)

⚡ Auto-Generate Job Cards

One-click bulk generation - Create job cards for ALL pending materials instantly
Selective generation - Choose specific vehicles
Auto-grouping - Materials automatically grouped by vehicle/project
Time-saving workflow - Seconds instead of hours!

📄 Job Card Management

Create job cards manually or auto-generate
Add job details (driver, supervisor, dates, costs)
Track status: Draft → In Progress → Completed
Cost calculation (spare parts, manpower, outside works)
Print functionality

📊 Dashboard

Statistics overview
Pending materials alert
Quick actions
Recent job cards

🛠 Technology Stack

Category	Technology
Framework	Next.js 16 (App Router)
Language	TypeScript 5
Database	SQLite with Prisma ORM
Styling	Tailwind CSS 4
UI Components	shadcn/ui
Icons	Lucide React
Notifications	Sonner
Excel Processing	xlsx

💻 Requirements

Minimum Requirements

Node.js: v18.17 or higher
Package Manager: Bun (recommended) or npm/yarn/pnpm
RAM: 512MB minimum
Storage: 100MB for application
Browser: Modern browser (Chrome, Firefox, Safari, Edge)

📥 Installation

Windows

Step 1: Install Prerequisites

Install Node.js (v18+)

# Download from https://nodejs.org/ or use winget
winget install OpenJS.NodeJS.LTS

Install Bun (recommended) or use npm

# Install Bun
powershell -c "irm bun.sh/install.ps1 | iex"

# Or npm comes with Node.js

Install Git
```
winget install Git.Git
```

Step 2: Clone and Setup

# Clone the repository
git clone https://github.com/yohan114/Job-Card-Management-System.git
cd Job-Card-Management-System

# Install dependencies
bun install
# Or: npm install

# Setup database
bun run db:push
# Or: npm run db:push

# Start development server
bun run dev
# Or: npm run dev

Step 3: Access Application

Open browser and go to: http://localhost:3000

macOS

Step 1: Install Prerequisites

Install Homebrew (if not installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Node.js
```
brew install node
```

Install Bun (recommended)

curl -fsSL https://bun.sh/install | bash
source ~/.bashrc  # or ~/.zshrc

Install Git
```
brew install git
```

Step 2: Clone and Setup

# Clone the repository
git clone https://github.com/yohan114/Job-Card-Management-System.git
cd Job-Card-Management-System

# Install dependencies
bun install
# Or: npm install

# Setup database
bun run db:push
# Or: npm run db:push

# Start development server
bun run dev
# Or: npm run dev

Step 3: Access Application

Open browser and go to: http://localhost:3000

Ubuntu Server

Step 1: Install Prerequisites

# Update system
sudo apt update && sudo apt upgrade -y

# Install Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Install Bun
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

# Install Git
sudo apt install -y git

# Install build tools (for native modules)
sudo apt install -y build-essential python3

Step 2: Clone and Setup

Quick Setup (Recommended):

# Clone the repository
git clone https://github.com/yohan114/Job-Card-Management-System.git
cd Job-Card-Management-System

# Run the setup script (automates all setup steps)
chmod +x setup.sh
./setup.sh

Manual Setup:

# Clone the repository
git clone https://github.com/yohan114/Job-Card-Management-System.git
cd Job-Card-Management-System

# Install dependencies
bun install
# Or: npm install

# Create database directory
mkdir -p db

# Setup database (IMPORTANT: This creates the database file)
bun run db:push
# Or: npm run db:push

# Verify database was created
ls -la db/custom.db

# If database doesn't exist, run again:
bun run db:generate && bun run db:push

Step 3: Production Setup (PM2)

# Install PM2 globally
sudo npm install -g pm2

# Generate Prisma client and build the application
bun run db:generate
bun run build
# Or: npm run build

# Start with PM2
pm2 start npm --name "job-card-system" -- start

# Save PM2 configuration
pm2 save

# Setup PM2 to start on boot
pm2 startup

Troubleshooting Ubuntu Server

If data is not saving:

# 1. Check if database file exists
ls -la db/custom.db

# 2. Check file permissions
chmod 664 db/custom.db
chmod 775 db

# 3. Regenerate Prisma client
bun run db:generate

# 4. Push database schema again
bun run db:push

# 5. Restart the application
pm2 restart job-card-system

# 6. Check logs for errors
pm2 logs job-card-system

Database connection issues:

# Verify .env file has correct path
cat .env
# Should show: DATABASE_URL="file:./db/custom.db"

# If .env is missing, create it:
echo 'DATABASE_URL="file:./db/custom.db"' > .env

# Then rebuild
bun run db:generate
bun run db:push

Step 4: Configure Firewall (Optional)

# Allow port 3000
sudo ufw allow 3000

# Or use nginx as reverse proxy
sudo apt install nginx
sudo nano /etc/nginx/sites-available/job-card-system

Nginx Configuration:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

# Enable site
sudo ln -s /etc/nginx/sites-available/job-card-system /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

🚀 Usage

Initial Setup

Start the application
```
bun run dev
```
Import Data
- Go to Vehicles tab → Click Import → Select your vehicle list (CSV/Excel)
- Go to MRN Items tab → Click Import → Select your materials list (Excel)
Generate Job Cards
- Click Auto Generate button in header
- Review pending materials by vehicle
- Click Generate ALL Job Cards or select specific vehicles

File Format for Import

Vehicles/CSV Format:

NO	E&C NO	BRAND	TYPE	MODEL NO	REGISTRATION NO	CAPACITY	YOM
1	LB-01	JCB	Backhoe Loader	3DX	ZA-2609	1.0 cu. m.	2012

Materials/Excel Format:

Date	MRN No.	Description	Unit	Qty	Vehicle / Project	Remark	Price	Total
15/12/25	141401	Fan belt	Nos	2	VR-71	As per sample

Categories Auto-Detected:

MRN Items: Default category
Lubricants: Items containing "oil", "grease", "hydraulic fluid"
Common Items: Items containing "bolt", "nut", "washer", "seal", "bearing"
Filters: Items containing "filter"

📁 Project Structure

job-card-management-system/
├── prisma/
│   └── schema.prisma          # Database schema
├── public/                     # Static files
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── machines/       # Machine CRUD APIs
│   │   │   ├── materials/      # Material CRUD APIs
│   │   │   └── job-cards/      # Job Card APIs
│   │   ├── globals.css         # Global styles
│   │   ├── layout.tsx          # Root layout
│   │   └── page.tsx            # Main application
│   ├── components/ui/          # shadcn/ui components
│   ├── hooks/                  # Custom React hooks
│   └── lib/
│       ├── db.ts               # Prisma client
│       └── utils.ts            # Utility functions
├── db/
│   └── custom.db               # SQLite database
├── package.json
├── tailwind.config.ts
├── tsconfig.json
└── README.md

🔌 API Endpoints

Machines

Method	Endpoint	Description
GET	`/api/machines`	List all machines
POST	`/api/machines/create`	Create new machine
GET	`/api/machines/[id]`	Get machine details
PUT	`/api/machines/[id]`	Update machine
DELETE	`/api/machines/[id]`	Delete machine
POST	`/api/machines/import`	Import from CSV/Excel
GET	`/api/machines/export`	Export to Excel

Materials

Method	Endpoint	Description
GET	`/api/materials`	List materials (filterable)
POST	`/api/materials/create`	Create new material
GET	`/api/materials/[id]`	Get material details
PUT	`/api/materials/[id]`	Update material
DELETE	`/api/materials/[id]`	Delete material
POST	`/api/materials/import`	Import from Excel
GET	`/api/materials/export`	Export to Excel

Job Cards

Method	Endpoint	Description
GET	`/api/job-cards`	List job cards
POST	`/api/job-cards`	Create job card
GET	`/api/job-cards/[id]`	Get job card details
PUT	`/api/job-cards/[id]`	Update job card
DELETE	`/api/job-cards/[id]`	Delete job card
GET	`/api/job-cards/auto-generate`	Auto-generate ALL
POST	`/api/job-cards/auto-generate`	Auto-generate selected

🗄 Database Schema

Machine

- id: Int (Auto-increment)
- ecNo: String (E&C Code)
- brand: String
- type: String
- modelNo: String
- registrationNo: String (Unique)
- capacity: String
- yom: Int (Year of Manufacture)

IssuedMaterial

- id: Int
- date: DateTime
- mrnNo: String (MRN Number)
- description: String
- unit: String
- qty: Int
- vehicleProject: String
- remark: String
- price: Float
- total: Float
- category: Enum (MRN_ITEM, LUBRICANT, COMMON_ITEM, FILTER)
- isUsed: Boolean

JobCard

- id: Int
- jobCardNo: String (Unique - e.g., JC-2026-0001)
- vehicleRegNo: String
- companyCode: String
- vehicleMachineryMeter: Float
- repairType: String
- expectedCompletionDate: DateTime
- driverOperatorName: String
- driverOperatorContact: String
- bcdNo: String
- jobDescription: String
- jobStartDate: DateTime
- jobCompletedDate: DateTime
- supervisorName: String
- totalSparePartsCost: Float
- totalManpowerCost: Float
- outsideWorkCost: Float
- status: Enum (DRAFT, IN_PROGRESS, COMPLETED, CANCELLED)

🔧 Environment Variables

Create a .env file in the root directory:

# Database
DATABASE_URL="file:./db/custom.db"

📸 Screenshots

Dashboard

Auto Generate

Job Card List

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📝 License

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

👤 Author

Yohan

GitHub: @yohan114

🙏 Acknowledgments

📞 Support

For support, please open an issue on GitHub or contact the development team.

Document No.: EC40.WS.FO.3:4:22.10 Company: Edward and Christie

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.zscripts		.zscripts
db		db
docs		docs
download		download
examples/websocket		examples/websocket
mini-services		mini-services
prisma		prisma
public		public
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Caddyfile		Caddyfile
LICENSE		LICENSE
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package.json		package.json
postcss.config.mjs		postcss.config.mjs
push-to-github.sh		push-to-github.sh
setup.sh		setup.sh
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Job Card Management System

📋 Table of Contents

✨ Features

🚗 Vehicle/Machinery Management

📦 Material Management

⚡ Auto-Generate Job Cards

📄 Job Card Management

📊 Dashboard

🛠 Technology Stack

💻 Requirements

Minimum Requirements

Recommended

📥 Installation

Windows

Step 1: Install Prerequisites

Step 2: Clone and Setup

Step 3: Access Application

macOS

Step 1: Install Prerequisites

Step 2: Clone and Setup

Step 3: Access Application

Ubuntu Server

Step 1: Install Prerequisites

Step 2: Clone and Setup

Step 3: Production Setup (PM2)

Troubleshooting Ubuntu Server

Step 4: Configure Firewall (Optional)

🚀 Usage

Initial Setup

File Format for Import

Vehicles/CSV Format:

Materials/Excel Format:

Categories Auto-Detected:

📁 Project Structure

🔌 API Endpoints

Machines

Materials

Job Cards

🗄 Database Schema

Machine

IssuedMaterial

JobCard

🔧 Environment Variables

📸 Screenshots

Dashboard

Auto Generate

Job Card List

🤝 Contributing

📝 License

👤 Author

🙏 Acknowledgments

📞 Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages