Chat Backend API

A production-ready REST API for a real-time chat system built with Java 17 and Spring Boot 3.2.5. Supports user authentication, chat rooms (direct & group), messaging with file attachments, and real-time WebSocket communication.

Technology Stack

Technology	Purpose
Java 17	Programming language
Spring Boot 3.2.5	Application framework
Spring Data JPA	Data access layer
Spring Security	Authentication & authorization
JWT (jjwt 0.12.5)	Token-based authentication
H2 Database	Development/testing database
PostgreSQL	Production database
Spring WebSocket	Real-time messaging
SpringDoc OpenAPI 2.5	API documentation (Swagger UI)
Lombok	Boilerplate code reduction
JUnit 5 + Mockito	Testing framework

Features

Mandatory Features ✅

• JWT authentication with refresh tokens
• Role-based access control (USER, ADMIN)
• CRUD operations on 5 entities with relationships
• DTOs with Bean Validation
• Global exception handling with @ControllerAdvice
• Normalized database schema with indexes
• Swagger/OpenAPI documentation

Additional Features ⭐

1. Pagination & Sorting — All list endpoints paginated with configurable size/sort
2. Advanced Search & Filtering — Multi-criteria message search (keyword, sender, date range)
3. Soft Delete — Messages use logical deletion with admin restore
4. Audit Trail — Automatic createdAt, updatedAt, createdBy, updatedBy on all entities
5. File Upload/Download — Attachments with file type and size validation
6. Advanced Security — Account lockout after 5 failed login attempts

Bonus

• WebSocket support for real-time messaging via STOMP

Setup Instructions

Prerequisites

• Java 17+ installed (java -version)
• Maven 3.8+ installed (mvn -version) OR use the included Maven wrapper

Run the Application

# Clone the project
git clone <repository-url>
cd chat-backend

# Run with dev profile (H2 in-memory database)
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# OR using Maven wrapper (if present)
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

The application starts at http://localhost:8080

API Documentation (Swagger UI)

Open http://localhost:8080/swagger-ui.html in your browser.

H2 Database Console

Available at http://localhost:8080/h2-console when running with dev profile:

• JDBC URL: jdbc:h2:mem:chatdb
• Username: sa
• Password: (empty)

API Endpoints Overview

Authentication (Public)

Method	Endpoint	Description
POST	/api/auth/register	Register a new user
POST	/api/auth/login	Login and get JWT tokens
POST	/api/auth/refresh	Refresh access token

Users (Authenticated)

Method	Endpoint	Description
GET	/api/users/me	Get current user profile
PUT	/api/users/me	Update profile
GET	/api/users/{id}	Get user by ID
GET	/api/users/search?query=	Search users

Chat Rooms (Authenticated)

Method	Endpoint	Description
POST	/api/chatrooms	Create chat room
GET	/api/chatrooms	List my chat rooms
GET	/api/chatrooms/{id}	Get chat room details
PUT	/api/chatrooms/{id}	Update chat room
DELETE	/api/chatrooms/{id}	Delete chat room (soft)
POST	/api/chatrooms/{id}/members/{userId}	Add member
DELETE	/api/chatrooms/{id}/members/{userId}	Remove member

Messages (Authenticated)

Method	Endpoint	Description
POST	/api/chatrooms/{roomId}/messages	Send message
GET	/api/chatrooms/{roomId}/messages	Get messages (paginated)
GET	/api/chatrooms/{roomId}/messages/search	Search messages
PUT	/api/messages/{id}	Edit message
DELETE	/api/messages/{id}	Delete message (soft)

Attachments (Authenticated)

Method	Endpoint	Description
POST	/api/messages/{msgId}/attachments	Upload file
GET	/api/attachments/{id}/download	Download file

Admin (ADMIN role only)

Method	Endpoint	Description
GET	/api/admin/users	List all users
PUT	/api/admin/messages/{id}/restore	Restore deleted message

Running Tests

# Run all tests
mvn test

# Run only unit tests
mvn test -Dtest="*ServiceTest"

# Run only integration tests
mvn test -Dtest="*IntegrationTest"

Sample Test Credentials

When running with dev profile, the following accounts are automatically created:

Username	Password	Role
admin	Admin@123	ADMIN
alice	Alice@123	USER
bob	Bob@12345	USER
charlie	Charlie@1	USER

Project Architecture

com.chatapi
├── config/           SecurityConfig, WebSocketConfig, OpenApiConfig, AuditConfig, DataSeeder
├── controller/       AuthController, UserController, ChatRoomController, MessageController,
│                     AttachmentController, AdminController
├── dto/
│   ├── request/      RegisterRequest, LoginRequest, CreateChatRoomRequest, SendMessageRequest, etc.
│   └── response/     AuthResponse, UserResponse, ChatRoomResponse, MessageResponse, PagedResponse, etc.
├── entity/           BaseEntity, User, ChatRoom, ChatRoomMember, Message, Attachment
│   └── enums/        Role, ChatRoomType, MemberRole, MessageType
├── exception/        ResourceNotFoundException, GlobalExceptionHandler, etc.
├── repository/       UserRepository, ChatRoomRepository, MessageRepository, etc.
├── security/         JwtTokenProvider, JwtAuthenticationFilter, CustomUserDetailsService
├── service/          AuthService, UserService, ChatRoomService, MessageService, AttachmentService
│   └── impl/         Service implementations with business logic
└── websocket/        ChatWebSocketController

Database Schema

users ──┐
        ├── chat_room_members ── chat_rooms ── messages ── attachments
        └── messages (sender)

• users → One-to-Many → messages (as sender)
• chat_rooms → One-to-Many → messages
• users ↔ chat_rooms via chat_room_members (Many-to-Many)
• messages → One-to-Many → attachments