HR Management API

A modern, scalable HR Management System built with .NET 9 following Clean Architecture principles. This API provides comprehensive employee and department management capabilities with JWT authentication and PostgreSQL persistence.

🌟 Features

• Employee Management: Create, read, update, and delete employee records with department association
• Department Management: Manage organizational departments and structures
• User Authentication: Secure JWT-based authentication and authorization
• Pagination: Efficient data retrieval with paginated responses
• API Documentation: Interactive OpenAPI/Swagger UI for API exploration
• Structured Logging: Comprehensive logging with Serilog
• Health Checks: Built-in health check endpoints for monitoring
• Docker Support: Containerized deployment with Docker and Docker Compose
• Database Migrations: EF Core migrations with PostgreSQL

🏗️ Architecture

This project follows Clean Architecture principles with clear separation of concerns:

src/
├── HrManagement.Domain/           # Core business logic & entities
│   ├── Entities/                  # Domain entities (Employee, Department, User)
│   ├── Repositories/              # Repository interfaces
│   ├── Services/                  # Domain services
│   └── Errors/                    # Custom error definitions
├── HrManagement.Application/      # Application use cases & DTOs
│   ├── UseCases/                  # Application services
│   ├── Dtos/                      # Data Transfer Objects
│   ├── Mapping/                   # Entity-to-DTO mappings
│   └── ApplicationModule.cs       # DI configuration
├── HrManagement.Infrastructure/   # External services & database
│   ├── Persistence/               # EF Core DbContext & Repositories
│   ├── Migrations/                # Database migrations
│   ├── Services/                  # Infrastructure services
│   └── InfrastructureModule.cs    # DI configuration
├── HrManagement.Presentation/     # API controllers & middleware
│   ├── Controllers/               # API endpoints
│   ├── Program.cs                 # Application startup
│   └── Properties/                # Launch settings
└── HrManagement.Shared/           # Shared utilities & helpers

tests/
└── HrManagement.Tests/            # Unit tests

Layer Responsibilities:

• Domain: Business rules, entities, and repository contracts
• Application: Use cases, DTOs, and cross-cutting concerns
• Infrastructure: Data access, external services, and EF Core configuration
• Presentation: HTTP controllers, routing, and request/response handling

🛠️ Tech Stack

• .NET 9.0 - Latest .NET runtime
• Entity Framework Core - ORM for database access
• PostgreSQL - Primary database
• JWT Bearer - Authentication & authorization
• Serilog - Structured logging
• Swagger/OpenAPI - API documentation
• Docker & Docker Compose - Containerization
• xUnit - Unit testing framework

📋 Prerequisites

• .NET 9.0 SDK or later
• PostgreSQL 15+ (or Docker for containerized setup)
• Docker & Docker Compose (optional, for containerized deployment)
• Visual Studio Code or Visual Studio 2022+ (recommended)

🚀 Getting Started

Option 1: Docker Setup (Recommended)

1. Clone the repository:

   git clone https://github.com/yourusername/HrManagement.git
   cd HrManagement

2. Build and run with Docker Compose:

   docker-compose up --build

3. Access the API:

   • API: http://localhost:5158
   • Swagger UI: http://localhost:5158/api-docs/index.html
   • PgAdmin: http://localhost:8080 (default: admin@example.com / admin)

Option 2: Local Development

1. Clone the repository:

   git clone https://github.com/yourusername/HrManagement.git
   cd HrManagement

2. Set up PostgreSQL:

   # Using Docker (single container)
   docker run --name postgres-hr -e POSTGRES_PASSWORD=admin -e POSTGRES_DB=hrmanagement -p 5432:5432 -d postgres:15

3. Configure connection string: Update appsettings.json or set environment variable:

   {
     "ConnectionStrings": {
       "DefaultConnection": "Host=localhost;Port=5432;Database=hrmanagement;Username=postgres;Password=admin"
     }
   }

4. Restore dependencies:

   dotnet restore

5. Apply migrations:

   dotnet ef database update -p src/HrManagement.Infrastructure

6. Run the application:

   dotnet run --project src/HrManagement.Presentation

7. Access the API:

   • API: http://localhost:5158
   • Swagger UI: http://localhost:5158/api-docs/index.html

📚 API Endpoints

Authentication

• POST /api/v1/auth/register - Register new user
• POST /api/v1/auth/login - Authenticate user (returns JWT token)

Employees

• GET /api/v1/employees - Get all employees (with pagination)
• GET /api/v1/employees/{id} - Get employee by ID
• POST /api/v1/employees - Create new employee
• PUT /api/v1/employees/{id} - Update employee
• DELETE /api/v1/employees/{id} - Delete employee

Departments

• GET /api/v1/departments - Get all departments
• GET /api/v1/departments/{id} - Get department by ID
• POST /api/v1/departments - Create new department
• PUT /api/v1/departments/{id} - Update department
• DELETE /api/v1/departments/{id} - Delete department

Health Check

• GET /health - Service health status

Detailed API documentation is available at http://localhost:5158/api-docs/index.html when the application is running.

🔐 Authentication

The API uses JWT (JSON Web Tokens) for authentication:

1. Obtain a token:

   curl -X POST http://localhost:5158/api/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{"username":"user","password":"password"}'

2. Use the token in requests:

   curl -H "Authorization: Bearer {token}" \
     http://localhost:5158/api/v1/employees

📊 Database Schema

Entities

Employee

• Id (Guid) - Primary key
• Name (string) - Employee name
• Email (string) - Email address
• Position (string) - Job position
• DepartmentId (Guid) - Foreign key to Department
• CreatedAt (DateTime) - Creation timestamp

Department

• Id (Guid) - Primary key
• Name (string) - Department name
• Description (string) - Department description
• CreatedAt (DateTime) - Creation timestamp

User

• Id (Guid) - Primary key
• Username (string) - Login username
• Email (string) - Email address
• PasswordHash (string) - Hashed password
• CreatedAt (DateTime) - Creation timestamp

🧪 Testing

Run unit tests:

dotnet test

Run tests with coverage:

dotnet test /p:CollectCoverageMetrics=true

📝 Project Configuration

Application Settings

appsettings.json:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=hrmanagement;Username=postgres;Password=admin"
  },
  "Jwt": {
    "Key": "your-secret-key-here-minimum-32-chars",
    "Issuer": "hr-management-api",
    "Audience": "hr-management-client",
    "ExpirationMinutes": 60
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

User Secrets (Development)

Store sensitive configuration locally:

dotnet user-secrets init -p src/HrManagement.Presentation
dotnet user-secrets set "Jwt:Key" "your-secure-secret-key-here"

🐳 Docker Configuration

Docker Compose Services

• api - .NET 9 web API (port 5158)
• db - PostgreSQL 15 database (port 5432)
• pgadmin - PostgreSQL administration (port 8080)

Build Docker Image

docker build -t hrmanagement:latest .

Run Container

docker run -p 5158:5158 \
  -e ConnectionStrings__DefaultConnection="Host=db;Port=5432;Database=hrmanagement;Username=postgres;Password=admin" \
  hrmanagement:latest

📈 Logging

The application uses Serilog for structured logging:

• Console output (development)
• Rolling file sinks (production)
• Request/response middleware logging
• Exception logging

Logs can be configured in appsettings.json under the Serilog section.

🔄 Migrations

Create a new migration:

dotnet ef migrations add MigrationName -p src/HrManagement.Infrastructure

Apply migrations:

dotnet ef database update -p src/HrManagement.Infrastructure

Remove last migration:

dotnet ef migrations remove -p src/HrManagement.Infrastructure

🤝 Contributing

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

Code Standards

• Follow C# naming conventions (PascalCase for public members)
• Use dependency injection for loose coupling
• Write unit tests for new features
• Keep methods focused and single-responsibility
• Add XML documentation comments to public methods

📋 Project Structure Guidelines

• Domain: Pure business logic, no external dependencies
• Application: Orchestration layer, DTOs, and use cases
• Infrastructure: EF Core context, repositories, migrations
• Presentation: Controllers, middleware, HTTP concerns
• Tests: Unit tests, integration tests, test fixtures

🐛 Troubleshooting

Database Connection Issues

Problem: Connection refused to PostgreSQL

• Solution: Ensure PostgreSQL is running and credentials match appsettings.json
• Docker Fix: docker-compose up db (restart database service)

Migration Failures

Problem: dotnet ef database update fails

• Solution: Delete problematic migration and recreate:

  dotnet ef migrations remove -p src/HrManagement.Infrastructure
  dotnet ef migrations add NewMigrationName -p src/HrManagement.Infrastructure

JWT Token Issues

Problem: 401 Unauthorized on protected endpoints

• Solution: Verify token is passed in Authorization header as Bearer {token}
• Check token hasn't expired (default: 60 minutes)
• Verify Jwt:Key matches between token generation and validation

Docker Compose Port Conflicts

Problem: Port already in use

• Solution: Change ports in docker-compose.yml or stop conflicting services:

  docker-compose down

📄 License

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

👥 Authors

• Emmanuel Francois - Initial work

📞 Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Contact: emmanuelnoc@gmail.com
• Documentation: Wiki

🔗 Related Resources

• .NET Documentation
• Entity Framework Core
• Clean Architecture
• JWT Introduction
• PostgreSQL Documentation

---

Last Updated: 2026
Status: Active Development