How Chorus Works

Laravel Chorus creates a bidirectional synchronization system between your Laravel backend and client applications. This page explains the core architecture and data flow patterns that make real-time synchronization possible.

Architecture Overview

Core Components

Server-Side Components

Harmonics Trait

Applied to Laravel models to enable synchronization. Defines which fields to sync and provides filtering capabilities.

class Message extends Model
{
    use Harmonics;
    
    protected $syncFields = ['id', 'body', 'user_id', 'created_at'];
    
    protected function syncFilter(): Builder
    {
        return $this->where('user_id', auth()->id());
    }
}

Harmonics Table

Central change log that records all create, update, and delete operations for tracked models.

Column	Purpose
`table_name`	Which model table changed
`record_id`	Primary key of the changed record
`operation`	Type of change (create/update/delete)
`data`	JSON snapshot of the changed fields
`user_id`	For user-scoped synchronization
`rejected`	Boolean flag that is true if the user write is rejected
`rejected_reason`	Reason for rejection (string)

Write Actions

Handle client write operations with validation, business logic, and conflict resolution.

class CreateMessageAction extends WriteAction
{
    public function handle(Request $request, array $data): Message
    {
        return Message::create([
            'id' => $data['id'] ?? Str::uuid(),
            'body' => $data['message'],
            'user_id' => auth()->id(),
        ]);
    }
    
    public function rules(): array
    {
        return [
            'message' => 'required|string|max:255'
        ];
    }
}

Laravel Reverb Integration

WebSocket server that broadcasts change events to connected clients in real-time.

Client-Side Components

IndexedDB Storage

Browser-based database that stores synchronized data locally for offline access and instant queries. We use DexieJS to provide to sensibly interface with IndexedDB.Example DexieJS Query

const messagesQuery = useTableQuery<Message>(
    (table) => selectedPlatform
        ? table.where('platform_id').equals(selectedPlatform)
        : table,
        [selectedPlatform]
);

Chorus Hooks

React hooks that manage synchronization, provide optimistic updates, and handle real-time data binding.

const { data: messages, create, update, delete: remove } = useTable(
  'messages', 
  types
);

WebSocket Connection

Persistent connection to Laravel Reverb for receiving real-time updates and broadcasting changes.

Optimistic Updates

Immediate UI updates before server confirmation, providing instant user feedback.

Change Detection Adapters

Chorus supports multiple methods for detecting model changes:

1. Eloquent (Default)

// Automatically triggers when models are saved/deleted
public static function bootHarmonics()
{
    static::created(fn($model) => self::createHarmonic($model, 'create'));
    static::updated(fn($model) => self::createHarmonic($model, 'update'));
    static::deleted(fn($model) => self::createHarmonic($model, 'delete'));
}

2. Postgres: WAL Logical Replication Stream (Future Enhancement)

It is planned to add support for Postgres Logical Replication stream. For Postgres databases with logical replication enabled, it is possible to listen to the database’s logical changes (create, update, delete) directly. This means that we can mutate the database directly without going through the Eloquent ORM. This approach is ideal for applications that have databases that can change outside Laravel in some way.

Synchronization Strategies

Selective Field Sync

Only specified fields are synchronized, reducing bandwidth and storage requirements.

protected $syncFields = [
    'id',           // Always include primary key
    'title',        // User-visible content
    'status',       // Business logic fields
    'updated_at'    // Timestamp for conflict resolution
    // 'password' excluded for security
    // 'internal_notes' excluded to reduce size
];

Filtered Synchronization

Apply custom logic to determine which records each user should receive.

protected function syncFilter(): Builder
{
    $user = auth()->user();
    
    return $this->where(function($query) use ($user) {
        $query->where('user_id', $user->id)              // Own records
              ->orWhere('assigned_to', $user->id)         // Assigned records
              ->orWhere('team_id', $user->team_id);       // Team records
    });
}

Channel-based Broadcasting

Different WebSocket channels for different data scopes and user permissions.

// User-specific channel
"chorus.user.{$userId}"

// Tenant-specific channel  
"chorus.tenant.{$tenantId}.user.{$userId}"

// Table-wide updates
"chorus.table.messages"

// Record-specific updates
"chorus.record.messages.{$messageId}"

Conflict Resolution

When multiple clients modify the same data simultaneously, Chorus handles conflicts using:

Last-Write-Wins Strategy

Server timestamps determine the “winning” version
Client changes are overwritten by server updates
Simple but may lose user edits in rare cases

Optimistic Locking

Version numbers or timestamps prevent conflicting updates
Failed updates trigger user notifications
Allows manual conflict resolution

Field-Level Merging

Different fields can be updated by different users
Complex but preserves maximum user input
Requires careful schema design

Performance Optimizations

Delta Compression

Only changed fields are transmitted, not entire records

Batch Processing

Multiple changes combined into single operations

Connection Pooling

Efficient WebSocket connection management

Local Caching

IndexedDB provides instant query performance

Security Considerations

Data Filtering: syncFilter() ensures users only receive authorized data
Write Validation: All client operations validated server-side
Channel Authorization: WebSocket channels require proper authentication
Field Selection: Sensitive fields excluded from synchronization
Tenant Isolation: Automatic multi-tenant data separation

Next: Learn how to implement Chorus in your application with our Getting Started guide.

Overview

Integrations

Core Concepts

Advanced

How Chorus Works

How Chorus Works

Architecture Overview

Core Components

Server-Side Components

Client-Side Components

Change Detection Adapters

1. Eloquent (Default)

2. Postgres: WAL Logical Replication Stream (Future Enhancement)

Synchronization Strategies

Selective Field Sync

Filtered Synchronization

Channel-based Broadcasting

Conflict Resolution

Last-Write-Wins Strategy

Optimistic Locking

Field-Level Merging

Performance Optimizations

Delta Compression

Batch Processing

Connection Pooling

Local Caching

Security Considerations

​How Chorus Works

​Architecture Overview

​Core Components

​Server-Side Components

​Client-Side Components

​Change Detection Adapters

​1. Eloquent (Default)

​2. Postgres: WAL Logical Replication Stream (Future Enhancement)

​Synchronization Strategies

​Selective Field Sync

​Filtered Synchronization

​Channel-based Broadcasting

​Conflict Resolution

​Last-Write-Wins Strategy

​Optimistic Locking

​Field-Level Merging

​Performance Optimizations

Delta Compression

Batch Processing

Connection Pooling

Local Caching

​Security Considerations

How Chorus Works

Architecture Overview

Core Components

Server-Side Components

Client-Side Components

Change Detection Adapters

1. Eloquent (Default)

2. Postgres: WAL Logical Replication Stream (Future Enhancement)

Synchronization Strategies

Selective Field Sync

Filtered Synchronization

Channel-based Broadcasting

Conflict Resolution

Last-Write-Wins Strategy

Optimistic Locking

Field-Level Merging

Performance Optimizations

Security Considerations