hrplatformbackend-d8c5zs/README.md

HR Platform Backend

A comprehensive HR platform backend built with FastAPI and SQLite, providing employee management, authentication, and category-based search functionality.

Features

• Authentication & Authorization: JWT-based authentication system with user roles
• Employee Management: Complete CRUD operations for employees
• Department Management: Organize employees by departments
• Job Title Management: Manage job positions and titles
• Category-Based Search: Advanced search functionality by skills, categories, departments, and more
• OpenAPI Documentation: Interactive API documentation with Swagger UI and ReDoc
• Health Check Endpoint: Monitor the health of the API and database

Tech Stack

• Framework: FastAPI
• Database: SQLite
• ORM: SQLAlchemy
• Migrations: Alembic
• Authentication: JWT (JSON Web Tokens)
• API Documentation: OpenAPI (Swagger and ReDoc)

Project Structure

.
├── alembic.ini              # Alembic configuration
├── app                      # Main application package
│   ├── api                  # API endpoints
│   │   ├── deps.py          # API dependencies
│   │   ├── routes.py        # API router
│   │   └── v1               # API version 1 endpoints
│   ├── core                 # Core application modules
│   │   ├── config.py        # Application configuration
│   │   └── security.py      # Security utilities
│   ├── crud                 # CRUD operations
│   ├── db                   # Database setup
│   │   ├── base.py          # Base models import
│   │   ├── base_class.py    # Base model class
│   │   ├── init_db.py       # Database initialization
│   │   └── session.py       # Database session
│   ├── models               # SQLAlchemy models
│   └── schemas              # Pydantic schemas
├── main.py                  # Application entry point
├── migrations               # Alembic migrations
│   ├── env.py               # Migration environment
│   ├── script.py.mako       # Migration script template
│   └── versions             # Migration versions
├── openapi.json             # Generated OpenAPI schema
├── openapi_schema.py        # Script to generate OpenAPI schema
├── requirements.txt         # Python dependencies
└── run_migrations.py        # Helper script for running Alembic migrations

Getting Started

Prerequisites

• Python 3.8 or higher
• pip (Python package installer)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd hrplatformbackend
   

2. Install the dependencies:

   pip install -r requirements.txt
   

3. Set environment variables (optional, defaults are provided):

   export SECRET_KEY="your-secret-key"
   export FIRST_SUPERUSER="admin@example.com"
   export FIRST_SUPERUSER_PASSWORD="admin123"
   

Running Migrations

Run Alembic migrations to set up the database schema using the provided script:

python run_migrations.py upgrade head

Alternatively, if you need to create a new migration:

python run_migrations.py revision --autogenerate -m "description"

Running the Application

Start the FastAPI server:

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

The API will be available at http://localhost:8000

Running with Docker

You can also run the application using Docker:

# Build the Docker image
docker build -t hrplatform-backend .

# Run the container
docker run -p 8000:8000 -e DATABASE_PATH=/app/storage/db/db.sqlite hrplatform-backend

For production deployments, make sure to set the necessary environment variables:

docker run -p 8000:8000 \
  -e SECRET_KEY="your-secure-key" \
  -e FIRST_SUPERUSER="admin@yourdomain.com" \
  -e FIRST_SUPERUSER_PASSWORD="secure-password" \
  -e DATABASE_PATH="/app/storage/db/db.sqlite" \
  -v /host/path/to/data:/app/storage \
  hrplatform-backend

API Documentation

Once the server is running, you can access the interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

Usage

Authentication

1. Register a new user:

   curl -X POST "http://localhost:8000/api/v1/auth/register" \
     -H "Content-Type: application/json" \
     -d '{"email": "user@example.com", "password": "password123", "full_name": "Example User"}'
   

2. Login to get access token:

   curl -X POST "http://localhost:8000/api/v1/auth/login" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "username=user@example.com&password=password123"
   

3. Use the token for authenticated requests:

   curl -X GET "http://localhost:8000/api/v1/users/me" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
   

Employee Management

1. Create a new employee:

   curl -X POST "http://localhost:8000/api/v1/employees/" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "first_name": "John",
       "last_name": "Doe",
       "email": "john.doe@example.com",
       "hire_date": "2023-01-15",
       "department_id": "department_id_here",
       "job_title_id": "job_title_id_here"
     }'
   

2. Search employees by category:

   curl -X GET "http://localhost:8000/api/v1/employees/search/?categories=IT&skills=Python&department_id=dept_id" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
   

Environment Variables

Variable	Description	Default Value
PROJECT_NAME	Name of the project	HR Platform API
SECRET_KEY	Secret key for JWT encoding	Auto-generated
ACCESS_TOKEN_EXPIRE_MINUTES	JWT token expiration time in minutes	11520 (8 days)
FIRST_SUPERUSER	Email for the initial admin user	admin@example.com
FIRST_SUPERUSER_PASSWORD	Password for the initial admin user	admin123
DATABASE_PATH	Path to the SQLite database file	Auto-detected with fallbacks

The application will automatically try the following paths for the database (in order):

1. Path specified in the DATABASE_PATH environment variable (if set)
2. /app/storage/db/db.sqlite (standard Docker container path)
3. /tmp/hrplatform/db/db.sqlite (fallback for limited permissions)
4. ./db/db.sqlite (relative to the current working directory)

This makes the application work reliably in different environments, including Docker containers, without requiring manual configuration.

License

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