Real-time Code Synchronization

Relevant source files

The following files were used as context for generating this wiki page:

• src/main/java/org/example/coding_convention/websocket/WebSocketController.java
• src/main/java/org/example/coding_convention/websocket/editor/EditorDto.java
• src/main/java/org/example/coding_convention/websocket/editor/CursorPosition.java
• src/main/java/org/example/coding_convention/websocket/editor/MousePosition.java
• src/main/java/org/example/coding_convention/websocket/editor/MouseController.java
• README.md
• src/main/java/org/example/coding_convention/file/model/FilesDto.java

Real-time Code Synchronization is a core feature of the PhanesEditor project that enables multiple users within the same project to collaborate on code simultaneously. The system leverages WebSocket technology to broadcast code changes, cursor movements, and mouse positions to all participants in a specific project room.

This module ensures that any modification made by a user is immediately reflected across all connected clients, maintaining a consistent state for collaborative development. Access to these real-time features is restricted to verified project members to ensure security and data integrity.
Sources: README.md:12-23, README.md:46-51

Architectural Overview

The synchronization system is built on Spring WebSocket and uses a pub/sub (Publish/Subscribe) pattern. The backend acts as a message broker that receives events from clients and broadcasts them to the appropriate project-specific topics.

Communication Flow

The following diagram illustrates how messages are routed through the WebSocket controllers to synchronize data between users.

The architecture separates different types of real-time data—code edits, cursor movements, and mouse positions—into distinct message mappings and topics to ensure efficient processing.
Sources: WebSocketController.java:23-32, MouseController.java:11-20, README.md:76-78

Core Components and Data Models

Message Data Structures

To facilitate precise synchronization, the system utilizes specific Data Transfer Objects (DTOs) that capture the context of every user action.

Component	Class	Key Fields	Description
Code Change	EditorDto.Code	text, range, type	Represents a text insertion or deletion within a specific line/column range.
Cursor Pos	CursorPosition	line, column, senderId	Tracks the active line and column index of a user's text cursor.
Mouse Pos	MousePosition	x, y, id	Tracks the 2D coordinates of a user's mouse pointer on the screen.

Sources: EditorDto.java:7-22, CursorPosition.java:2-12, MousePosition.java:2-15

Code Modification Logic

Code changes are handled via EditorDto.Code. The Range object specifies exactly where the change occurred in the document, allowing clients to apply incremental updates rather than refreshing the entire file.

public static class Range {
    private Integer startLineNumber;
    private Integer startColumn;
    private Integer endLineNumber;
    private Integer endColumn;
}

Sources: EditorDto.java:7-13

Real-time Event Handling

The synchronization logic is split across two primary controllers that handle different aspects of the collaborative experience.

Editor and Chat Controller

The WebSocketController manages high-level editor events and chat messages tied to a specific project room (roomId).

• Endpoint: /editor/{roomId}
• Topic: /topic/editor/{roomId}
• Functionality: Receives an EditorDto.Code object and broadcasts it to all subscribers of that project's editor topic.

Sources: WebSocketController.java:28-31

Presence and UI Synchronization

The MouseController handles UI-specific feedback like mouse movements and cursor placement. Unlike the general editor controller, these currently broadcast to global topics, though they are intended for visual presence.

File State Management

While WebSocket handles the "in-flight" synchronization, the persistent state of the file is managed through FilesDto.ContentUpdateReq. When a file needs to be saved or synchronized with the database/S3 storage, the fileContents and projectId are validated to ensure the update belongs to the correct context.
Sources: FilesDto.java:15-26, README.md:38-41

Conclusion

The Real-time Code Synchronization system provides a low-latency collaborative environment by utilizing Spring WebSocket. By decoupling code edits, cursor positions, and mouse movements into specialized DTOs and controllers, PhanesEditor-BE ensures that project members can interact seamlessly on a shared codebase while maintaining strict project-based access control.
Sources: README.md:65-72, WebSocketController.java:1-33