Update README.md

packages/sync/README.md

@@ -23,19 +23,31 @@ Curious what the install command does? See manual installation below.
 
 First, you need to create a platform, better two. You would be able to sync on the same platform (but different model of course), but that is not the main idea of Sync.
 
+So, let's create platforms.
+
 ![Create Sync Platform](https://github.com/mooxphp/moox/raw/main/art/screenshot/sync-plattform-create.jpeg)
 
+A platform should have a name, a domain (we'll search the IP for you) and a token, that can be generated by the button.
+
 ![List Sync Platforms](https://github.com/mooxphp/moox/raw/main/art/screenshot/sync-plattforms.jpeg)
 
+Now the platforms are created and we can see it in the list and use them for our first Sync.
+
 ## Create Syncs
 
-Then you are able to create a Sync between platforms.
+After creating platforms, you are able to create a Sync between platforms.
 
 ![Create Syncs like this](https://github.com/mooxphp/moox/raw/main/art/screenshot/sync-sync-edit.jpeg)
 
+Choose the Source Platform and Model, the Target Platform and Model and enable Platform Relations, if the model supports it, see [Platform Relations](#platformrelations).
+
 ![List your Syncs](https://github.com/mooxphp/moox/raw/main/art/screenshot/sync-syncs.jpeg)
 
-## The basic flow
+Now you can see your Syncs in the list.
+
+## Key Concept
+
+It is crucial to understand, that Moox Sync is not a two-way sync that simply copies data from A to B. It is a one-way sync from Source to Target, but it is made to be central-managed and it is smart, extensible and secure.
 
 ### SyncPlattformsJob
 
@@ -63,15 +75,7 @@ The SyncListener needs to be activated in Moox Sync Configuration. That should b
 
 The PrepareSyncJob is invoked by the SyncListener. It prepares the data and triggers the `SyncWebhook`.
 
-The PrepareSyncJob supports custom data handling like custom queries, data manipulation, so called Transformers, also available as Transformer Bindings, configured in Moox Sync Configuration.
-
-### Transformer
-
-Transformers are not implemented yet. We recommend using Transformer Bindings instead.
-
-### Transformer Bindings
-
-See how `WpUserTransformer` (in Moox Press) extends `AbstractTransformer` on how to implement a transformer binding. Register your transformer binding in the Moox Sync config.
+The PrepareSyncJob supports custom data handling like custom queries, data manipulation, so called Transformers, also available as Transformer Bindings, configured in Moox Sync Configuration. See [Advanced Usage](#advanced-usage).
 
 ### SyncWebhook
 
@@ -87,11 +91,35 @@ The SyncJob queues the actual sync by using the `SyncService`.
 
 ### SyncService
 
-The Sync writes the data on the Target platform. It supports `Custom SyncHandler`and `PlatformRelations`.
+The Sync writes the data on the Target platform. It supports `Custom SyncHandler`and `PlatformRelations`. See [Advanced Usage](#advanced-usage).
+
+## Advanced Usage
+
+### Transformer
+
+Transformers are not implemented yet. We recommend using Transformer Bindings instead.
+
+### Transformer Bindings
+
+While the (selectable in Sync) Transformer feature is not fully implemented, you can use Transformer Bindings for custom data transformation logic.
+
+To create a custom transformer:
+
+1. Create a new class that extends `AbstractTransformer`.
+2. Implement the `transformCustomFields` method.
+3. Register your transformer in the `transformer_bindings` config.
+
+See `WpUserTransformer` in Moox Press on how to implement a Transformer binding.
 
 ### SyncHandler
 
-See how `WpUserSyncHandler`(in Moox Press) extends `AbstractSyncHandler`on how to implement your own SyncHandler. Register your sync handler in the Moox Sync config.
+For complex models requiring custom sync logic, implement Sync Handlers:
+
+1. Create a new class that extends `AbstractSyncHandler`.
+2. Implement the `syncModel` and `deleteModel` methods.
+3. Register your sync handler in the `sync_bindings` config.
+
+See `WpUserSyncHandler` in Moox Press on how to implement your own SyncHandler.
 
 ### PlatformRelations
 
@@ -102,13 +130,68 @@ Key methods:
 -   `syncPlatformsForModel($model, array $platformIds)`: Syncs the platforms for a given model.
 -   `getPlatformsForModel($model)`: Retrieves the platforms associated with a given model.
 
+#### How to implement PlatformRelations
+
+To implement PlatformRelations, you need to configure the `models_with_platform_relations` in the Moox Sync config. This is a list of models that should have platform relations.
+
+While the relations are automatically added to the model, you may want to add a field to your Filament Resource to manage the platforms for a given record.
+
+```php
+                    Select::make('platforms')
+                        ->label('Platforms')
+                        ->multiple()
+                        ->options(function () {
+                            return \Moox\Sync\Models\Platform::pluck('name', 'id')->toArray();
+                        })
+                        ->afterStateHydrated(function ($component, $state, $record) {
+                            if ($record && class_exists('\Moox\Sync\Services\PlatformRelationService')) {
+                                $platformService = app(\Moox\Sync\Services\PlatformRelationService::class);
+                                $platforms = $platformService->getPlatformsForModel($record);
+                                $component->state($platforms->pluck('id')->toArray());
+                            }
+                        })
+                        ->dehydrated(false)
+                        ->reactive()
+                        ->afterStateUpdated(function ($state, callable $set, $record) {
+                            if ($record && class_exists('\Moox\Sync\Services\PlatformRelationService')) {
+                                $platformService = app(\Moox\Sync\Services\PlatformRelationService::class);
+                                $platformService->syncPlatformsForModel($record, $state ?? []);
+                            }
+                        })
+                        ->preload()
+                        ->searchable()
+                        ->visible(fn () => class_exists('\Moox\Sync\Models\Platform'))
+                        ->columnSpan([
+                            'default' => 12,
+                            'md' => 12,
+                            'lg' => 12,
+                        ]),
+```
+
 ### SyncBackupJob
 
-Not implemented yet.
+Not implemented yet!
+
+The SyncBackupJob runs as a fallback, if the Eloquent listener is disabled or not invoked. It checks for changes in the database and syncs them to the target platform.
 
 ## Security
 
-Platform Token and HMAC.
+Moox Sync implements robust security measures:
+
+### Webhook Authentication
+
+The `WebhookAuthMiddleware` handles this authentication and verification process:
+
+-   The API token authenticates the source platform, so even the very first sync (of platforms) is done securely
+-   After platforms are synced, the platform token provides additional security using HMAC.
+-   The HMAC signature verifies the integrity of the payload.
+-   HTTPS (which you should enforce) protects against man-in-the-middle attacks
+
+In addition, you are able to change the webhook url, so that guessing the webhook url becomes difficult.
+
+### Token Authentication
+
+For API endpoints, Moox Sync uses token-based authentication via the `PlatformTokenAuthMiddleware`. Alternatively, you can use Sanctum to authenticate your API requests.
 
 ## Config