Skip to content

About

High-throughput collaborative task platform engineered with Java 25 Virtual Threads & Spring Boot 4. Features Hexagonal Modular Monolith, PostgreSQL FTS, Redis rate limiting, RabbitMQ event streaming, S3 storage, WebSocket/STOMP real-time push, OpenTelemetry tracing, and pluggable GenAI.

Topics

aws-s3distributed-systemsevent-drivengenaihexagonal-architecturejavajwtminiomodular-monolithopenapiopentelemetrypostgresqlrabbitmqrate-limitingredisspring-bootstompswaggervirtual-threadswebsocket

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

TaskMaster

Distributed Collaborative Task Platform

CI Build Java 25 Spring Boot 4 PostgreSQL 17 Redis 7 OpenTelemetry OpenAPI 3.1 Tests Passing License: MIT

A high-throughput, cloud-native collaborative task tracking and workflow automation platform.
Engineered with Java 25 Virtual Threads, Spring Boot 4.x, Hexagonal Modular Architecture, Bidirectional WebSocket/STOMP, and Vendor-Agnostic Generative AI.

System Architecture • REST API Specification • Interactive Swagger UI • OpenAPI YAML • Roadmap • Architecture Decisions (ADRs)

📌 Executive Summary

TaskMaster is an enterprise-grade collaborative task tracking platform designed for high concurrency, low latency, and operational elasticity. Built as a decoupled Hexagonal Modular Monolith, each business context functions as an isolated domain that can be scaled monolithically or extracted into independent microservices with zero business logic refactoring.

flowchart TB
    subgraph CLIENTS["🌐 Ingress & API Consumers"]
        direction LR
        SPA["💻 Web UI (Next.js 15 / React 19)"]
        MOBILE["📱 Mobile & API Clients"]
        WS_CLIENT["⚡ WebSocket STOMP Client"]
    end

    subgraph GW["🔐 Security Perimeter & Rate Limiter"]
        direction LR
        RATE["Redis Sliding-Window Limiter\n(Caffeine In-Memory Fallback)"]
        JWT_AUTH["OAuth2 / RS256 JWT Filter\n(RFC 7517 JWKS Discovery)"]
        IDOR_GATE["Multi-Tenant Authorization Gate\n(Personal Tasks & Team Workspaces)"]
        RATE --> JWT_AUTH --> IDOR_GATE
    end

    subgraph CORE["⚙️ TaskMaster Modular Monolith Core (Java 25 LTS · Virtual Threads)"]
        direction TB
        subgraph MODULES["Hexagonal Domain Modules"]
            direction LR
            M_USER["👤 User & Identity\n(Auth, Roles, Tokens)"]
            M_TEAM["👥 Team Workspace\n(RBAC, Invites)"]
            M_TASK["✅ Task Engine\n(FSM, Criteria, Optimistic Lock)"]
            M_COLLAB["💬 Collaboration\n(Threads, S3 Pre-Signed)"]
            M_NOTIF["🔔 Notifications\n(STOMP Broker)"]
        end
        subgraph CROSS_CUTTING["Cross-Cutting Intelligence & Observability"]
            direction LR
            AI_ENG["🤖 Universal AI Engine\n(OpenAI / Groq / Gemini / Ollama)"]
            OTEL_ENG["📊 OpenTelemetry Engine\n(OTLP Exporter / Micrometer)"]
        end
        MODULES --> CROSS_CUTTING
    end

    subgraph STORAGE["🗄️ Resilient Infrastructure Tier"]
        direction LR
        PG[("🐘 PostgreSQL 17\n(ACID · tsvector GIN · JSONB)")]
        REDIS[("🔴 Redis 7\n(Rate Limiter · Session Cache)")]
        S3[("🪣 AWS S3 / MinIO\n(Binary File Attachments)")]
        JAEGER[("🔭 Jaeger Collector\n(OpenTelemetry Tracing)")]
    end

    CLIENTS --> GW
    GW --> CORE
    CORE --> PG
    CORE --> REDIS
    CORE --> S3
    CORE --> JAEGER
Loading

✨ Key Features & Capabilities

🔐 Security & Identity Management

  • Asymmetric RS256 Tokens: Cryptographic access token signing with persistent PEM keys and public RFC 7517 JWKS discovery (/.well-known/jwks.json).
  • Refresh Token Family Rotation: Single-use refresh tokens with automatic family revocation upon replay attack detection.
  • Strict Authorization & IDOR Gates: Team-level boundary enforcement preventing unauthorized cross-tenant mutations.
  • Multi-Tenant Search Scoping: TaskSpecification dynamically scopes queries to joined workspaces and personal tasks (teamId IN (:allowedTeamIds) OR (teamId IS NULL AND (creator = :userId OR assignee = :userId))).
  • Distributed Rate Limiting: Sliding-window rate limiter using Redis ZSET with bounded Caffeine LRU cache fallback.

📋 Task Lifecycle & Execution Engine

  • Formal State Machine: Validated transitions (OPEN → IN_PROGRESS → REVIEW → COMPLETED → ARCHIVED).
  • Multi-Dimensional Querying: High-performance JPA Specifications for dynamic filtering by status, priority, assignee, team, labels, and date ranges.
  • Sub-Millisecond Full-Text Search: PostgreSQL generated tsvector column and weighted GIN index.
  • Concurrency & Soft Deletion: JPA @Version optimistic locking and automatic Hibernate @SQLRestriction soft deletion.

👥 Team Workspaces & Collaboration

  • Role-Based Access Control (RBAC): Fine-grained permissions (OWNER, ADMIN, MEMBER) and secure workspace invite codes.
  • Threaded Comment Discussions: Recursive, nested comment hierarchies with author editing and soft deletes.
  • Direct S3 Pre-Signed Storage: AWS SDK v2 client generating pre-signed URLs to offload binary file download I/O directly to MinIO/S3.

⚡ Real-Time Push & Event Pipeline

  • WebSocket STOMP Broker: Authenticated bidirectional channels (/ws) dispatching instant alerts to private queues (/user/queue/notifications).
  • In-Process Domain Event Bus: Spring ApplicationEventPublisher with transactional boundary awareness (@EventListener).

🤖 Universal Pluggable Generative AI

  • OpenAI-Compatible Standard: Single /chat/completions REST client compatible with Groq Cloud (llama-3.3-70b), Google Gemini, self-hosted Ollama, and enterprise AI Gateways.
  • AI Capabilities: Markdown task description drafting, executive comment summarization, priority recommendation, semantic duplicate detection, and automated categorization tagging.
  • Zero-Downtime Heuristic Fallback: Resilient internal heuristic engine ensures 100% availability during network partitions or offline testing.

📊 Vendor-Neutral Observability

  • OpenTelemetry Standard: Standard OTLP trace export (management.otlp.tracing.endpoint) compatible with Jaeger, Prometheus, Grafana, Datadog, or New Relic without code changes.
  • Standard Error Envelopes: RFC 7807 ProblemDetail responses with timestamps, error codes, and correlation tracking.

🛠️ Technology Stack

Domain Technology Selection Rationale
Runtime Java 25 (LTS) Virtual Threads (Project Loom), Records, Pattern Matching, Sealed Types
Framework Spring Boot 4.0 / Spring 7.0 Jakarta EE 11 baseline, centralized BOM platform, virtual-thread native
Database PostgreSQL 17 + Flyway ACID guarantees, GIN full-text search index, JSONB metadata, Flyway migrations
Cache & Limiter Redis 7 + Caffeine Distributed atomic sliding-window limiting with bounded in-memory fallback
Object Storage AWS SDK v2 (MinIO / S3) Cryptographic pre-signed URLs offload binary file streaming from app servers
Real-Time WebSocket + STOMP (SockJS) JWT-authenticated handshake, targeted point-to-point user notifications
Generative AI Universal OpenAI Protocol Zero vendor lock-in; swappable between Groq, Gemini, Ollama, and AI Gateways
Observability OpenTelemetry (OTel) + OTLP CNCF vendor-neutral tracing, W3C TraceContext, Micrometer Prometheus metrics
API Contract OpenAPI 3.1 & Swagger UI Auto-generated interactive UI + version-controlled static specification YAML
Testing JUnit 5 + ArchUnit + MockMvc 100% passing test suite enforcing hexagonal boundaries and CI validation

⚡ Quick Start

Prerequisites

  • Java JDK 25 (Eclipse Temurin, GraalVM, or OpenJDK)
  • Docker & Docker Compose
  • Gradle 8.x+ (or use the included ./gradlew)

1. Clone Repository

git clone https://github.com/shashankch/task-master.git
cd task-master

2. Launch Local Infrastructure

Start PostgreSQL 17, Redis 7, RabbitMQ, MinIO, and Jaeger OTel Collector in detached mode:

docker compose up -d

Verify service health:

docker compose ps

3. Run the Application

./gradlew bootRun --args='--spring.profiles.active=dev'

The service is available at http://localhost:8080.

🔌 Free-Tier & Pluggable Infrastructure

TaskMaster follows a Zero-Cost Local Development / 1-Line Cloud Upgrade philosophy:

Component Default (Zero-Cost / Open-Source) Managed Cloud Equivalent Switch Mechanism
Database Local PostgreSQL 17 (Docker) / Neon Serverless AWS Aurora / Google Cloud SQL Set SPRING_DATASOURCE_URL
Cache & Rate Limit Local Redis 7 (Docker) / Upstash Redis AWS ElastiCache / Redis Cloud Set SPRING_REDIS_HOST
Object Storage Local MinIO (Docker) AWS S3 / Cloudflare R2 Set AWS_S3_ENDPOINT & AWS Credentials
AI Assistant Groq Cloud (llama-3.3-70b) / Local Ollama OpenAI GPT-4o / Anthropic Claude Set AI_BASE_URL, AI_API_KEY, AI_MODEL
Observability Local Jaeger + Prometheus (Docker) Grafana Cloud / Datadog / Dynatrace Set OTEL_EXPORTER_OTLP_ENDPOINT

📖 API Documentation & Modules

TaskMaster provides interactive documentation and static OpenAPI 3.1 schemas:

API Surface Overview

Module Base Path Key Capabilities Authentication
Auth /api/v1/auth User registration, login, token refresh rotation, logout, and public JWKS Public (Rate Limited)
Users /api/v1/users Profile retrieval and display name/avatar updates Bearer JWT
Tasks /api/v1/tasks CRUD, status state transitions, assignment, criteria search, FTS, soft delete Bearer JWT
Teams /api/v1/teams Workspaces, role governance (OWNER, ADMIN, MEMBER), invite codes Bearer JWT
Comments /api/v1/tasks/{taskId}/comments Hierarchical threaded discussions, nested replies, author edit, soft delete Bearer JWT
Attachments /api/v1/tasks/{taskId}/attachments Multipart upload (≤10MB), S3 storage, pre-signed download URLs, deletion Bearer JWT
Notifications /api/v1/notifications Persistent notification center, unread counters, mark read, STOMP push (/ws) Bearer JWT
AI Assistant /api/v1/ai Task description synthesis, comment summaries, priority suggestions, tagging Bearer JWT

🧪 Testing & Verification

TaskMaster enforces strict automated verification across unit, integration, and architecture layers:

# Run all automated unit and integration tests (110 tests)
./gradlew test

# Run Checkstyle static code analysis and architecture rules
./gradlew check

# Run specific integration slice
./gradlew test --tests "*IntegrationTest"

Architectural Guardrails

Hexagonal boundary purity and modular isolation are enforced at compile-time via ArchUnit in ArchitectureTests.java:

  • Domain models and port interfaces have zero dependencies on web/persistence adapters.
  • Inbound controllers cannot bypass service boundaries to access outbound adapters directly.

🗺️ Product Roadmap

For comprehensive milestone breakdowns, delivery statuses, and planned engineering horizons across all phases, see docs/ROADMAP.md.

📚 Documentation Index

📄 License

Distributed under the MIT License. See LICENSE for more information.

About

High-throughput collaborative task platform engineered with Java 25 Virtual Threads & Spring Boot 4. Features Hexagonal Modular Monolith, PostgreSQL FTS, Redis rate limiting, RabbitMQ event streaming, S3 storage, WebSocket/STOMP real-time push, OpenTelemetry tracing, and pluggable GenAI.

Topics

aws-s3distributed-systemsevent-drivengenaihexagonal-architecturejavajwtminiomodular-monolithopenapiopentelemetrypostgresqlrabbitmqrate-limitingredisspring-bootstompswaggervirtual-threadswebsocket

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages