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.
- Features
- Technology Stack
- Architecture
- Prerequisites
- Quick Start
- Environment Configuration
- API Documentation
- Project Structure
- Development
- Testing
- Deployment
- Contributing
- License
- 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
- 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)
- 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
- 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
- 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
- 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 | 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 |
| 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 |
| 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 |
| 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 |
| Technology | Version | Purpose |
|---|---|---|
| Maven | 3.11.0 | Build automation |
| Docker | Latest | Containerization |
| Docker Compose | Latest | Multi-container orchestration |
βββββββββββββββββββββββββββββββββββββββββββ
β 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) β
βββββββββββββββββββββββββββββββββββββββββββ
β 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
- 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
Before you begin, ensure you have the following installed:
- Java Development Kit (JDK) 21+: Download OpenJDK
- Maven 3.8+: Download Maven
- Docker & Docker Compose: Download Docker (recommended)
- PostgreSQL 15+: If not using Docker
- Redis 7+: If not using Docker
- Git: For version control
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/healthFor 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# Check application health
curl http://localhost:8080/actuator/health
# Expected response:
# {"status":"UP"}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=trueThe 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=prodThe 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 |
Once the application is running, access the interactive API documentation:
- Swagger UI: http://localhost:8080/swagger-ui.html
- OpenAPI JSON: http://localhost:8080/v3/api-docs
- OpenAPI YAML: http://localhost:8080/v3/api-docs.yaml
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..."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 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 tasksGET /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 hierarchyPOST /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": 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"
}{
"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"
}# 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=20task-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.
# 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# 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.jarThe project uses annotation processors:
# Lombok generates: getters, setters, constructors, builders, etc.
# MapStruct generates: mapper implementations
# Generated files location:
# target/generated-sources/annotations/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
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# 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 -DskipTestssrc/test/java/com/omori/taskmanagement/
βββ controller/ # Controller integration tests
βββ service/ # Service unit tests
βββ repository/ # Repository tests
βββ integration/ # Full integration tests
- Follow AAA pattern: Arrange, Act, Assert
- Use meaningful test names
- Mock external dependencies
- Test both success and failure scenarios
- Keep tests independent and isolated
# 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# 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# 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 taskmanagementCreate 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# 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| 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) |
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: OFFWe welcome contributions! Please follow these guidelines:
-
Fork the repository
# Fork on GitHub, then clone your fork git clone https://github.com/YOUR-USERNAME/task-management.git cd task-management
-
Create a feature branch
git checkout -b feature/amazing-feature
-
Make your changes
- Follow the coding conventions
- Write tests for new functionality
- Update documentation as needed
-
Run tests
mvn test -
Commit your changes
# Follow Conventional Commits format git commit -m "feat(task-service): add bulk export functionality"
-
Push to your fork
git push origin feature/amazing-feature
-
Create Pull Request
- Target the
devbranch - Provide clear description of changes
- Reference related issues
- Target the
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
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
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.
Omori
- Email: nguyen.le.programmer@gmail.com
- GitHub: @XIVIXMMI
- Spring Boot - Excellent application framework
- PostgreSQL - Robust and reliable database
- Redis - High-performance caching solution
- MapStruct - Type-safe mapping framework
- Lombok - Reducing boilerplate code
- Auth0 - JWT library
- SpringDoc - OpenAPI documentation
- PROJECT_SPEC.md - Comprehensive project specification
- AI_MANIFEST.yaml - AI assistant configuration
- Swagger UI - Interactive API documentation (when running)
- Spring Boot Documentation
- Spring Data JPA Documentation
- Spring Security Documentation
- PostgreSQL Documentation
- Redis Documentation
- Conventional Commits
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.