Call Center Backend - Spring Boot Application

Complete backend implementation for a Call Center system with automatic dialer (Manual, Progressive, and Predictive modes).

🏗️ Architecture

Technology Stack

Java 17+
Spring Boot 3.2+
Spring Data JPA (Database access)
Spring Security + JWT (Authentication)
Spring WebSocket (Real-time notifications)
MySQL 8.0 (Database)
FreeSWITCH (Telephony engine via ESL)

Project Structure

backend/
├── src/main/java/com/callcenter/
│   ├── CallCenterApplication.java          # Main application
│   ├── config/                              # Configuration classes
│   │   ├── CorsConfig.java
│   │   ├── FreeSwitchConfig.java
│   │   ├── SecurityConfig.java
│   │   └── WebSocketConfig.java
│   ├── controller/                          # REST Controllers
│   │   ├── AuthController.java
│   │   ├── CampaignController.java
│   │   ├── ContactController.java
│   │   ├── CallController.java
│   │   ├── AgentController.java
│   │   ├── ReportController.java
│   │   └── WebSocketController.java
│   ├── model/                               # Entity classes
│   │   ├── User.java
│   │   ├── Campaign.java
│   │   ├── Contact.java
│   │   ├── Call.java
│   │   ├── AgentStatus.java
│   │   └── CallRecording.java
│   ├── repository/                          # Data access layer
│   │   ├── UserRepository.java
│   │   ├── CampaignRepository.java
│   │   ├── ContactRepository.java
│   │   ├── CallRepository.java
│   │   ├── AgentStatusRepository.java
│   │   └── CallRecordingRepository.java
│   ├── dto/                                 # Data Transfer Objects
│   │   ├── LoginRequest.java
│   │   ├── LoginResponse.java
│   │   ├── CallRequest.java
│   │   ├── CallResponse.java
│   │   ├── CampaignDTO.java
│   │   ├── ContactDTO.java
│   │   ├── StatisticsDTO.java
│   │   ├── AgentStatusDTO.java
│   │   └── ImportResult.java
│   ├── service/                             # Business logic
│   │   ├── AuthService.java
│   │   ├── CampaignService.java
│   │   ├── ContactService.java
│   │   ├── CallService.java
│   │   ├── AgentService.java
│   │   ├── FreeSwitchService.java
│   │   ├── ReportService.java
│   │   └── WebSocketService.java
│   ├── dialer/                              # Dialer implementations
│   │   ├── ManualDialer.java
│   │   ├── ProgressiveDialer.java           # Runs every 5s
│   │   ├── PredictiveDialer.java            # Runs every 3s
│   │   └── DialRatioCalculator.java
│   ├── freeswitch/                          # FreeSWITCH integration
│   │   ├── ESLClient.java
│   │   ├── EventListener.java
│   │   ├── CommandBuilder.java
│   │   └── EventHandler.java
│   ├── security/                            # Security components
│   │   ├── JwtTokenProvider.java
│   │   ├── JwtAuthenticationFilter.java
│   │   └── UserDetailsServiceImpl.java
│   └── exception/                           # Exception handling
│       ├── ResourceNotFoundException.java
│       ├── FreeSwitchException.java
│       ├── ValidationException.java
│       └── GlobalExceptionHandler.java
└── src/main/resources/
    └── application.yml                      # Application configuration

🚀 Quick Start

Prerequisites

Java 17 or higher
```
java -version
```
Maven 3.6+
```
mvn -version
```
MySQL 8.0
```
mysql --version
```
FreeSWITCH (installed and configured)
```
systemctl status freeswitch
```

Setup Steps

1. Add FreeSWITCH ESL Dependency

CRITICAL: Add this to pom.xml before building:

<!-- FreeSWITCH ESL Client -->
<dependency>
    <groupId>org.freeswitch.esl.client</groupId>
    <artifactId>org.freeswitch.esl.client</artifactId>
    <version>0.9.2</version>
</dependency>

2. Create Database

CREATE DATABASE callcenter_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'callcenter_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON callcenter_db.* TO 'callcenter_user'@'localhost';
FLUSH PRIVILEGES;

3. Configure Application

Edit src/main/resources/application.yml:

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/callcenter_db
    username: callcenter_user
    password: your_password

jwt:
  secret: change-this-to-a-secure-256-bit-secret-key-minimum-32-characters

freeswitch:
  esl:
    host: localhost
    port: 8021
    password: ClueCon

4. Build & Run

# Clean and build
mvn clean install

# Run application
mvn spring-boot:run

# Or run JAR
java -jar target/callcenter-0.0.1-SNAPSHOT.jar

Application starts on: http://localhost:8080

📡 API Endpoints

Authentication

POST   /api/auth/login          # Login
POST   /api/auth/register       # Register user
GET    /api/auth/me             # Get current user

Campaigns

GET    /api/campaigns                 # List all (paginated)
GET    /api/campaigns/{id}            # Get campaign
POST   /api/campaigns                 # Create campaign
PUT    /api/campaigns/{id}            # Update campaign
DELETE /api/campaigns/{id}            # Delete campaign
POST   /api/campaigns/{id}/start      # Start campaign
POST   /api/campaigns/{id}/pause      # Pause campaign
POST   /api/campaigns/{id}/stop       # Stop campaign
GET    /api/campaigns/{id}/statistics # Get statistics

Contacts

GET    /api/contacts                        # List all (paginated)
GET    /api/contacts/{id}                   # Get contact
POST   /api/contacts                        # Create contact
PUT    /api/contacts/{id}                   # Update contact
DELETE /api/contacts/{id}                   # Delete contact
POST   /api/contacts/import                 # Import CSV
GET    /api/contacts/campaign/{campaignId}  # List by campaign

Calls

POST   /api/calls/make                # Make call
POST   /api/calls/{callId}/hangup     # Hangup call
POST   /api/calls/{callId}/transfer   # Transfer call
POST   /api/calls/{callId}/complete   # Complete call (add notes)
GET    /api/calls/history             # Call history
GET    /api/calls/{callId}            # Get call details
GET    /api/calls/agent/{agentId}     # Agent's calls

Agents

GET    /api/agents                        # List agents
GET    /api/agents/{id}/status            # Get agent status
POST   /api/agents/{id}/status            # Update agent status
GET    /api/agents/available              # Available agents
GET    /api/agents/{id}/status/history    # Status history

Reports

GET    /api/reports/dashboard                    # Dashboard statistics
GET    /api/reports/calls-by-hour               # Calls by hour
GET    /api/reports/calls-by-disposition        # Calls by disposition
GET    /api/reports/agent-performance           # Agent performance
GET    /api/reports/campaign-stats/{campaignId} # Campaign statistics

🔌 WebSocket Topics

Subscribe to:

/topic/calls - All call events
/topic/agents - Agent status changes
/topic/campaigns - Campaign updates
/topic/statistics - Statistics updates
/user/queue/messages - User-specific messages
/user/queue/contacts - Contact assignments

Send to:

/app/call.event - Send call event
/app/agent.status - Send agent status
/app/campaign.update - Send campaign update

Example WebSocket Connection:

const socket = new SockJS('http://localhost:8080/ws');
const stompClient = Stomp.over(socket);

stompClient.connect({
  'Authorization': 'Bearer ' + token
}, function(frame) {
  console.log('Connected: ' + frame);

  // Subscribe to call events
  stompClient.subscribe('/topic/calls', function(message) {
    const event = JSON.parse(message.body);
    console.log('Call event:', event);
  });

  // Subscribe to user-specific messages
  stompClient.subscribe('/user/queue/messages', function(message) {
    const data = JSON.parse(message.body);
    console.log('Message:', data);
  });
});

📞 Dialer Modes

1. Manual Dialer

Agent requests next contact
Agent initiates call manually
One call at a time per agent

2. Progressive Dialer

Runs automatically every 5 seconds
Dials one contact per available agent
Waits for customer to answer before connecting to agent
No abandoned calls

3. Predictive Dialer (COMPLETE ALGORITHM)

Runs automatically every 3 seconds
Implements complete algorithm from specifications:
1. Get campaign metrics
2. Calculate contact rate
3. Calculate dial ratio based on aggressiveness
4. Adjust for abandonment rate
5. Dial multiple contacts
6. Connect answered calls to available agents
7. Abandon calls if no agent available

Algorithm formula:

ratioBase = availableAgents / contactRate
ratio = ratioBase * aggressiveness
if (abandonmentRate > 5%): ratio = ratio * 0.8
ratio = min(ratio, availableAgents * 3)
callsToMake = ratio - callsInProgress

🔧 FreeSWITCH Integration

ESL Commands Supported:

originate - Initiate calls
uuid_kill - Hangup calls
uuid_bridge - Connect calls
uuid_transfer - Transfer calls
uuid_record - Record calls
uuid_hold - Hold/unhold calls

Events Handled:

CHANNEL_CREATE - Call created
CHANNEL_ANSWER - Call answered
CHANNEL_HANGUP - Call ended
CHANNEL_BRIDGE - Calls connected
HEARTBEAT - Connection keepalive

🛡️ Security

Authentication

JWT token-based authentication
Token expiration: 24 hours (configurable)
BCrypt password encryption

Authorization

Role-based access control (RBAC)
Roles: ADMIN, SUPERVISOR, AGENT
Method-level security with @PreAuthorize

CORS

Configured for frontend (http://localhost:4200)
Can be customized in CorsConfig.java

📊 Database Schema

Tables auto-created by JPA:

users - System users (agents, supervisors, admins)
campaigns - Call campaigns
contacts - Contact list
calls - Call history
agent_status - Agent status tracking
call_recordings - Recording metadata

🧪 Testing

Test Authentication

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

Test Protected Endpoint

curl -X GET http://localhost:8080/api/campaigns \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Test WebSocket

See WebSocket example above

📝 Logging

Logs are configured in application.yml:

Root level: INFO
Application level: DEBUG
FreeSWITCH events: DEBUG
SQL queries: DEBUG (in development)

🔍 Monitoring

Health Check

curl http://localhost:8080/actuator/health

Metrics

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

🐛 Troubleshooting

Issue: FreeSWITCH connection fails

Solution: Check FreeSWITCH is running and ESL is enabled on port 8021

Issue: Database connection fails

Solution: Verify MySQL is running and credentials are correct

Issue: JWT authentication fails

Solution: Ensure JWT secret is at least 32 characters

Issue: WebSocket connection fails

Solution: Check CORS configuration and WebSocket endpoint

📦 Production Deployment

1. Build production JAR

mvn clean package -DskipTests

2. Run with production profile

java -jar -Dspring.profiles.active=prod target/callcenter-0.0.1-SNAPSHOT.jar

3. Environment Variables

export DB_URL=jdbc:mysql://production-db:3306/callcenter_db
export DB_USER=callcenter_user
export DB_PASSWORD=secure_password
export JWT_SECRET=your-secure-256-bit-secret-key
export FREESWITCH_HOST=freeswitch-server

4. Docker Deployment (Optional)

FROM openjdk:17-jdk-slim
COPY target/callcenter-0.0.1-SNAPSHOT.jar app.jar
ENTRYPOINT ["java","-jar","/app.jar"]

🔐 Security Best Practices

Change default JWT secret
Change default admin password
Use HTTPS in production
Configure firewall rules
Enable rate limiting
Regular security updates
Monitor logs for suspicious activity

📈 Performance Tuning

JVM Options

java -Xms2G -Xmx4G -XX:+UseG1GC -jar callcenter.jar

Database Connection Pool

Configure in application.yml:

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5

🤝 Contributing

Follow Spring Boot best practices
Use Lombok annotations
Add proper logging
Handle exceptions properly
Write unit tests
Document new endpoints

📄 License

[Your License Here]

👥 Support

For issues and questions:

Check logs in logs/ directory
Review this README
Check IMPLEMENTATION_CHECKLIST.md

Status: Production Ready ✅

All 56 Java files implemented with complete functionality. No TODOs or stubs.

Name		Name	Last commit message	Last commit date
.idea		.idea
.mvn/wrapper		.mvn/wrapper
logs		logs
src/main		src/main
target		target
.dockerignore		.dockerignore
.gitattributes		.gitattributes
DEVTOOLS_QUICK_START.md		DEVTOOLS_QUICK_START.md
Dockerfile		Dockerfile
GenerateHash.java		GenerateHash.java
README.md		README.md
backend.log		backend.log
fix-enums.sh		fix-enums.sh
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

Latest commit

History

Folders and files

Repository files navigation

Call Center Backend - Spring Boot Application

🏗️ Architecture

Technology Stack

Project Structure

🚀 Quick Start

Prerequisites

Setup Steps

1. Add FreeSWITCH ESL Dependency

2. Create Database

3. Configure Application

4. Build & Run

📡 API Endpoints

Authentication

Campaigns

Contacts

Calls

Agents

Reports

🔌 WebSocket Topics

Subscribe to:

Send to:

Example WebSocket Connection:

📞 Dialer Modes

1. Manual Dialer

2. Progressive Dialer

3. Predictive Dialer (COMPLETE ALGORITHM)

🔧 FreeSWITCH Integration

ESL Commands Supported:

Events Handled:

🛡️ Security

Authentication

Authorization

CORS

📊 Database Schema

🧪 Testing

Test Authentication

Test Protected Endpoint

Test WebSocket

📝 Logging

🔍 Monitoring

Health Check

Metrics

🐛 Troubleshooting

Issue: FreeSWITCH connection fails

Issue: Database connection fails

Issue: JWT authentication fails

Issue: WebSocket connection fails

📦 Production Deployment

1. Build production JAR

2. Run with production profile

3. Environment Variables

4. Docker Deployment (Optional)

🔐 Security Best Practices

📈 Performance Tuning

JVM Options

Database Connection Pool

🤝 Contributing

📄 License

👥 Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages