Realtime Support Chat

Project roadmap

1. 01

   Define the chat flows

   ~1.5h

   Write DESIGN.md: a conversation is created by a visitor (with a random visitor token), waits in a queue, is claimed by one agent, and is closed by the agent. List the STOMP destinations (sending to /app/conversations/{id}/send, subscribing to /topic/conversations/{id}, and /topic/queue for agents), the message format, and how visitors and agents are identified. Done when: DESIGN.md covers every flow and destination.

2. 02

   Store conversations and messages

   ~2h

   Create a Spring Boot project with Web, WebSocket, Data JPA, Security, Validation and PostgreSQL, using Flyway for the schema. Model agents, conversations (visitor token, status waiting, active or closed, and the assigned agent) and messages (conversation, sender type, text, time and a client id for avoiding duplicates). Add a REST endpoint for paged history. Done when: conversations and messages can be saved and history is returned in pages.

3. 03

   Send messages over WebSockets

   ~2.5h

   Configure a STOMP endpoint with the simple broker. Messages sent to a conversation are validated (length, and that the sender belongs to that conversation), saved, ignored when their client id was already saved, then broadcast to the conversation's topic. Write a simple HTML page for visitors and one for agents using the stomp.js client. Done when: a visitor and an agent can chat in real time.

4. 04

   Assign conversations to agents

   ~2h

   Agents log in (Spring Security with a form or basic login) and see waiting conversations live on /topic/queue. Claiming a conversation uses an update with a condition on the status (or optimistic locking), so if two agents claim at the same moment only one succeeds and the other is told. Secure the WebSocket handshake and check permissions on subscriptions with a ChannelInterceptor, so only the assigned agent and the visitor can join a conversation. Done when: two agents claiming the same conversation results in exactly one owner.

5. 05

   Track presence and missed messages

   ~2h

   Track agents' online status from session connect and disconnect events (SessionConnectedEvent and SessionDisconnectEvent), and show online agents in the agent page. When a visitor reconnects, fetch messages after the last one they saw from the history endpoint. Tell the visitor when their agent disconnects, and return a conversation to the queue if the agent doesn't return within a few minutes. Done when: presence is accurate, and reconnecting shows missed messages.

6. 06

   Test it

   ~2.5h

   Write integration tests with a real PostgreSQL (Testcontainers) and Spring's WebSocketStompClient: sending and receiving messages, duplicate client ids ignored, only authorized subscribers can join a conversation, two agents claiming at once, and history paging. Done when: all tests pass.

Resources

• DocsSpring guide: using WebSocket to build an interactive web application
• DocsSpring Framework reference: WebSockets and STOMP
• DocsSpring Security: WebSocket security
• DocsSpring Data JPA reference
• DocsTestcontainers for Java