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:
   ```bash
   pip install -r requirements.txt
   ```

## Running the Application

Start the FastAPI server with uvicorn:
```bash
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
```bash
ruff check . --fix
```

### Database Migrations
The initial migration is included. For new migrations:
```bash
# 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.