bench get-app https://github.com/itsmerizvi/najemhr

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=itsmerizvi%2Fnajemhr)](https://frappegems.com/gems/apps/itsmerizvi/najemhr)

NajemHR 📊

A modern, comprehensive HR Management System built on Frappe Framework with beautiful dashboards, KPI tracking, and employee management features.

✨ Features

🎯 Dashboard

• Live Data Visualization - Real-time stats and charts
• Task Management - Track tasks with progress indicators
• Attendance Overview - Weekly attendance charts
• KPI Tracking - Monitor key performance indicators
• Employee List - Quick access to employee profiles

👤 Employee Profile

• Comprehensive Profile Page - Beautiful employee detail view
• Quick Edit - Inline editing without leaving the page
• Stats Cards - Attendance rate, leave balance, tasks, projects
• Tabbed Interface - Overview, Attendance, Leaves, Tasks, Performance
• KPI Performance - Individual employee KPI tracking

📈 KPI System

• 8 Built-in KPI Types:
  • Attendance
  • Productivity
  • Performance
  • Recruitment
  • Retention
  • Training
  • Payroll
  • Custom (with formulas)
• Automated Calculation - Schedule KPI calculations
• Flexible Applicability - Company-wide, Department, Designation, or Individual
• Custom Formulas - Write Python expressions for complex KPIs
• Weighted Scoring - Prioritize important metrics

🎨 UI/UX

• Modern Design - Gradient backgrounds, smooth animations
• Responsive - Works on desktop, tablet, and mobile
• Professional Typography - Clean, readable interface
• Color-coded Status - Visual indicators for quick understanding
• Interactive Charts - SVG-based visualizations

🚀 Installation

Prerequisites

• Frappe Framework (v14 or v15)
• ERPNext or HRMS app
• Python 3.10+
• MariaDB 10.6+

Install via Bench

# Navigate to your bench directory
cd /path/to/frappe-bench

# Get the app
bench get-app https://github.com/itsmerizvi/najemhr.git --branch develop

# Install on your site
bench --site your-site.localhost install-app najemhr

# Migrate
bench --site your-site.localhost migrate

# Clear cache
bench --site your-site.localhost clear-cache

📖 Quick Start

1. Setup Default KPIs

bench --site your-site.localhost execute najemhr.najemhr.setup_default_kpis.setup_kpis

This creates 5 default KPI metrics: - Attendance Rate (95% target) - Task Completion Rate (90% target) - Employee Retention Rate (95% target) - Training Completion Rate (85% target) - Recruitment Efficiency (100% target)

2. Create Sample Data (Optional)

# Create employees
bench --site your-site.localhost execute najemhr.najemhr.bulk_employees.create_employees

# Create tasks and projects
bench --site your-site.localhost execute najemhr.najemhr.create_tasks_projects.main

3. Access the Dashboard

Navigate to: http://your-site.localhost/app/najem-dashboard

🎯 Usage

Dashboard

• View real-time HR metrics
• Monitor attendance trends
• Track task completion
• Review KPI performance
• Quick access to employees

Employee Profile

• Click any employee from the dashboard
• View comprehensive employee details
• Edit information inline with "Quick Edit"
• Track individual KPI performance
• Monitor attendance and leave history

KPI Management

• Create KPI Metrics: HR > KPI Metric > New
• View KPI Records: HR > KPI Record
• Calculate KPIs: Runs automatically (can be scheduled)

Custom KPI Formula Example

# In KPI Metric, set Calculation Method = "Formula"
formula = """
tasks = frappe.db.count("Task", {
    "status": "Completed",
    "employee": employee,
    "exp_end_date": ["between", [period_start, period_end]]
})
result = (tasks / 30) * 100  # Target: 30 tasks per period
"""

🏗️ Architecture

Technology Stack

• Backend: Python 3.10+ (Frappe Framework)
• Frontend: JavaScript, HTML5, CSS3
• Database: MariaDB
• Charts: SVG (custom implementation)
• UI Framework: Frappe Desk

Project Structure

najemhr/
├── najemhr/
│   ├── doctype/
│   │   ├── kpi_metric/          # KPI configuration
│   │   ├── kpi_record/          # KPI calculation results
│   │   └── performance_kpi/     # Legacy KPI (deprecated)
│   ├── page/
│   │   ├── najem_dashboard/     # Main dashboard page
│   │   └── employee_profile/    # Employee detail page
│   ├── workspace/
│   │   └── najem_hr/            # Sidebar workspace config
│   ├── kpi_calculator.py        # Core KPI calculation engine
│   ├── setup_default_kpis.py    # Default KPI setup script
│   ├── bulk_employees.py        # Test data generator
│   └── KPI_SYSTEM_README.md     # Detailed KPI documentation
├── hooks.py                      # Frappe hooks and config
├── boot.py                       # Session boot handler
└── public/
    └── image/
        └── najemhr-logo.svg     # App logo

Key Components

1. Dashboard Page (najem_dashboard)

• Real-time data fetching via whitelisted methods
• SVG chart rendering
• Responsive grid layout
• Live task, attendance, and KPI tracking

2. Employee Profile Page (employee_profile)

• Comprehensive employee view
• Inline editing with frappe.ui.Dialog
• Tabbed interface for different data types
• Permission-based access control

3. KPI Calculator (kpi_calculator.py)

• Generic calculation engine
• 8 built-in KPI types
• Custom formula execution with frappe.safe_eval
• Automated scheduling support
• Department/Designation filtering

4. Workspace Configuration

• Custom sidebar navigation
• Shortcuts to key pages
• Role-based visibility
• Apps page integration

📚 Documentation

• KPI System: See KPISYSTEMREADME.md
• API Reference: Check whitelisted methods in page .py files
• Customization: Extend doctypes and pages as needed

🤝 Contributing

This app uses pre-commit for code formatting and linting. Please install pre-commit and enable it for this repository:

cd apps/najemhr
pre-commit install

Pre-commit is configured to use the following tools: - ruff - eslint - prettier - pyupgrade

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🧪 Testing

CI/CD

This app uses GitHub Actions for CI. The following workflows are configured: - CI: Installs this app and runs unit tests on every push to develop branch - Linters: Runs Frappe Semgrep Rules and pip-audit on every pull request

Manual Testing

# Run tests
bench --site your-site.localhost run-tests --app najemhr

# Run specific test
bench --site your-site.localhost run-tests --doctype "KPI Record"

📝 Changelog

v0.0.1 (Initial Release)

• ✨ Custom dashboard with live data
• ✨ Employee profile page with inline editing
• ✨ Comprehensive KPI system (8 types)
• ✨ Beautiful UI with gradients and animations
• ✨ Workspace configuration
• ✨ Bulk data creation scripts
• 📚 Complete documentation

🔒 License

MIT License - see LICENSE for details

👨‍💻 Author

itsmerizvi - GitHub: @itsmerizvi - Email: md@codepublicist.com

🙏 Acknowledgments

• Built on Frappe Framework
• Inspired by modern HR management needs
• Designed for extensibility and customization

⭐ Support

If you find this project useful, please consider giving it a star on GitHub!