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:
   ```bash
   git clone <repository-url>
   cd hrplatformbackend
   ```

2. Install the dependencies:
   ```bash
   pip install -r requirements.txt
   ```

3. Set environment variables (optional, defaults are provided):
   ```bash
   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:

```bash
python run_migrations.py upgrade head
```

Alternatively, if you need to create a new migration:

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

### Running the Application

Start the FastAPI server:

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

The API will be available at [http://localhost:8000](http://localhost:8000)

### Running with Docker

You can also run the application using Docker:

```bash
# 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:

```bash
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](http://localhost:8000/docs)
- ReDoc: [http://localhost:8000/redoc](http://localhost:8000/redoc)
- OpenAPI JSON: [http://localhost:8000/openapi.json](http://localhost:8000/openapi.json)

## Usage

### Authentication

1. Register a new user:
   ```bash
   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:
   ```bash
   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:
   ```bash
   curl -X GET "http://localhost:8000/api/v1/users/me" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
   ```

### Employee Management

1. Create a new employee:
   ```bash
   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:
   ```bash
   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.