hrmanagementbackendservice-ehtfn4/README.md

HR Management Backend Service

A comprehensive HR management backend system built with FastAPI, providing APIs for managing employees, departments, leave requests, payroll, and attendance tracking.

Features

• User Authentication: JWT-based authentication with role-based access control
• Employee Management: Complete employee profile management with hierarchical permissions
• Department Management: Create and manage company departments with managers
• Leave Management: Employee leave request system with approval workflow
• Payroll Management: Payroll processing with overtime, bonuses, and deductions
• Attendance Tracking: Clock in/out system with hours calculation
• Role-Based Access: Admin, HR Manager, Manager, and Employee roles with appropriate permissions

Tech Stack

• FastAPI: Modern, fast web framework for building APIs
• SQLAlchemy: SQL toolkit and ORM
• SQLite: Lightweight database for data storage
• Alembic: Database migration tool
• JWT: Token-based authentication
• Pydantic: Data validation using Python type annotations
• Ruff: Fast Python linter and formatter

Project Structure

├── app/
│   ├── core/           # Core functionality (security, dependencies)
│   ├── db/             # Database configuration and session management
│   ├── models/         # SQLAlchemy database models
│   ├── routers/        # API route handlers
│   ├── schemas/        # Pydantic schemas for request/response
│   └── services/       # Business logic services
├── migrations/         # Alembic database migrations
├── main.py            # FastAPI application entry point
├── requirements.txt   # Python dependencies
└── alembic.ini       # Alembic configuration

Installation

1. Clone the repository
2. Install dependencies:

   pip install -r requirements.txt
   

Running the Application

Start the FastAPI server with uvicorn:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

The API will be available at:

• Base URL: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• Alternative Docs: http://localhost:8000/redoc
• Health Check: http://localhost:8000/health

Environment Variables

The following environment variables should be set for production:

• SECRET_KEY: JWT secret key for token signing (default: "your-secret-key-change-in-production")

API Endpoints

Authentication

• POST /auth/register - Register a new user
• POST /auth/login - Login and get access token
• GET /auth/me - Get current user information

Employees

• POST /employees - Create employee profile
• GET /employees - List all employees
• GET /employees/{id} - Get employee by ID
• PUT /employees/{id} - Update employee
• DELETE /employees/{id} - Delete employee

Departments

• POST /departments - Create department
• GET /departments - List departments
• GET /departments/{id} - Get department by ID
• PUT /departments/{id} - Update department
• DELETE /departments/{id} - Delete department

Leave Management

• POST /leaves - Create leave request
• GET /leaves - List leave requests
• GET /leaves/{id} - Get leave request by ID
• PUT /leaves/{id}/approve - Approve/reject leave request
• PUT /leaves/{id} - Update leave request
• DELETE /leaves/{id} - Delete leave request

Payroll

• POST /payroll - Create payroll record
• GET /payroll - List payroll records
• GET /payroll/{id} - Get payroll record by ID
• PUT /payroll/{id} - Update payroll record
• POST /payroll/{id}/process - Process payroll record
• DELETE /payroll/{id} - Delete payroll record

Attendance

• POST /attendance - Create attendance record
• GET /attendance - List attendance records
• GET /attendance/{id} - Get attendance record by ID
• PUT /attendance/{id} - Update attendance record
• POST /attendance/{id}/clock-out - Clock out from attendance record
• DELETE /attendance/{id} - Delete attendance record

User Roles

Admin

• Full access to all system features
• Can manage all users, employees, departments
• Can view and process all payroll records
• Can delete any records

HR Manager

• Can manage employees and departments
• Can view and approve leave requests
• Can create and process payroll records
• Can view all attendance records

Manager

• Can view employees in their department
• Can approve leave requests for their department
• Can view attendance records for their team

Employee

• Can view and update their own profile
• Can create and manage their own leave requests
• Can view their own payroll records
• Can create and update their own attendance records

Database

The application uses SQLite database with the following main tables:

• users - User accounts and authentication
• employees - Employee profiles and information
• departments - Company departments
• leave_requests - Leave request records
• payroll_records - Payroll and salary information
• attendance_records - Daily attendance tracking

Database files are stored in /app/storage/db/ directory.

Development

Running Linter

ruff check . --fix

Database Migrations

The initial migration is included. For new migrations:

# Create a new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

Authentication

The API uses JWT (JSON Web Tokens) for authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Error Handling

The API returns appropriate HTTP status codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 422 - Validation Error

License

This project is proprietary software for HR management purposes.