📘 Employee Work Intelligence & Management System

A production-grade, API-first Spring Boot backend designed to give managers structured visibility into employee work, hierarchy, and productivity patterns — built on clean architecture, transactional integrity, auditability, and ethical AI-assisted summaries.

---

🚩 Problem Statement

In medium to large organizations, managers often lack clear, structured visibility into:

• Who is working under whom
• What employees are actively working on
• How work progresses over time
• Whether employees are overloaded or inactive
• When risks or delays are emerging

Most existing tools either become heavy project-management systems (Jira-like), rely on invasive tracking (real-time monitoring, GPS, screenshots), or lack auditability and accountability.

This project fills that gap — a lightweight, ethical, backend-driven system that delivers managerial intelligence, not surveillance.

---

✅ What This Project Solves

Capability	Description
Hierarchy Clarity	Transparent employee → manager mapping with validation
Work Logging	Structured, time-based activity logging (no real-time tracking)
Weekly Aggregation	Daily & weekly work summaries per employee and per team
Managerial Insights	Detects inactivity, overload, and long-running tasks
AI Summaries	Converts backend facts into human-readable text (explain only)
Audit Trail	Immutable, append-only logs of every critical action

---

🧠 How the System Works

1. Hierarchical Modeling

Employees are explicitly assigned to managers through a controlled endpoint. The system validates role correctness, prevents self-assignment, and blocks circular hierarchies — all within a single transaction.

2. Structured Work Logging

Employees log what they worked on, when, and what type of work it was. There is no real-time tracking and no micromanagement. Work types are categorized as FEATURE, BUG, RESEARCH, or SUPPORT.

3. Time-Based Intelligence

The backend aggregates work logs on a daily and weekly basis. This aggregation is what powers detection of inactivity, overload, and long-running tasks — all server-side, no client polling required.

4. AI as an Explainer — Not a Decision Maker

The AI layer receives structured, factual data generated by the backend and converts it into plain-English summaries. It makes zero decisions. The AI boundary is clean: structured data → prompt → text output. This layer is isolated and designed to be swapped with any real AI API when needed.

5. Audit & Accountability

Every important mutation — employee creation, manager assignment, work log creation — is recorded in an append-only audit log that captures who did it, what changed, and when.

---

🏗️ Architecture Overview

Controller  →  Service  →  Repository
                  ↓
           Domain Business Logic
                  ↓
       Audit Logging & AI Explanation Layers

Layer	Responsibility
Controller	API contracts — request/response only
Service	Business rules, transactions, orchestration
Repository	Persistence via Spring Data JPA
Audit Layer	Append-only action logging (cross-cutting)
AI Layer	Structured data → human-readable summary (cross-cutting)
Scheduler	Periodic job execution, cleanly separated from domain logic

---

🛠️ Tech Stack

Technology	Purpose
Java	Core language
Spring Boot	Backend framework
Spring Data JPA	ORM abstraction layer
Hibernate	JPA implementation
MySQL	Relational database
Bean Validation	Input validation
Spring Scheduler	Weekly background jobs
REST APIs	Client communication
AI Service (Mocked)	Human-readable text summaries

---

⚙️ Local Setup

Prerequisites

• Java 23+
• MySQL 8+
• Maven
• Postman (recommended for API testing)

1. Database Setup

CREATE DATABASE work_intelligence;

Configure your MySQL credentials in src/main/resources/application.properties (or .yml).

2. Build & Run

mvn clean install
mvn spring-boot:run

The server starts at:

http://localhost:8080

---

📡 API Reference

All examples below are copy-paste ready for Postman or curl.

---

👤 Employee Management

Create Employee

POST /employees
Content-Type: application/json

{
  "fullName": "John Doe",
  "email": "john.doe@gmail.com",
  "role": "EMPLOYEE"
}

Valid roles: EMPLOYEE | MANAGER | ADMIN

---

Get All Employees

GET /employees

Response:

[
  {
    "id": 1,
    "fullName": "John Doe",
    "email": "john.doe@gmail.com",
    "role": "EMPLOYEE"
  }
]

---

🧑‍💼 Manager Assignment

Assign Manager to Employee

POST /employees/assign-manager
Content-Type: application/json

{
  "employeeId": 5,
  "managerId": 2
}

Validations enforced:

• Target must hold MANAGER role
• Self-assignment is blocked
• Circular hierarchy is prevented
• Operation is fully transactional

---

🧩 Work Logging

Log a Work Entry

POST /work-logs
Content-Type: application/json

{
  "employeeId": 5,
  "workType": "FEATURE",
  "description": "Implemented weekly summary API",
  "startTime": "2026-01-27T10:00:00",
  "endTime": "2026-01-27T13:00:00"
}

Valid work types: FEATURE | BUG | RESEARCH | SUPPORT

---

Get Employee Weekly Logs

GET /work-logs/employee/{employeeId}/weekly?startDate=2026-01-27

Response:

{
  "employeeId": 5,
  "totalHours": 18,
  "workSummary": [
    {
      "date": "2026-01-27",
      "hours": 3,
      "type": "FEATURE"
    }
  ]
}

---

📊 Manager Weekly Intelligence

Manager's Team Weekly Summary

GET /work-logs/manager/{managerId}/weekly?startDate=2026-01-27

Response:

[
  {
    "employeeId": 5,
    "employeeName": "John Doe",
    "totalHours": 18,
    "status": "NORMAL"
  }
]

This structured output is the exact input fed into the AI summary layer.

---

🤖 AI-Assisted Weekly Summary

The AI layer does not expose a standalone endpoint for manual triggering. It runs as part of the weekly scheduled job (see below). The flow is:

Backend aggregates team data  →  Builds structured prompt  →  AI generates plain-text summary

AI makes no decisions. It only explains.

Example AI output:

This week, the team focused primarily on feature development.
Work patterns were consistent, with no major inactivity detected.

---

⏱️ Weekly Scheduler

A scheduled job fires every Monday at 9:00 AM:

@Scheduled(cron = "0 0 9 ? * MON")

It handles:

1. Aggregating weekly data for each manager's team
2. Building the AI prompt from structured facts
3. Generating and storing the human-readable summary

Scheduling, domain logic, and AI logic are fully separated.

---

🧾 Audit Log Structure

Every critical action is recorded. Stored fields per audit entry:

Field	Description
actorId	ID of the user who triggered the action
actorType	USER / MANAGER / SYSTEM
entityType	The entity affected (e.g., EMPLOYEE, WORK_LOG)
entityId	ID of the affected entity
action	What happened (e.g., CREATE, ASSIGN_MANAGER)
timestamp	Exact time of the event

Audit logs are append-only — no updates, no deletes.

---

⚖️ Ethical Design Principles

This system was designed with intent:

❌ What This System Does NOT Do	✅ What This System Does
GPS or location tracking	Transparent, structured data only
Screenshots or screen recording	Human-first interpretation
AI-driven decisions	Explainable insights only
Real-time employee monitoring	Asynchronous, logged work entries

---

📌 Project Status

Area	Status
Backend	✅ Complete & stable
AI Integration	✅ Mocked & replaceable
Audit Logging	✅ Append-only, production-ready
Scheduler	✅ Wired & verified
Frontend	🟡 Intentionally excluded (API-first design)

---

👨‍💻 Author

Built as a backend-focused project to demonstrate real-world Spring Boot architecture, clean system design, transactional safety, ethical AI usage, and enterprise-grade backend practices.

---

📜 License

Open for learning and demonstration purposes.