Advanced Task Management System

This project, developed as part of the Definex Spring Boot Bootcamp, provides a comprehensive management system enabling organizations to effectively handle their project and task management needs. The system includes features such as department-based project organization, advanced task status tracking, team member management, and file attachment support.

📑 Table of Contents

• Features
• Technology Stack
• Getting Started
• API Documentation
• Authentication and Authorization
• Task Workflow
• Running with Docker
• Test Coverage
• Demo Environment

🚀 Features

• 📋 Project and Task Management: Department-based project organization, comprehensive task tracking
• 👥 Team Management: Project-based team creation, role definition, and authorization
• 🔄 Advanced Status Tracking: Task workflow including happy path, cancel, and blocked states
• 🏷️ Priority Management: Assign critical, high, medium, and low priorities to tasks
• 📎 File Attachment Support: Attach and store files with tasks
• 💬 Comments and Collaboration: Discussion and collaboration on tasks
• 📊 Task History: Track status changes with reasons
• 🛡️ JWT-Based Security: Secure API access and role-based authorization
• 📱 Responsive API: Frontend-agnostic API accessible from any device or platform

💻 Technology Stack

Backend

• Language: Java 21
• Framework: Spring Boot 3.4.3
• Security: Spring Security, JWT
• Database: PostgreSQL 17
• ORM: Spring Data JPA
• API Documentation: Swagger UI / OpenAPI 3
• Testing: JUnit 5, Mockito, JaCoCo

DevOps

• Build Tool: Maven
• Containerization: Docker
• CI/CD: GitHub Actions (optional)

🌱 Getting Started

Requirements

• Java 21 or higher
• PostgreSQL 17
• Maven 3.9 or higher

Database Setup

# Create PostgreSQL database
createdb taskmanagement

# Or use tools like pgAdmin/DBeaver to create it

Update the connection details in application.properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/taskmanagement
spring.datasource.username= // Your PostgreSQL username
spring.datasource.password= // Your PostgreSQL password

File Attachment Configuration

# File Upload Configuration
app.file-storage-location=uploads
spring.servlet.multipart.max-file-size= // Maximum file size (e.g., 10MB)
spring.servlet.multipart.max-request-size= // Maximum request size (e.g., 10MB)

Create an uploads directory in the project's root folder:

mkdir uploads
chmod 755 uploads  # For Linux/Mac

For Windows, ensure you give write permissions to the folder.

Building and Running the Project

# Build the project
mvn clean install

# Run the application
mvn spring-boot:run

The application will run on port 8080 by default: http://localhost:8080

📘 API Documentation

You can access the Swagger UI interface at:

http://localhost:8080/docs

Using Swagger UI

Swagger UI provides a comprehensive and interactive interface to explore, test, and learn all available API endpoints. Here's how to use it:

1. Access the Swagger UI: Navigate to http://localhost:8080/docs in your browser

2. Authentication:

   • Click on the "Authorize" button at the top right
   • After logging in via the /api/auth/login endpoint, copy the JWT token from the response
   • In the Authorize dialog, enter the token with format: Bearer eyJhbGciOiJIUzI1NiJ9...
   • Click "Authorize" to apply the token to all subsequent requests

3. Exploring Endpoints:

   • Endpoints are grouped by controllers (User, Project, Task, etc.)
   • Expand any controller to see available operations
   • Each operation includes detailed information about parameters, request body, and responses

4. Testing Endpoints:

   • Click on any endpoint to expand it
   • Fill in required parameters or request body
   • Click "Execute" to send the request
   • View response status, headers, and body below

5. Schema Models:

   • At the bottom of the page, you can find all data models used by the API
   • Expand any model to see its structure and property details

The system uses OpenAPI 3 with custom configuration as defined in the application.properties:

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/docs
springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.tagsSorter=alpha

🔐 Authentication and Authorization

All endpoints are accessible through Swagger UI after logging in. JWT authentication is implemented with a 24-hour token validity period.

Authentication via Swagger UI

1. Navigate to the /api/auth/login endpoint under "Auth Controller"
2. Click "Try it out" and enter your credentials:

   {
     "username": "admin",
     "password": "admin123"
   }

3. Click "Execute" to submit the login request
4. Copy the token from the response body
5. Click the "Authorize" button at the top of the page
6. Enter the token with format Bearer eyJhbGciOiJIUzI1NiJ9...
7. Click "Authorize" to apply the token

Now all your API requests through Swagger UI will include the JWT token automatically.

🔄 Task Workflow

Tasks have the following state flows:

1. Happy Path: Backlog ⟷ In Analysis ⟷ In Development ⟷ Completed
2. Cancel Path: Any state (except Completed) → Cancelled
3. Blocked Paths: (In Analysis ⟷ Blocked) or (In Development ⟷ Blocked)

Status Change Constraints

• ✅ Completed tasks cannot be converted to any other state
• ✅ Cancelled tasks cannot be converted to any other state
• ✅ When a task is blocked or cancelled, providing a reason is mandatory
• ✅ Team leaders and project managers can edit task titles and descriptions
• ✅ Other users can only change task status, add attachments, and comments

🐳 Running with Docker

Recommended Setup Method: Docker provides the easiest way to quickly start the project with all its components. With a single command, you can launch both the PostgreSQL database and the application.

Requirements

• Docker
• Docker Compose (usually included with Docker Desktop)

Docker Startup Steps

# Start the Docker containers
docker-compose up -d

# Check container status
docker-compose ps

# View application logs (optional)
docker-compose logs -f app

Benefits of Docker Setup

• ✅ No need for manual PostgreSQL database installation
• ✅ No need to install Java and Maven on your machine
• ✅ All dependencies are automatically managed
• ✅ Works consistently on any machine (Windows, MacOS, Linux)
• ✅ Application and database run in isolated containers
• ✅ Start and stop the entire system with a single command

Accessing Swagger UI

When running with Docker, you can access Swagger UI at:

http://localhost:8080/docs

Creating Test Data

1. After starting the Docker containers, open Swagger UI
2. Log in using the /api/auth/login endpoint (username: admin, password: admin123)
3. Authorize with the JWT token you receive
4. Generate test data using the /api/test-data/create endpoint

Stopping the Application

# Stop the Docker containers
docker-compose down

🧪 Test Coverage

To view test reports:

# Run tests and generate reports
mvn clean test

# Check JaCoCo test coverage reports
# Reports will be created in the target/site/jacoco directory

🔍 Demo Environment

To populate the system with test data:

1. Start the system:

   mvn spring-boot:run

2. Log in with the admin user through Swagger UI:

   • Navigate to http://localhost:8080/docs
   • Find the /api/auth/login endpoint under "Auth Controller"
   • Enter credentials and execute the request

   {
     "username": "admin",
     "password": "admin123"
   }

   • Copy the JWT token from the response

3. Authorize Swagger UI with the token:

   • Click the "Authorize" button at the top of the page
   • Enter the token with format eyJhbGciOiJIUzI1NiJ9...
   • Click "Authorize"

4. Generate test data:

   • Navigate to the /api/test-data/create endpoint under "Test Data Controller"
   • Click "Execute" to populate the system with test data

This will populate the system with the following test data:

• 4 departments (Software, HR, Marketing, Administration)
• 12 users with different roles (project managers, team leaders, developers)
• 3 projects (Task Management System, E-Commerce Platform, Mobile Banking)
• 11 tasks in various states with realistic descriptions
• Comments and file attachments for task collaboration
• Task history entries for status transitions

The full test data creation logic is available in the TestDataUtil.java class.