Skip to content

README.md

Latest commit

 

History

History
177 lines (126 loc) · 6.45 KB

README.md

File metadata and controls

177 lines (126 loc) · 6.45 KB

TaskForge

TaskForge is a backend application for task and project management, designed to help users organise projects, teams, tasks, comments, attachments, and activity history in a structured and secure way.

The application is useful for small teams, developers, and project coordinators who need a centralised system to manage work, assign responsibilities, track progress, and keep project-related information in one place.

Technical Overview

TaskForge follows a layered backend architecture based on Spring Boot.

The project is organised into clear domain areas such as authentication, users, projects, tasks, teams, comments, attachments, activity logs, email integration, and calendar integration. Each area is separated into controllers, services, repositories, entities, and DTOs to keep the code maintainable, testable, and easy to extend.

The application exposes REST APIs secured with JWT authentication. Users can register, log in, update their profile image, change their password, and interact with the system according to their role. The project includes three roles: USER, MANAGER, and ADMIN, each with different permissions.

Data is stored in PostgreSQL using Spring Data JPA and Hibernate. The domain model includes multiple database tables and relationships such as one-to-many, many-to-one, and many-to-many associations. It also includes inheritance through the activity log model, allowing the application to represent different types of system events in a structured way.

The API design uses DTOs and validation to separate external request and response models from internal entities. Errors are handled through a centralised exception handling layer, which provides consistent and meaningful error responses.

TaskForge also includes advanced query features such as filtering, sorting, task search, project statistics, and aggregation endpoints.

External integrations are included through dedicated email and calendar modules. The email module is designed for notification workflows, while the calendar module supports calendar-related operations for project and task management.

Main Features

  • User registration and login with JWT authentication
  • Role-based authorisation with USER, MANAGER, and ADMIN
  • User profile management
  • Profile image upload
  • Password update
  • Project CRUD operations
  • Project status update
  • Task CRUD operations
  • Task assignment and unassignment
  • Team CRUD operations
  • Team members management
  • Project-team association
  • Comments on tasks
  • Task attachment upload
  • Activity log tracking
  • Filtering, sorting, and advanced task search
  • Project statistics and aggregation endpoints
  • DTO-based request and response handling
  • Request validation with meaningful error messages
  • Centralised exception handling with standard API error responses
  • Email integration module
  • Calendar integration module
  • PostgreSQL persistence
  • Docker-based PostgreSQL setup for local development
  • Postman-ready API testing workflow

API Areas

The application includes the following main API areas:

  • Authentication API
  • User API
  • Admin user management API
  • Project API
  • Task API
  • Team API
  • Comment API
  • Attachment API
  • Activity log API
  • Statistics API
  • Email API
  • Calendar API

Technologies Used

  • Java 17
  • Spring Boot
  • Spring Web
  • Spring Data JPA
  • Spring Security
  • JWT authentication
  • PostgreSQL
  • Hibernate
  • Maven
  • Docker
  • Postman
  • GitHub

Local Development

Prerequisites

Before running the project, make sure the following tools are installed:

  • Java 17
  • Maven
  • Docker
  • PostgreSQL client or Docker-based PostgreSQL container
  • Postman

Database Configuration

The application uses PostgreSQL as its database.

Example local configuration:

spring.datasource.url=jdbc:postgresql://localhost:5433/taskforge
spring.datasource.username=taskforge_user
spring.datasource.password=taskforge_password

A Docker PostgreSQL container can be used for local development. The application expects the database to be available before the Spring Boot application starts.

Start the database with Docker

From the project root, run: docker compose up -d

Run the Application

From the project root, run: ./mvnw spring-boot:run

The application will start on: http://localhost:8080

The health endpoint is available at: http://localhost:8080/actuator/health

Authentication Workflow

Most endpoints require authentication.

The basic workflow is:

  1. Register a user.
  2. Log in with email and password.
  3. Copy the returned JWT access token.
  4. Use the token in Postman with the Authorisation header:

Authorization: Bearer <access_token>

Different roles have different permissions:

  • USER: standard application user.
  • MANAGER: can manage project-related and team-related resources.
  • ADMIN: can manage global administrative operations, including user roles.

Postman Testing

The collection covers:

  • Authentication flow
  • User profile operations
  • Admin role management
  • Project CRUD
  • Task CRUD
  • Task assignment and unassignment
  • Team CRUD
  • Team member operations
  • Project-team association
  • Comments
  • Attachments
  • Activity logs
  • Statistics and aggregations
  • Email integration endpoints
  • Calendar integration endpoints
  • Error cases such as invalid input, missing token, invalid role, and not found resources

Known Issues / Limitations

  • Email sending is currently disabled by configuration for local development and testing.
  • The email module is already present in the project structure, but it must be enabled with valid email provider API token before real emails can be sent.
  • Uploaded files are stored locally, so a production deployment should replace or extend local storage with a cloud storage solution such as AWS S3, Google Cloud Storage, or Azure Blob Storage.
  • The project currently focuses on the backend API only. A frontend application can be added in the future.
  • Local development requires PostgreSQL to be running before starting the application.

Project Status

TaskForge was developed as a university Backend Programming final project and as a portfolio-ready backend application. The project focuses on clean architecture, scalable code organisation, role-based access control, RESTful API design, database persistence, validation, file handling, external service integration, and complete API testing through Postman.

The current version focuses on backend architecture, REST API design, security, persistence, validation, external integrations, and complete API testing.