citrus-cms/resources/views/guide/NAKS_SYNC_SYSTEM.md

NAKS Synchronization & Trigger System Documentation

This document explains the technical architecture and workflow of the NAKS multi-project synchronization system. This system ensures that when a NAKS certificate changes its "Source Project" (ownership), all other project sites are notified and updated automatically.

---

🇹🇷 Türkçe Dokümantasyon

1. Genel Bakış

NAKS Senkronizasyon Sistemi, birden fazla proje sahasında (Web Uygulaması) ortak bir veri havuzunun korunmasını sağlar. Özellikle naks_certificates (Technology) modülünde, bir sertifikanın "Source Project" (Kaynak Proje) alanı değiştiğinde, diğer tüm projelerin bu değişikliği anında öğrenmesi ve verilerini güncellemesi gerekir.

Bu sistem, Event-Driven (Olay Güdümlü) bir yapı kullanır:

1. Kullanıcı bir kaydı düzenler.
2. Sistem değişikliği algılar.
3. Diğer projelere "Senkronizasyon Yap" emri gönderilir.
4. Diğer projeler, güncel veriyi çeker.

2. Mimari Bileşenler

Sistem 4 ana bileşenden oluşur:

A. Observer (Gözlemci)

Dosya: app/Observers/NaksCertificateObserver.php

• Veritabanındaki updated olayını dinler.
• Eğer source_project sütunu değişmişse (örneğin Viksa'dan boş/bu proje'ye geçmişse) tetiklenir.
• TriggerNaksSyncJob'ı kuyruğa (Queue) ekler.

B. Trigger Job (Tetikleyici İş)

Dosya: app/Jobs/TriggerNaksSyncJob.php

• Arka planda (Queue) çalışır.
• Sistemdeki diğer tüm proje URL'lerini (api/project-app-urls) listeler.
• Kendisi hariç diğer tüm projelere POST /api/naks/trigger-sync isteği atar.

C. Endpoint Controller (Karşılayıcı Uç Nokta)

Dosya: app/Http/Controllers/Api/NaksSyncController.php

• Diğer projelerden gelen tetikleme isteklerini karşılar.
• İstek geldiğinde güvenlik kontrolü yapar.
• Gelen isteğe göre NaksSyncService->sync() metodunu çalıştıracak bir işlemi kuyruğa alır.

D. Sync Service (Senkronizasyon Servisi)

Dosya: app/Services/NaksSyncService.php

• Asıl işi yapan servistir.
• Karşı projeye bağlanır, token alır ve verileri (naks_certificates) indirip yerel veritabanını günceller.
• Conflict (Çakışma) yönetimi yapar (timestamp kontrolü).

3. İş Akışı (Workflow)

1. Adım 1: Kullanıcı A Projesinde bir NAKS sertifikasını düzenler ve Source Project alanını değiştirir (örneğin temizler).
2. Adım 2: NaksCertificateObserver bu değişikliği yakalar.
3. Adım 3: Observer, TriggerNaksSyncJob başlatır.
4. Adım 4: Job, Proje B ve Proje C'ye API isteği gönderir: POST .../api/naks/trigger-sync.
5. Adım 5: Proje B isteği alır, doğrular ve kendi kuyruğuna "Senkronizasyon Başlat" emri verir.
6. Adım 6: Proje B, arka planda Proje A'ya bağlanır ve güncellenmiş kaydı kendi veritabanına yazar.

4. Kurulum ve Gereksinimler

• Queue Worker: Sistemin çalışması için Laravel Queue Worker (php artisan queue:work) sunucuda çalışıyor olmalıdır.
• Observer Kaydı: AppServiceProvider içerisinde observer tanımlı olmalıdır.
• Yetkilendirme: .env dosyasında SYNC_ADMIN_EMAIL ve SYNC_ADMIN_PASSWORD tanımlı olmalıdır.

---

🇬🇧 English Documentation

1. Overview

The NAKS Synchronization System maintains a shared data pool across multiple project sites (Web Applications). Specifically for the naks_certificates (Technology) module, when the "Source Project" field of a certificate changes, all other projects must be notified immediately to update their local data.

The system uses an Event-Driven architecture:

1. User updates a record.
2. System detects the change.
3. A "Trigger Sync" command is sent to other projects.
4. Other projects pull the latest data.

2. Architecture Components

The system consists of 4 main components:

A. Observer

File: app/Observers/NaksCertificateObserver.php

• Listens for the database updated event.
• Triggers if the source_project column has changed (e.g., changed from 'Viksa' to empty/this project).
• Dispatches TriggerNaksSyncJob to the queue.

B. Trigger Job

File: app/Jobs/TriggerNaksSyncJob.php

• Runs in the background (Queue).
• Lists all other project URLs via (api/project-app-urls).
• Sends a POST /api/naks/trigger-sync request to all projects except the current one.

C. Endpoint Controller

File: app/Http/Controllers/Api/NaksSyncController.php

• Receives trigger requests from other projects.
• Validates the incoming request.
• Queues a task to run NaksSyncService->sync() based on the trigger.

D. Sync Service

File: app/Services/NaksSyncService.php

• The core service that performs logic.
• Connects to the remote project, authenticates, downloads data (naks_certificates), and updates the local database.
• Handles conflict resolution (via timestamp checks).

3. Workflow

1. Step 1: User modifies a NAKS certificate in Project A and changes the Source Project field.
2. Step 2: NaksCertificateObserver captures this event.
3. Step 3: The Observer dispatches TriggerNaksSyncJob.
4. Step 4: The Job sends an API request to Project B and Project C: POST .../api/naks/trigger-sync.
5. Step 5: Project B receives the request, validates it, and queues a "Start Sync" command locally.
6. Step 6: Project B connects to Project A in the background and updates its local record with the new data.

4. Setup & Requirements

• Queue Worker: A Laravel Queue Worker (php artisan queue:work) must be running on the server for asynchronous processing.
• Observer Registration: The observer must be registered in AppServiceProvider.
• Authentication: SYNC_ADMIN_EMAIL and SYNC_ADMIN_PASSWORD must be configured in the .env file.