Skip to content

A comprehensive, enterprise-grade RESTful API for task and project management with advanced features

License

Notifications You must be signed in to change notification settings

XIVIXMMI/task-management-api

Repository files navigation

Task Management API

Java Spring Boot PostgreSQL Redis License

A comprehensive, enterprise-grade RESTful API for task and project management built with modern Spring Boot architecture. Features hierarchical task structures (Epic/Story/Task), JWT authentication, Redis caching, workspace collaboration, and complete audit trails.

πŸ“‘ Table of Contents

✨ Features

Core Task Management

  • Hierarchical Task Structure: Epic β†’ Story β†’ Task with validation
  • CRUD Operations: Create, read, update, delete tasks with soft delete support
  • Task Filtering & Search: Advanced filtering, pagination, and keyword search
  • Task Progress Tracking: Progress percentage and status management
  • Task Prioritization: Priority levels (low, medium, high, urgent, critical)
  • Due Date Management: Start dates, due dates, and overdue tracking
  • Bulk Operations: Batch status updates and batch deletion
  • Task Assignment: Assign tasks to users within workspaces

Advanced Features

  • Workspace Collaboration: Multi-user workspaces with member management
  • Category Organization: Categorize tasks for better organization
  • Subtasks: Break down tasks into manageable subtasks
  • Task Hierarchy Validation: Prevent circular dependencies and invalid relationships
  • Recurring Tasks: Support for recurring task patterns
  • Activity Logging: Complete audit trail with AOP-based logging
  • Redis Caching: High-performance caching for queries (1-hour TTL)

Security & Authentication

  • JWT Authentication: Secure token-based authentication (Auth0 JWT 4.4.0)
  • Role-based Authorization: USER and ADMIN roles with method-level security
  • Password Encryption: BCrypt password hashing
  • Session Management: Redis-backed session storage
  • Access Control: Task ownership and workspace access validation

Architecture & Code Quality

  • SOLID Principles: Clean, maintainable, and testable code
  • Layered Architecture: Clear separation of Controller, Service, Repository layers
  • Service Segregation: Specialized services (Creation, Query, Update, Delete, Validation)
  • DTO Pattern: Separate API contracts from domain models
  • Global Exception Handling: Centralized error handling with meaningful messages
  • Transaction Management: ACID compliance with Spring transactions
  • MapStruct: Type-safe DTO-Entity mapping

Database & Performance

  • PostgreSQL: Robust relational database with schema separation
  • Flyway Migrations: Version-controlled database schema
  • HikariCP: High-performance connection pooling
  • Query Optimization: Efficient queries with proper indexing
  • Lazy Loading: Optimized entity loading to prevent N+1 problems
  • Redis Caching: Intelligent caching strategy for improved performance

API & Documentation

  • RESTful API: Standard REST conventions
  • OpenAPI 3.0: Complete API documentation with Swagger UI
  • Validation: Comprehensive input validation with Jakarta Bean Validation
  • HTTP/2: Enhanced performance with HTTP/2 support
  • Spring Actuator: Health checks and monitoring endpoints

πŸ›  Technology Stack

Core Framework

Technology Version Purpose
Java 21 Programming language
Spring Boot 3.5.0 Application framework
Spring Data JPA 3.5.0 Data persistence
Spring Security 6.5.x (>=6.5.0) Authentication & authorization
Spring Validation 3.5.0 Input validation
Spring Cache 3.5.0 Caching abstraction
Spring Actuator 3.5.0 Monitoring & health checks

Database & Caching

Technology Version Purpose
PostgreSQL 42.7.7 Primary database
Hibernate 6.6.0.Final ORM implementation
Flyway 10.10.0 Database migrations
Redis Latest Caching & session storage
HikariCP Latest Connection pooling

Security

Technology Version Purpose
Auth0 JWT 4.4.0 JWT token management
Spring Security 6.5.x (>=6.5.0) Security framework (GA release May 19, 2025)
Spring Session Redis Latest Session management
BCrypt Built-in Password hashing

Development Tools

Technology Version Purpose
Lombok 1.18.32 Boilerplate reduction
MapStruct 1.6.3 DTO-Entity mapping
SpringDoc OpenAPI 2.8.8 API documentation
dotenv-java 3.0.0 Environment variables

Build & DevOps

Technology Version Purpose
Maven 3.11.0 Build automation
Docker Latest Containerization
Docker Compose Latest Multi-container orchestration

πŸ— Architecture

Layered Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚         Controller Layer                β”‚
β”‚  (REST API, Request/Response Handling)  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
               β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚         Service Layer                   β”‚
β”‚  (Business Logic, Validation, Caching)  β”‚
β”‚                                         β”‚
β”‚  β”œβ”€ Creation Services                   β”‚
β”‚  β”œβ”€ Query Services                      β”‚
β”‚  β”œβ”€ Update Services                     β”‚
β”‚  β”œβ”€ Deletion Services                   β”‚
β”‚  β”œβ”€ Validation Services                 β”‚
β”‚  β”œβ”€ Access Control Services             β”‚
β”‚  └─ Hierarchy Services                  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
               β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚         Repository Layer                β”‚
β”‚  (Data Access, JPA Repositories)        β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
               β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚         PostgreSQL Database             β”‚
β”‚  (project, usermgmt, audit schemas)     β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Design Principles

βœ… SOLID Principles: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion

βœ… Separation of Concerns: Clear boundaries between layers

βœ… Dependency Injection: Constructor injection via Lombok @RequiredArgsConstructor

βœ… Fail Fast: Early validation with meaningful error messages

βœ… Service Segregation: Specialized services for each operation type

Key Design Patterns

  • Repository Pattern: Data access abstraction with Spring Data JPA
  • DTO Pattern: Separate API contracts from domain entities
  • Builder Pattern: Fluent object construction with Lombok @Builder
  • Facade Pattern: Simplify complex subsystem interactions
  • Strategy Pattern: Task type-specific behavior (Epic/Story/Task)
  • Chain of Responsibility: Validation chains and exception handling

πŸ“‹ Prerequisites

Before you begin, ensure you have the following installed:

πŸš€ Quick Start

Option 1: Docker Compose (Recommended)

The easiest way to get started is using Docker Compose:

# 1. Clone the repository
git clone https://github.com/XIVIXMMI/task-management-api.git
cd task-management-api

# 2. Create environment file
cp .env.example .env
# Edit .env with your configurations

# 3. Start all services (PostgreSQL, Redis, Application)
docker-compose up --build -d

# 4. View logs
docker-compose logs -f app

# 5. Access the application
# API: http://localhost:8080
# Swagger UI: http://localhost:8080/swagger-ui.html
# Health Check: http://localhost:8080/actuator/health

Option 2: Local Development

For local development without Docker:

# 1. Clone the repository
git clone https://github.com/XIVIXMMI/task-management.git
cd task-management

# 2. Start PostgreSQL (ensure it's running on port 5432)
# Create database
createdb taskmanagement

# 3. Start Redis (ensure it's running on port 6379)
redis-server

# 4. Configure environment variables
cp .env.example .env
# Edit .env with your local database credentials

# 5. Build the application
mvn clean install -DskipTests

# 6. Run Flyway migrations (if needed)
mvn flyway:migrate

# 7. Run the application
mvn spring-boot:run

# Or run the JAR file
java -jar target/task-management.jar

# 8. Access the application
# Swagger UI: http://localhost:8080/swagger-ui.html

Quick Health Check

# Check application health
curl http://localhost:8080/actuator/health

# Expected response:
# {"status":"UP"}

βš™οΈ Environment Configuration

Required Environment Variables

Create a .env file in the project root with the following variables:

# ============================================
# Database Configuration
# ============================================
DB_URL=jdbc:postgresql://localhost:5432/taskmanagement
DB_USERNAME=postgres
DB_PASSWORD=your_secure_password

# ============================================
# Redis Configuration
# ============================================
REDIS_HOST=localhost
REDIS_PORT=6379

# ============================================
# JWT Configuration
# ============================================
# Generate a secure 256-bit key: openssl rand -base64 32
JWT_SECRET_KEY=your-256-bit-secret-key-minimum-32-characters
JWT_ISSUER=task-management-api
JWT_EXPIRATION_MINUTE=1440

# ============================================
# Flyway Configuration
# ============================================
FLYWAY_ENABLED=true

Application Profiles

The application supports multiple profiles:

  • dev (default): Development mode with detailed logging

    • SQL logging enabled
    • Debug logging for application packages
    • Redis debug logging
  • prod: Production mode with optimized settings

    • Minimal logging
    • Production-ready caching
    • Optimized connection pooling

Set the active profile:

# In .env file
SPRING_PROFILES_ACTIVE=dev

# Or via command line
mvn spring-boot:run -Dspring-boot.run.profiles=prod

Database Schema Organization

The application uses multiple PostgreSQL schemas:

Schema Purpose Tables
project Task management tasks, workspaces, categories, subtasks, tags
usermgmt User management users, profiles, roles, sessions
audit Audit trails activity_logs, error_logs
notification Notifications notifications, reminders, templates
collaboration Collaboration comments, attachments, invitations

πŸ“š API Documentation

Interactive Documentation

Once the application is running, access the interactive API documentation:

Authentication Flow

All API endpoints (except registration and login) require JWT authentication:

# 1. Register a new user
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.doe",
    "email": "john@example.com",
    "password": "SecurePass123!",
    "confirmPassword": "SecurePass123!"
  }'

# 2. Login and get JWT token
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.doe",
    "password": "SecurePass123!"
  }'

# Response:
# {
#   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "type": "Bearer",
#   "expiresIn": 86400000
# }

# 3. Use token in subsequent requests
curl -X GET http://localhost:8080/api/v1/task \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Key API Endpoints

Authentication & User Management

POST   /api/v1/auth/register              # Register new user
POST   /api/v1/auth/login                 # Login and get JWT token
GET    /api/v1/user/profile               # Get user profile
PUT    /api/v1/user/profile               # Update user profile
PUT    /api/v1/user/password              # Change password
PUT    /api/v1/user/email                 # Update email
PUT    /api/v1/user/avatar                # Update avatar

Task Management

# Task CRUD Operations
POST   /api/v1/task/create                # Create new task
GET    /api/v1/task/{taskId}              # Get task by ID
GET    /api/v1/task/uuid/{uuid}           # Get task by UUID
GET    /api/v1/task                       # Get tasks with filters & pagination
PUT    /api/v1/task/{taskId}              # Update task
DELETE /api/v1/task/{taskId}              # Hard delete task
DELETE /api/v1/task/{taskId}/soft         # Soft delete task

# Task Status & Progress
PATCH  /api/v1/task/{taskId}/status       # Update task status
PATCH  /api/v1/task/{taskId}/progress     # Update task progress

# Bulk Operations
PATCH  /api/v1/task/batch/status          # Update multiple tasks status
DELETE /api/v1/task/batch                 # Delete multiple tasks

# Search & Filtering
GET    /api/v1/task/search                # Search tasks by keyword
GET    /api/v1/task/overdue               # Get overdue tasks

Task Hierarchy

GET    /api/v1/hierarchy/parent/{taskId}  # Get parent task
GET    /api/v1/hierarchy/children/{taskId}# Get child tasks
POST   /api/v1/hierarchy/move             # Move task to new parent
GET    /api/v1/hierarchy/validate         # Validate task hierarchy

Sample Request/Response

Create Task Request

POST /api/v1/task/create
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

{
  "title": "Implement user authentication",
  "description": "Implement JWT-based authentication with Spring Security",
  "priority": "high",
  "taskType": "TASK",
  "dueDate": "2025-10-15T17:00:00",
  "startDate": "2025-10-01T09:00:00",
  "estimatedHours": 16.0,
  "categoryId": 1,
  "workspaceId": 1,
  "assignedToId": 2,
  "parentTaskId": null,
  "isRecurring": false,
  "sortOrder": 0
}

Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": 123,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Implement user authentication",
    "description": "Implement JWT-based authentication with Spring Security",
    "status": "pending",
    "priority": "high",
    "taskType": "TASK",
    "progress": 0,
    "estimatedHours": 16.0,
    "actualHours": 0.0,
    "dueDate": "2025-10-15T17:00:00",
    "startDate": "2025-10-01T09:00:00",
    "categoryName": "Development",
    "workspaceName": "Backend Team",
    "assignedToName": "Jane Smith",
    "createdAt": "2025-09-30T10:30:00",
    "updatedAt": "2025-09-30T10:30:00"
  },
  "timestamp": "2025-09-30T10:30:00"
}

Error Response (400 Bad Request)

{
  "timestamp": "2025-09-30T10:30:00",
  "status": 400,
  "error": "Validation Error",
  "message": "Title must be between 3 and 255 characters",
  "path": "/api/v1/task/create"
}

Task Filtering & Pagination

# Get tasks with filtering and pagination
GET /api/v1/task?page=0&size=10&status=pending&priority=high&sortBy=dueDate&direction=ASC

# Search tasks by keyword
GET /api/v1/task/search?keyword=authentication&page=0&size=20

πŸ“ Project Structure

task-management/
β”œβ”€β”€ src/
β”‚   └── main/
β”‚       β”œβ”€β”€ java/com/omori/taskmanagement/
β”‚       β”‚   β”œβ”€β”€ annotations/              # Custom annotations (@LogActivity)
β”‚       β”‚   β”œβ”€β”€ aspect/                   # AOP aspects
β”‚       β”‚   β”œβ”€β”€ config/                   # Configuration classes
β”‚       β”‚   β”‚   β”œβ”€β”€ SecurityConfiguration.java
β”‚       β”‚   β”‚   β”œβ”€β”€ SwaggerConfiguration.java
β”‚       β”‚   β”‚   β”œβ”€β”€ MessageConfiguration.java
β”‚       β”‚   β”‚   └── WebConfig.java
β”‚       β”‚   β”œβ”€β”€ controller/               # REST Controllers
β”‚       β”‚   β”‚   β”œβ”€β”€ task/
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ TaskBulkController.java
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ TaskCommandController.java
β”‚       β”‚   β”‚   β”‚   └── TaskQueryController.java
β”‚       β”‚   β”‚   β”œβ”€β”€ TaskController.java
β”‚       β”‚   β”‚   β”œβ”€β”€ TaskHierarchyController.java
β”‚       β”‚   β”‚   └── UserUpdateController.java
β”‚       β”‚   β”œβ”€β”€ dto/                      # Data Transfer Objects
β”‚       β”‚   β”‚   β”œβ”€β”€ common/               # ApiResult, RequestMetadata
β”‚       β”‚   β”‚   β”œβ”€β”€ project/              # Task-related DTOs
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ task/
β”‚       β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ creation/
β”‚       β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ update/
β”‚       β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ TaskResponse.java
β”‚       β”‚   β”‚   β”‚   β”‚   └── TaskFilterRequest.java
β”‚       β”‚   β”‚   β”‚   └── subtask/
β”‚       β”‚   β”‚   └── usermgmt/             # User-related DTOs
β”‚       β”‚   β”œβ”€β”€ exceptions/               # Custom exceptions
β”‚       β”‚   β”‚   β”œβ”€β”€ task/
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ TaskNotFoundException.java
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ TaskValidationException.java
β”‚       β”‚   β”‚   β”‚   └── TaskAccessDeniedException.java
β”‚       β”‚   β”‚   └── GlobalExceptionHandler.java
β”‚       β”‚   β”œβ”€β”€ model/                    # JPA Entities
β”‚       β”‚   β”‚   β”œβ”€β”€ audit/                # ActivityLog, ErrorLog
β”‚       β”‚   β”‚   β”œβ”€β”€ collaboration/        # Comment, Attachment
β”‚       β”‚   β”‚   β”œβ”€β”€ notification/         # Notification, Reminder
β”‚       β”‚   β”‚   β”œβ”€β”€ project/              # Task, Workspace, Category
β”‚       β”‚   β”‚   └── usermgmt/             # User, Profile, Role
β”‚       β”‚   β”œβ”€β”€ repository/               # Spring Data JPA Repositories
β”‚       β”‚   β”‚   β”œβ”€β”€ audit/
β”‚       β”‚   β”‚   β”œβ”€β”€ project/              # TaskRepository, WorkspaceRepository
β”‚       β”‚   β”‚   └── usermgmt/             # UserRepository, RoleRepository
β”‚       β”‚   β”œβ”€β”€ security/                 # Security components
β”‚       β”‚   β”‚   β”œβ”€β”€ jwt/                  # JWT implementation
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ JwtAuthenticationFilter.java
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ JwtTokenManager.java
β”‚       β”‚   β”‚   β”‚   └── JwtProperties.java
β”‚       β”‚   β”‚   └── service/
β”‚       β”‚   β”‚       β”œβ”€β”€ AuthService.java
β”‚       β”‚   β”‚       β”œβ”€β”€ CustomUserDetails.java
β”‚       β”‚   β”‚       └── UserDetailsServiceImpl.java
β”‚       β”‚   β”œβ”€β”€ service/                  # Business Logic
β”‚       β”‚   β”‚   β”œβ”€β”€ task/
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ creation/         # Task creation services
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ query/            # Task query services
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ update/           # Task update services
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ delete/           # Task deletion services
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ hierarchy/        # Task hierarchy services
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ utils/            # Validation, access control
β”‚       β”‚   β”‚   β”‚   β”œβ”€β”€ TaskService.java
β”‚       β”‚   β”‚   β”‚   └── TaskServiceImpl.java
β”‚       β”‚   β”‚   β”œβ”€β”€ subtask/
β”‚       β”‚   β”‚   └── user/
β”‚       β”‚   β”œβ”€β”€ utils/                    # Utility classes
β”‚       β”‚   └── validation/               # Custom validators
β”‚       └── resources/
β”‚           β”œβ”€β”€ db/migration/             # Flyway migration scripts
β”‚           β”œβ”€β”€ messages/                 # i18n message bundles
β”‚           β”œβ”€β”€ application.yml           # Main configuration
β”‚           └── banner.txt                # Application banner
β”œβ”€β”€ target/                               # Build output (gitignored)
β”œβ”€β”€ .env                                  # Environment variables (gitignored)
β”œβ”€β”€ .env.example                          # Environment template
β”œβ”€β”€ docker-compose.yml                    # Docker compose (development)
β”œβ”€β”€ docker-compose.prod.yml               # Docker compose (production)
β”œβ”€β”€ Dockerfile                            # Application Docker image
β”œβ”€β”€ pom.xml                               # Maven configuration
β”œβ”€β”€ PROJECT_SPEC.md                       # Detailed project specification
β”œβ”€β”€ AI_MANIFEST.yaml                      # AI assistant configuration
β”œβ”€β”€ README.md                             # This file
└── LICENSE                               # Apache 2.0 License

For detailed package organization and architectural decisions, see PROJECT_SPEC.md.

πŸ”§ Development

Building the Application

# Clean and compile
mvn clean compile

# Run tests
mvn test

# Package application (skip tests)
mvn clean package -DskipTests

# Package with tests
mvn clean package

# Install to local Maven repository
mvn clean install

Running the Application

# Run with Maven
mvn spring-boot:run

# Run with specific profile
mvn spring-boot:run -Dspring-boot.run.profiles=prod

# Run the JAR file
java -jar target/task-management.jar

# Run with custom port
java -jar target/task-management.jar --server.port=9090

# Run in debug mode
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar target/task-management.jar

Code Generation

The project uses annotation processors:

# Lombok generates: getters, setters, constructors, builders, etc.
# MapStruct generates: mapper implementations

# Generated files location:
# target/generated-sources/annotations/

Code Style & Conventions

This project follows strict coding conventions. See PROJECT_SPEC.md for:

  • Naming conventions (packages, classes, methods, variables)
  • Code structure (controllers, services, entities)
  • API design principles
  • Error handling patterns
  • Logging conventions
  • Transaction management
  • Database conventions

Git Commit Conventions

Follow Conventional Commits:

# Format
<type>(<scope>): <subject>

# Examples
feat(task-service): add bulk task update functionality
fix(task-query): enhance query robustness
refactor(controllers): rename ApiResponse to ApiResult
perf(task-services): enhance query performance and caching
docs(readme): update API documentation

# Types: feat, fix, hotfix, refactor, perf, style, docs, test, build, ci, chore

πŸ§ͺ Testing

Running Tests

# Run all tests
mvn test

# Run specific test class
mvn test -Dtest=TaskServiceTest

# Run specific test method
mvn test -Dtest=TaskServiceTest#testCreateTask

# Run tests with coverage
mvn test jacoco:report

# Skip tests during build
mvn package -DskipTests

Test Structure

src/test/java/com/omori/taskmanagement/
β”œβ”€β”€ controller/           # Controller integration tests
β”œβ”€β”€ service/              # Service unit tests
β”œβ”€β”€ repository/           # Repository tests
└── integration/          # Full integration tests

Testing Best Practices

  • Follow AAA pattern: Arrange, Act, Assert
  • Use meaningful test names
  • Mock external dependencies
  • Test both success and failure scenarios
  • Keep tests independent and isolated

🐳 Deployment

Docker Deployment

Development Environment

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Remove volumes
docker-compose down -v

Production Environment

# Build production image
docker build -t omori/taskmanagement:latest .

# Run production compose
docker-compose -f docker-compose.prod.yml up -d

# View logs
docker-compose -f docker-compose.prod.yml logs -f app

# Stop services
docker-compose -f docker-compose.prod.yml down

Manual Deployment

# 1. Build the application
mvn clean package -DskipTests

# 2. Copy JAR to server
scp target/task-management.jar user@server:/opt/taskmanagement/

# 3. Create systemd service
sudo nano /etc/systemd/system/taskmanagement.service

# Service file content:
[Unit]
Description=Task Management API
After=postgresql.service redis.service

[Service]
Type=simple
User=taskmanagement
WorkingDirectory=/opt/taskmanagement
ExecStart=/usr/bin/java -jar task-management.jar
Restart=always
Environment="SPRING_PROFILES_ACTIVE=prod"

[Install]
WantedBy=multi-user.target

# 4. Start service
sudo systemctl daemon-reload
sudo systemctl enable taskmanagement
sudo systemctl start taskmanagement

# 5. Check status
sudo systemctl status taskmanagement

Environment-Specific Configuration

Create different .env files:

  • .env.dev - Development
  • .env.staging - Staging
  • .env.prod - Production

Load the appropriate file before starting:

export $(cat .env.prod | xargs)
java -jar target/task-management.jar

πŸ“Š Monitoring & Health Checks

Spring Actuator Endpoints

# Health check
curl http://localhost:8080/actuator/health

# Detailed health (requires authentication)
curl http://localhost:8080/actuator/health -H "Authorization: Bearer <token>"

# Application info
curl http://localhost:8080/actuator/info

# Metrics
curl http://localhost:8080/actuator/metrics

# Specific metric
curl http://localhost:8080/actuator/metrics/jvm.memory.used

Available Actuator Endpoints

Endpoint Description
/actuator/health Application health status
/actuator/info Application information
/actuator/metrics Application metrics
/actuator/env Environment properties
/actuator/loggers Logger configuration
/actuator/threaddump Thread dump
/actuator/heapdump Heap dump (download)

Logging

Application logs can be found in:

  • Console output (default)
  • Custom log file (if configured)

Log levels are configured in application.yml:

logging:
  level:
    root: INFO
    com.omori.taskmanagement: DEBUG
    org.springframework.web: INFO
    org.hibernate.SQL: OFF

🀝 Contributing

We welcome contributions! Please follow these guidelines:

Development Workflow

  1. Fork the repository

    # Fork on GitHub, then clone your fork
    git clone https://github.com/YOUR-USERNAME/task-management.git
    cd task-management
  2. Create a feature branch

    git checkout -b feature/amazing-feature
  3. Make your changes

    • Follow the coding conventions
    • Write tests for new functionality
    • Update documentation as needed
  4. Run tests

    mvn test
  5. Commit your changes

    # Follow Conventional Commits format
    git commit -m "feat(task-service): add bulk export functionality"
  6. Push to your fork

    git push origin feature/amazing-feature
  7. Create Pull Request

    • Target the dev branch
    • Provide clear description of changes
    • Reference related issues

Code Review Checklist

Before submitting a PR, ensure:

  • βœ… Code follows SOLID principles
  • βœ… All tests pass
  • βœ… New features have tests
  • βœ… Code is properly documented
  • βœ… Follows naming conventions
  • βœ… No security vulnerabilities
  • βœ… API documentation updated (if applicable)
  • βœ… Commit messages follow conventional format

Reporting Issues

When reporting bugs, please include:

  • Clear description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (Java version, OS, etc.)
  • Error messages or stack traces

πŸ“„ License

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

Copyright 2025 Omori

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

πŸ‘€ Author

Omori

πŸ™ Acknowledgments

πŸ“š Additional Documentation

πŸ”— Useful Links


Note: This is an active development project. Features and APIs may change. For the latest updates and roadmap, please check the issues and project board.

For questions or support, please open an issue or contact the maintainer.

About

A comprehensive, enterprise-grade RESTful API for task and project management with advanced features

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages