• Overview
• Features
• Architecture
• Technology Stack
• Quick Start
• Docker
• Kubernetes Deployment
• Configuration
• Usage
• API Reference
• Development
• Testing
• Monitoring
• Troubleshooting
• Contributing
• License

srvc-tckt (Service Ticket) is a full-featured, distributed support ticket management system built with Spring Boot and designed for Kubernetes environments. It demonstrates real-time workload distribution, agent performance tracking, and queue management across multiple pods.

• 🚀 Cloud-Native: Built for Kubernetes with horizontal scaling
• 🎯 Priority Management: Color-coded priority system (Urgent/High/Medium/Low)
• 🔄 Real-Time Distribution: Watch tickets flow across pods in real-time
• 🛡️ Concurrency Safe: Optimistic locking prevents double-assignment
• 📊 Metrics & Monitoring: Built-in actuator endpoints and performance tracking
• 🎨 Modern UI: Responsive Thymeleaf templates with JavaScript enhancements

• 📋 Ticket Management

  • Create, assign, update, and track support tickets
  • Full lifecycle management (NEW → ASSIGNED → IN_PROGRESS → RESOLVED → CLOSED → ARCHIVED)
  • Priority-based queue with visual color coding
  • Category organization (Technical, Billing, Account, General)

• 👥 Multi-Agent Support

  • Multiple agents can work simultaneously
  • "Assign to Me" functionality with race condition prevention
  • Per-agent performance metrics and dashboards
  • Workload distribution visualization

• 🎯 Priority System

  • 🔴 URGENT - Immediate attention required
  • 🟠 HIGH - Important, prompt handling
  • 🟡 MEDIUM - Standard priority
  • 🟢 LOW - Can be deferred

• 📊 Analytics & Reporting

  • System-wide statistics dashboard
  • Per-agent performance metrics
  • Pod/Node distribution tracking
  • Response time and resolution time SLA tracking

• 🔔 Notifications

  • Email notifications for ticket events
  • Async email processing
  • Configurable notification templates

• ⚖️ Horizontal Scaling: Auto-scaling based on CPU/Memory metrics
• 🎲 Load Distribution: Demonstrates workload spread across pods
• 💚 Health Checks: Liveness and readiness probes
• 📡 Service Discovery: Pod and node tracking
• 🔄 Rolling Updates: Zero-downtime deployments
• 💾 Persistent Storage: PostgreSQL with PVC for data persistence

┌─────────────────────────────────────────────────────────────┐
│                     Load Balancer / Ingress                  │
└───────────────────────┬─────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
    ┌───▼───┐      ┌───▼───┐      ┌───▼───┐
    │ Pod 1 │      │ Pod 2 │      │ Pod 3 │
    │Agent A│      │Agent B│      │Agent C│
    └───┬───┘      └───┬───┘      └───┬───┘
        │               │               │
        └───────────────┼───────────────┘
                        │
                    ┌───▼────┐
                    │PostgreSQL│
                    └────────┘

srvc-tckt/
├── controllers/       # HTTP request handlers
├── services/         # Business logic layer
├── repositories/     # Data access layer
├── entities/         # JPA entities
├── dto/             # Data transfer objects
├── config/          # Spring configuration
└── templates/       # Thymeleaf HTML views

NEW → ASSIGNED → IN_PROGRESS → RESOLVED → CLOSED → ARCHIVED
         ↓             ↓
         └─────────────┴────→ WAITING_CUSTOMER ──→ IN_PROGRESS

• Java 21 - Modern Java LTS release
• Spring Boot 4.0.0 - Application framework
• Spring MVC - Web framework
• Spring Data JPA - Data persistence
• Spring Security - Authentication & authorization
• Hibernate - ORM
• Flyway - Database migrations

• H2 - In-memory database (development)
• PostgreSQL 16 - Production database

• Thymeleaf - Server-side templating
• HTML5/CSS3 - Modern web standards
• JavaScript (ES6+) - Client-side interactivity

• Docker - Containerization
• Kubernetes - Orchestration
• Maven - Build automation
• Spring Boot Actuator - Monitoring & metrics

• Lombok - Boilerplate reduction
• Spring Boot DevTools - Development utilities
• JavaMail - Email notifications

• Java 21 or higher
• Maven 3.9+
• Docker (optional, for containerization)
• kubectl & k3s (optional, for Kubernetes deployment)

1. Clone the repository

   git clone https://github.com/your-org/srvc-tckt.git
   cd srvc-tckt

2. Run with H2 (in-memory database)

   ./mvnw spring-boot:run

3. Access the application

   URL: http://localhost:8888
   

4. Login with default credentials

   • agent1 / password
   • agent2 / password
   • admin / admin

1. Start PostgreSQL

   docker run -d \
     --name postgres \
     -e POSTGRES_DB=srvc_tckt_db \
     -e POSTGRES_USER=postgres \
     -e POSTGRES_PASSWORD=postgres \
     -p 5432:5432 \
     postgres:16-alpine

2. Run application with prod profile

   ./mvnw spring-boot:run -Dspring-boot.run.profiles=prod

# Build the image
docker build -t srvc-tckt:latest .

# Verify the image
docker images | grep srvc-tckt

Create a docker-compose.yml:

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: srvc_tckt_db
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  srvc-tckt:
    image: srvc-tckt:latest
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      SPRING_PROFILES_ACTIVE: prod
      DB_HOST: postgres
      DB_PORT: 5432
      DB_NAME: srvc_tckt_db
      DB_USERNAME: postgres
      DB_PASSWORD: postgres
    ports:
      - "8888:8888"
    healthcheck:
      test: ["CMD", "wget", "--spider", "http://localhost:8888/actuator/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  postgres-data:

Run with:

docker-compose up -d

• k3s or any Kubernetes cluster
• kubectl configured
• Docker image built and available

1. Build and load image into k3s

   # Build the image
   docker build -t srvc-tckt:latest .
   
   # Import into k3s
   docker save srvc-tckt:latest | sudo k3s ctr images import -

2. Deploy to Kubernetes

   kubectl apply -f deployment.yaml

3. Check deployment status

   # Check pods
   kubectl get pods -n srvc-tckt
   
   # Check services
   kubectl get svc -n srvc-tckt
   
   # Watch pod distribution
   kubectl get pods -n srvc-tckt -o wide

4. Access the application

   # Get the LoadBalancer IP
   kubectl get svc srvc-tckt-service -n srvc-tckt
   
   # Access at: http://<EXTERNAL-IP>

# Manual scaling
kubectl scale deployment srvc-tckt -n srvc-tckt --replicas=5

# Check HPA status
kubectl get hpa -n srvc-tckt

# Watch auto-scaling in action
kubectl get hpa -n srvc-tckt --watch

# View logs from all pods
kubectl logs -n srvc-tckt -l app=srvc-tckt --tail=100

# Follow logs from a specific pod
kubectl logs -n srvc-tckt <pod-name> -f

# Execute commands in a pod
kubectl exec -n srvc-tckt <pod-name> -it -- /bin/sh

• local - H2 in-memory database, development features enabled
• prod - PostgreSQL database, production optimizations

Available at /actuator:

• /health - Health check
• /info - Application info
• /metrics - Application metrics
• /prometheus - Prometheus metrics

1. Navigate to Dashboard
2. Click Create New Ticket
3. Fill in the form:
   • Subject
   • Description
   • Priority (Urgent/High/Medium/Low)
   • Category (Technical/Billing/Account/General)
   • Customer Name & Email
4. Click Submit Ticket

1. Login as an agent (agent1/password)
2. View Ticket Queue - See all unassigned tickets
3. Click Assign to Me on a ticket
4. Work through the ticket lifecycle:
   • Start Progress - Begin working
   • Request Info - Ask customer for more details
   • Resolve - Mark as resolved
   • Close - Final closure

1. Go to Statistics page
2. View By Pod section
3. See how tickets are distributed across pods
4. Compare performance metrics per pod/node

• Alt + H - Dashboard
• Alt + Q - Ticket Queue
• Alt + M - My Tickets
• Alt + A - All Tickets
• Alt + N - New Ticket

GET    /tickets              # List all tickets
GET    /tickets/{id}         # Get ticket details
POST   /tickets/new          # Create ticket
POST   /tickets/{id}/assign  # Assign to current agent
POST   /tickets/{id}/start   # Start progress
POST   /tickets/{id}/resolve # Resolve ticket
POST   /tickets/{id}/close   # Close ticket

GET    /tickets/stats        # System statistics

GET    /actuator/health      # Health check
GET    /actuator/metrics     # Metrics
GET    /actuator/info        # Application info

# Clean and build
./mvnw clean install

# Skip tests for faster builds
./mvnw clean install -DskipTests

# Run tests only
./mvnw test

# Package as JAR
./mvnw clean package

srvc-tckt/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/helpdesk/srvc_tckt/
│   │   │       ├── config/          # Configuration
│   │   │       ├── controller/      # Controllers
│   │   │       ├── dto/            # DTOs
│   │   │       ├── entity/         # Entities
│   │   │       ├── repository/     # Repositories
│   │   │       └── service/        # Services
│   │   └── resources/
│   │       ├── db/migration/       # Flyway migrations
│   │       ├── static/             # CSS, JS
│   │       ├── templates/          # Thymeleaf templates
│   │       └── application.properties
│   └── test/                       # Tests
├── Dockerfile                      # Docker image definition
├── deployment.yaml                 # Kubernetes manifests
├── pom.xml                        # Maven configuration
└── README.md                      # This file

• Follow Java naming conventions
• Use Lombok to reduce boilerplate
• Document public APIs with Javadoc
• Write unit tests for service layer
• Keep controllers thin, business logic in services

./mvnw test

./mvnw test -Dtest=TicketServiceTest

./mvnw clean test jacoco:report

View coverage report: target/site/jacoco/index.html

Scrape metrics from:

http://localhost:8888/actuator/prometheus

Import the provided dashboard:

• CPU/Memory usage per pod
• Request rate and response times
• Ticket processing metrics
• Database connection pool stats

Logs are output to stdout/stderr and can be collected by:

• Kubernetes logs: kubectl logs
• Log aggregation: Elasticsearch/Fluentd/Kibana (EFK)
• Cloud logging: CloudWatch, Stackdriver, etc.

Check Java version:

java -version  # Should be 21 or higher

Check port availability:

lsof -i :8888  # Port should be free

PostgreSQL not running:

docker ps | grep postgres

Wrong credentials: Check application-prod.properties and environment variables

Check pod logs:

kubectl logs -n srvc-tckt <pod-name>

Check events:

kubectl describe pod -n srvc-tckt <pod-name>

Check resources:

kubectl top pods -n srvc-tckt

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Commit your changes

   git commit -m "Add amazing feature"

4. Push to the branch

   git push origin feature/amazing-feature

5. Open a Pull Request

• Write clear commit messages
• Add tests for new features
• Update documentation
• Follow existing code style
• Ensure CI passes

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

• Spring Boot team for the excellent framework
• Kubernetes community for orchestration tools
• Open source contributors

• 🐛 Issues: GitHub Issues
• 📖 Docs: Wiki