sodheroes

HRMS — Human Resource Management System

A full-stack web application built with React (frontend), Express.js (backend API), and MySQL (database).

📋 Requirements

• Node.js >= 16
• MySQL server running on localhost:3306 (or a remote server)
• npm (comes with Node.js)

🚀 Quick Install (Automatic)

npm install sodheroes

That's it. The installation will automatically:

1. ✅ Install all backend dependencies
2. ✅ Install all frontend dependencies
3. ✅ Create a default .env configuration file
4. ✅ Create the database and tables
5. ✅ Seed the database with sample data (22 employees, 7 departments, 8 positions, 8 users)

If seeding fails (e.g., MySQL not running), the error will show. Fix your database credentials and run:

npx sodheroes seed

▶️ Running the App

Start both servers (backend + frontend):

npx sodheroes start

• Backend API: http://localhost:5000
• Frontend UI: http://localhost:3000

Start individually:

npx sodheroes start:backend    # API server only (port 5000)
npx sodheroes start:frontend   # React app only (port 3000)

📖 Commands

| Command | Description | |---------|-------------| | npx sodheroes install | Install dependencies + seed database | | npx sodheroes seed | Seed the database with sample data | | npx sodheroes start | Start both backend and frontend | | npx sodheroes start:backend | Start only the backend API | | npx sodheroes start:frontend | Start only the React frontend | | npx sodheroes help | Show help information |

🔐 Default Login

| Username | Password | |----------|----------| | admin | password123 | | janesmith | password123 | | peterkamau | password123 | | alicemukamana | password123 | | davidhabimana | password123 | | jamesmuhire | password123 | | sarahineza | password123 | | emilymukeshi | password123 |

⚙️ Configuration

Edit backend/.env to configure your database and email settings:

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=
DB_NAME=hrms
DB_PORT=3306
SESSION_SECRET=hrms_secret_key_2026
PORT=5000
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
[email protected]
EMAIL_PASS=your_app_password

If .env does not exist after installation, create one manually or re-run:

npx sodheroes install

🗄️ Database Schema

| Table | Description | |-------|-------------| | department | Departments (HR, Finance, Sales, etc.) | | positions | Job positions with required qualifications | | employee | Employee records with status tracking | | users | System login credentials linked to employees |

Employee statuses: Active, On leave, Left, Blacklisted, Deceased, On mission

📁 Project Structure

node_modules/sodheroes/
├── bin/sodheroes                     # CLI entry point
├── FirstName_LastName_National_Practical_Exam_2026/
│   ├── backend/
│   │   ├── server.js                # Express API server
│   │   ├── .env                     # Configuration
│   │   ├── config/db.js             # MySQL connection pool
│   │   ├── db/
│   │   │   ├── init.sql             # Database schema
│   │   │   └── seed.js              # Data seeder
│   │   ├── middleware/auth.js       # Authentication middleware
│   │   └── routes/
│   │       ├── auth.js              # Login, signup, password reset
│   │       ├── employees.js         # Employee CRUD + reports
│   │       ├── departments.js       # Department CRUD
│   │       └── positions.js         # Position CRUD
│   └── frontend/
│       ├── src/
│       │   ├── App.js               # React app with routes
│       │   ├── api/axios.js         # API client config
│       │   ├── context/AuthContext.js
│       │   ├── components/          # Layout, Navbar, Sidebar
│       │   └── pages/               # Dashboard, Employees, etc.
│       ├── public/
│       └── package.json
└── package.json                     # Package manifest

❓ Troubleshooting

Seeding fails with "ECONNREFUSED" → Make sure MySQL is running. Check credentials in backend/.env.

Port already in use → Change PORT in backend/.env (backend) or the frontend will use port 3001 automatically.

"react-scripts: command not found" → Run npx sodheroes install to install frontend dependencies.

Forgot password flow uses email? → Configure EMAIL_* settings in backend/.env with valid SMTP credentials.

📄 License

MIT