Backend Overview

BonardaHR's backend is a Spring Boot 3 REST API backed by PostgreSQL 15 and managed with Flyway migrations. It follows a package-by-feature (domain-driven) layout, uses JWT-based stateless authentication, and integrates optionally with Microsoft Azure AD, SharePoint, and Outlook via the Microsoft Graph API.

---

Tech Stack

Layer	Technology
Language	Java 21
Framework	Spring Boot 3
Database	PostgreSQL 15+
Schema Migrations	Flyway
Auth	Azure AD OAuth2 + JWT
Microsoft Integrations	Microsoft Graph API
Build Tool	Maven (via mvnw wrapper)
Containerisation	Docker + Docker Compose

---

Project Structure

backend/
├── src/main/java/com/turntabl/backend/
│   ├── config/                # Spring Security, CORS, JWT, async config
│   ├── exception/             # GlobalExceptionHandler & custom exceptions
│   └── domain/                # Business Domain Modules (package-by-feature)
│       ├── admin/             # RBAC management & custom role admin
│       ├── common/            # Shared base entities & utilities
│       ├── dashboard/         # Dashboard aggregation metrics
│       ├── document/          # Document folders & SharePoint integration
│       ├── employee/          # Profile management, dynamic fields, CSV import
│       ├── esign/             # E-signature documents & signing requests
│       ├── event/             # Company events & regional holidays
│       ├── feedback/          # Employee surveys, performance & 1-on-1s
│       ├── notification/      # In-app notifications & email dispatcher
│       ├── onboarding/        # Onboarding templates, wizards & checklist tracking
│       ├── organization/      # Departments, offices, teams & org chart tree
│       ├── reports/           # HR metrics & Bradford Factor absenteeism engine
│       ├── timeoff/           # Leave policies, balances, accruals & approvals
│       ├── timesheet/         # Clock in/out & weekly timesheet submissions
│       └── workflow/          # Automated HR workflow engine & oversight
├── src/main/resources/
│   ├── application.yml        # Central configuration
│   └── db/migration/          # Flyway SQL migrations (V1–V19+)
├── Dockerfile                 # Multi-stage production build
├── docker-compose.dev.yml     # Local PostgreSQL + pgAdmin
└── pom.xml

---

Quick Start

1. Start PostgreSQL

docker-compose -f docker-compose.dev.yml up -d

This spins up a local PostgreSQL container on port 5432 and a pgAdmin UI.

2. Configure the backend

cp .env.example .env
# Edit .env with your DB credentials and JWT secret

3. Run the backend

./mvnw spring-boot:run
# Server starts at http://localhost:8081

The backend runs with spring.profiles.active=dev by default, which automatically seeds 10 sample employees, leave types, balances, and time-off requests via DevDataSeeder.

4. Run the frontend

cd ../frontend
npm install
npm run dev
# Starts at http://localhost:5173

---

Dev Login

In dev mode, the login page shows a dropdown of pre-seeded employees. Select one and click login — no password required. Each employee has a different role:

Employee	Role	Capabilities
Amara Osei (CEO)	ADMIN	Full access to everything
Esi Adjei (HR Manager)	HR_MANAGER	Manage all employees and time off
Kofi Boateng (Head of Engineering)	MANAGER	Approve team requests, view team
Yaw Asante (Software Engineer 3)	EMPLOYEE	View own profile, request time off

info

No Azure AD credentials are required in dev mode. See Microsoft Integration for production SSO setup.

---

Key Architecture Patterns

Dual-Identifier Pattern

Every entity has:

• An internal BIGSERIAL id — used for foreign keys, joins, and JWT subject claims. Never exposed via the API.
• A UUID public_id — the only identifier returned to clients.

The mapping boundary is the service layer. See ADR-012 for rationale.

Configurable Employee Sections

Employee profiles combine fixed columns (name, email, hire date) with dynamic JSONB-backed sections (payroll, emergency contacts, personal interests). Section field definitions live in employee_sections + section_fields; values in employee_field_values. See ADR-001.

Time Off Workflow

Requests follow a lifecycle: PENDING → APPROVED / REJECTED / CANCELLED. Balance counters (pending, used) are denormalized for O(1) reads and kept in sync across create, review, and cancel operations. Reviews use pessimistic locking to prevent double-approval races. See ADR-013.

Hierarchical Reporting

Self-referencing reports_to_id with circular reference prevention. The buildHierarchy method in EmployeeServiceImpl fetches the full employee list and builds the org tree in-memory — O(n) per level, acceptable for typical structures (3–5 levels deep).

Bradford Factor Analytics

HR metrics dashboard includes the Bradford Factor (S² × D) for measuring absenteeism impact. Risk thresholds (LOW / MEDIUM / HIGH / CRITICAL) are admin-configurable. See ADR-026 for details.

Roles & Permissions Admin

Admins can create/edit/delete custom roles and assign permissions from the /admin page. The five default roles (ADMIN, IT_MANAGER, HR_MANAGER, MANAGER, EMPLOYEE) are protected from deletion.

Admin API endpoints:

Endpoint	Permission	Description
GET /api/v1/admin/roles	ROLE_READ	List all roles with permissions
POST /api/v1/admin/roles	ROLE_CREATE	Create a new role
PUT /api/v1/admin/roles/{id}	ROLE_UPDATE	Update role name/description/permissions
DELETE /api/v1/admin/roles/{id}	ROLE_DELETE	Delete a custom role
GET /api/v1/admin/permissions	ROLE_READ	List all permissions
GET /api/v1/admin/employees/{id}/roles	ROLE_READ	Get an employee's roles
PUT /api/v1/admin/employees/{id}/roles	ROLE_ASSIGN	Set an employee's roles

Microsoft Integrations

All Microsoft integrations are optional — the app works fully in dev mode without any Azure credentials.

Integration	Purpose	Dev Mode
Azure AD SSO	"Sign in with Microsoft" button	Dev login dropdown (no SSO button)
SharePoint	Document browsing, upload, preview	Mock service returns realistic fake data
Calendar Sync	Sync approved time-off to Outlook	Events logged to console

---

Development Commands

Backend

./mvnw spring-boot:run      # Run with dev profile
./mvnw compile -q           # Quick compile check
./mvnw test                 # Run all tests
./mvnw clean package        # Production build (JAR)

Database Migrations

Schema changes are managed with Flyway and run automatically on startup.

src/main/resources/db/migration/
├── V1__create_employee_tables.sql          # Core schema: employees, roles, permissions, sections, audit
├── V2__create_time_off_tables.sql          # Time off types, balances, requests, unlimited leave
├── V3__create_timesheet_tables.sql         # Weekly timesheets with approval workflow
├── V4__create_departments_and_positions.sql # Departments and positions tables
├── V5__create_document_tables.sql          # Document management with signatures
├── V6__create_company_events.sql           # Company-wide events
├── V7__create_sites.sql                    # Site/location management
├── V11__add_reports_feature.sql            # Bradford Factor flag, REPORT_READ permission
├── V12__add_reports_indexes.sql            # Performance indexes for reports
└── V13__add_bradford_settings.sql          # Configurable Bradford thresholds

caution

Never modify an existing migration. Always create a new V{next}__description.sql file.

---

Further Reading

Document	Description
Architecture	Package layout, security, request flow diagram
Domain Modules	Detailed breakdown of each domain package
Database Schema	Full table reference, ERD, and migration history
HR Workflows	Time-off, timesheet, document signing, and lifecycle workflows
ADRs	All 26 architectural decision records
Microsoft Integration	Azure AD SSO, SharePoint, and Outlook Calendar setup
Database Review	Schema review findings and recommendations