Skip to content

PROJECT_README.md

Latest commit

 

History

History
368 lines (270 loc) · 8.71 KB

PROJECT_README.md

File metadata and controls

368 lines (270 loc) · 8.71 KB
Raw

Cloud_Native_Task_Manager - Microservices Architecture

📦 Project Overview

Cloud_Native_Task_Manager is a production-ready cloud-native microservices task management platform designed for scalability, resilience, and ease of deployment.

Project Details

  • Name: Cloud_Native_Task_Manager
  • Version: 2.0.0 (Microservices Architecture)
  • Type: Microservices with Spring Boot 3.2 & Next.js 14
  • Status: ✅ Production-Ready

🎯 Quick Start

Prerequisites

  • Docker & Docker Compose (recommended)
  • Or: Java 21, Maven 3.9+, Node.js 20+, PostgreSQL 16

Start in 3 Minutes

# Clone or navigate to project
cd Cloud_Native_Task_Manager

# Start all services
docker compose up --build

# Access services
# Frontend:       http://localhost:3000
# API Gateway:    http://localhost:8080/api
# Eureka:         http://localhost:8761
# Swagger UI:     http://localhost:8080/api/swagger-ui.html

Default Credentials:

  • Username: admin
  • Password: admin123

🏗️ Architecture

6 Independent Microservices

┌─────────────────────────────────────────┐
│     Frontend (Next.js)                  │
│     http://localhost:3000               │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│  API Gateway (Spring Cloud)             │
│  http://localhost:8080/api              │
└──────────────────┬──────────────────────┘
     │             │             │
     ▼             ▼             ▼
┌────────┐  ┌────────┐  ┌────────┐
│ Auth   │  │ Task   │  │ User   │
│Service │  │Service │  │Service │
│:8081   │  │:8082   │  │:8083   │
└────┬───┘  └────┬───┘  └────┬───┘
     │           │           │
     ▼           ▼           ▼
   [auth_db] [task_db] [user_db]

Service Discovery: Eureka (Port 8761)

Services

Service Port Purpose
Auth Service 8081 Authentication & JWT
Task Service 8082 Task management
User Service 8083 User admin operations
API Gateway 8080 Request routing
Service Discovery 8761 Eureka registry

📊 Key Features

✅ 6 Independent Microservices ✅ Service Discovery - Eureka-based auto-discovery ✅ API Gateway - Transparent request routing ✅ 3 Separate Databases - Data isolation per service ✅ JWT Authentication - Secure token-based auth ✅ Role-Based Access Control - ADMIN and USER roles ✅ Task Management - Full CRUD with filtering & pagination ✅ Docker Support - One-command setup ✅ Kubernetes Ready - Complete K8s manifests ✅ 100% Backward Compatible - Zero breaking changes

📁 Project Structure

Cloud_Native_Task_Manager/
├── 🏗️ Microservices (6 modules)
│   ├── auth-service/          # Authentication service
│   ├── task-service/          # Task management
│   ├── user-service/          # User admin
│   ├── api-gateway/           # Request router
│   ├── service-discovery/     # Eureka server
│   └── common/                # Shared DTOs
│
├── 🖼️ Frontend
│   └── frontend/              # Next.js 14 app
│
├── 🐳 Deployment
│   ├── docker-compose.yml     # Local setup
│   └── k8s/                   # Kubernetes manifests
│
├── 📚 Documentation
│   ├── README.md              # This file
│   ├── ARCHITECTURE.md        # System design
│   ├── DEPLOYMENT_GUIDE.md    # Deployment instructions
│   ├── QUICK_REFERENCE.md     # Quick commands
│   ├── MIGRATION_SUMMARY.md   # v1→v2 migration
│   └── docs/                  # Complete docs
│
└── ⚙️ Configuration
    ├── pom.xml               # Parent Maven POM
    ├── docker-compose.yml
    └── .env.example

🚀 Deployment

Option 1: Docker Compose (Development)

docker compose up --build

Option 2: Kubernetes (Production)

# Apply all K8s manifests
kubectl apply -k k8s/

# Verify deployment
kubectl get pods -n task-management

Option 3: Cloud Platforms

See DEPLOYMENT_GUIDE.md for AWS, GCP, Azure, DigitalOcean, etc.

📡 API Endpoints

All endpoints are accessed through the API Gateway at http://localhost:8080/api

Authentication

POST /api/auth/register    # Register new user
POST /api/auth/login       # Login & get JWT token

Tasks

GET    /api/tasks          # List tasks
POST   /api/tasks          # Create task
GET    /api/tasks/{id}     # Get task
PUT    /api/tasks/{id}     # Update task
DELETE /api/tasks/{id}     # Delete task

Users (Admin Only)

GET    /api/users          # List all users
GET    /api/users/{id}     # Get user details

Full API Documentation: See docs/api/API_REFERENCE.md

🗂️ Database Design

3 Separate PostgreSQL Databases

auth_db (Port 5432)

  • Stores user credentials & authentication
  • Only accessed by Auth Service

task_db (Port 5433)

  • Stores task data
  • Only accessed by Task Service

user_db (Port 5434)

  • Stores user profiles
  • Only accessed by User Service

🔧 Configuration

Environment Variables

Create .env.local from .env.example:

cp .env.example .env.local

Key Variables:

# Database
SPRING_DATASOURCE_USERNAME=taskuser
SPRING_DATASOURCE_PASSWORD=taskpassword

# JWT
JWT_SECRET=<base64-encoded-secret>
JWT_EXPIRATION=86400000

# Admin
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:8080/api

📚 Documentation

By Role

👨‍💻 Developers → Start with QUICK_REFERENCE.md

🏗️ Architects → Start with ARCHITECTURE.md

🔧 DevOps → Start with DEPLOYMENT_GUIDE.md

Everyone → Start with docs/README.md (complete docs index)

🔄 Migration from v1.0.0

This project was successfully migrated from monolithic to microservices:

✅ Zero Breaking Changes - Same API endpoints ✅ 100% Backward Compatible - Frontend works unchanged ✅ 6 Independent Services - Decomposed from monolith ✅ 3 Separate Databases - Data isolation per service

See MIGRATION_SUMMARY.md for details.

🎓 Technology Stack

Backend

  • Spring Boot 3.2.3
  • Spring Cloud 2023.0.0
  • Spring Security 6.1
  • Spring Data JPA
  • PostgreSQL 16
  • Eureka & Spring Cloud Gateway
  • Maven 3.9+

Frontend

  • Next.js 14
  • React 18
  • TypeScript
  • Tailwind CSS
  • Axios

DevOps

  • Docker & Docker Compose
  • Kubernetes 1.24+
  • GitHub Actions
  • Kustomize

🔒 Security

✅ JWT Authentication - HMAC-SHA512 signing, 24-hour expiration ✅ BCrypt Password Hashing - Secure password storage ✅ Role-Based Access Control - ADMIN and USER roles ✅ Per-Service Token Validation - No cascading auth calls ✅ Separate Databases - Data isolation

🧪 Testing

# Build and test all services
mvn clean test

# Build specific service
mvn clean package -pl auth-service -DskipTests

# Run integration tests
mvn clean verify

📞 Support & Help

Need Go To
Quick commands QUICK_REFERENCE.md
API documentation docs/api/
Deployment help DEPLOYMENT_GUIDE.md
Architecture details ARCHITECTURE.md
Complete documentation docs/README.md

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Commit your changes: git commit -m "feat: add my feature"
  4. Push to branch: git push origin feature/my-feature
  5. Open a Pull Request

📄 License

MIT License - See LICENSE file for details

📊 Project Statistics

  • Microservices: 6
  • Databases: 3 (separate)
  • API Endpoints: 10+
  • Documentation: 4,500+ lines
  • Docker Containers: 10 (local)
  • Kubernetes Objects: 50+

Last Updated: March 19, 2026 Status: ✅ Production-Ready Version: 2.0.0 (Microservices)

Quick Links