S SISL docs
⌕ /
PL
docs  ›  SISL Optima Connector  ›  Architecture

Architecture

The plugin is two processes talking over HMAC-signed HTTP. A third party is the license server on license.sisl.pl which signs responses with Ed25519.

Topology

flowchart LR subgraph SHOP["Magento 2.4.x · PHP 8.2/8.3 + MariaDB"] SO["<b>Sisl_Optima</b><br/>Magento module<br/>admin · cron · observer"] end subgraph WIN["Windows Server · Comarch ERP Optima"] SS["<b>Sisl.Sync.Service</b><br/>.NET 8 Windows Service"] SQL[("SQL Server<br/>CDN_Firma_*")] SS -- "Trusted_Connection" --> SQL end LIC["<b>license.sisl.pl</b><br/>License Server<br/>Ed25519 signing"] SO <== "HMAC-signed REST<br/>GET /v1/products · /v1/stocks<br/>POST /v1/orders" ==> SS SO -. "HTTPS license verify (24h)" .-> LIC SS -. "HTTPS license verify (24h)" .-> LIC classDef shop fill:#15151b,stroke:#d4ad5a,stroke-width:1px,color:#e5e5ec classDef win fill:#15151b,stroke:#6aa6ff,stroke-width:1px,color:#e5e5ec classDef lic fill:#1c1c24,stroke:#7ad6a8,stroke-width:1.5px,color:#e5e5ec class SHOP shop class WIN win class LIC lic

Components

Sisl_Optima (Magento PHP module)

File Responsibility
Service/ProductSync.php fetches /v1/products, upserts to catalog_product_entity
Service/StockSync.php fetches /v1/stocks, writes via StockRegistryInterface
Service/OrderForward.php sends orders to /v1/orders on sales_order_place_after
Service/Diagnostics.php 14 health checks (license, network, perms, cron, drift...)
Service/ProductExclusion.php checks sisl_optima_sync_disabled attribute per product
Model/SyncClient.php HTTP client with HMAC + retry 3x exponential backoff
Model/LicenseChecker.php license verification + 7-day offline grace

Sisl.Sync.Service (.NET 8 ASP.NET Core minimal API)

File Responsibility
Program.cs HTTP endpoints, DI, license gate middleware
Comarch/OptimaSqlClient.cs Dapper queries to CDN.Towary/TwrZasoby/TwrCeny/KntKarty
Auth/HmacAuthMiddleware.cs client signature verification on every /v1/*
Auth/LicenseGuard.cs Ed25519 verification, /v1/* gate (HTTP 402 if invalid)

Security

  1. HMAC-SHA256 on every request/response between Magento and Sisl.Sync.Service. Replay protection via X-SISL-Timestamp with max 300s drift.
  2. Ed25519 asymmetric signing of license server responses. Private key stays on license.sisl.pl only. Plugin has only the public key — cannot forge "valid:true".
  3. Nonce in request → echoed in response → no replay of old responses.
  4. Manifest hash of plugin files — server logs changes, detects cracked installs.
  5. Multi-checkpoint license verification in 5 places (PHP) + 1 (microservice) → editing one callsite isn't enough.

Comarch Optima schema (read-only)

The microservice reads from base tables, not the CDN.TwrKarty view (which requires CDN.RptTemp2):

Table Contains Filter
CDN.Towary products Twr_GIDTyp = 16 (product, not service)
CDN.TwrCeny prices per pricelist TwC_TwCNumer = 1 (retail)
CDN.TwrZasoby actual stock from PZ/PW TwZ_TrSIdDost > 0 (document-backed only)
CDN.TwrIlosci reservations + orders for Reserved and OnOrder
CDN.Magazyny warehouses filter by Mag_Symbol
CDN.KntKarty customers Knt_GIDTyp = 32

Next: Installation →