Ewolucja architektury i log modernizacji

Ten dokument przedstawia szczegółowy, techniczny przebieg modernizacji Comers, platformy commerce opartej o Yii2 i dostępnej pod adresem comers.app.

Opis obejmuje rzeczywiste zmiany wdrożone na systemie produkcyjnym.

To nie jest koncepcja ani redesign —
to realna transformacja działającego systemu, prowadzona iteracyjnie.

Spis treści

• Overview
• Faza: 2026-02
  • 1. Wydzielenie nowych modułów domenowych
  • 2. Przebudowa integracji eBay
  • 3. Moduł wiadomości
  • 4. Moduł listingów
  • 5. Moduł shipping
  • 6. Moduł notyfikacji
  • 7. Porty i adaptery
  • 8. Model raw-first ingestion
  • 9. Stateless + object storage
  • 10. Stabilizacja jobów i runtime
  • 11. Cleanup technologiczny
  • 12. UI
  • 13. CI/CD i delivery
  • 14. Dokumentacja
• Faza: 2026-03 / 2026-05
  • 1. Przejście od modułów do granic kontraktowych
  • 2. Moduł activities i append-only audit log
  • 3. Moduł orders i synchronizacja zamówień zewnętrznych
  • 4. Rozwój modułu messages
  • 5. Rozszerzenie notifications do Core API i MCP
  • 6. Warstwa AI: ChatKit, MCP, Core API i Gateway
  • 7. AI Gateway i capability contracts
  • 8. Separacja runtime i repozytoriów infrastrukturalnych
• Kolejne fazy
• Powiązane

Overview

Pierwotny system stojący za Comers był monolitem opartym o Yii2, odpowiedzialnym za:

• zarządzanie zamówieniami
• integracje marketplace (eBay, Amazon, WooCommerce, Baselinker)
• listingi
• shipping
• faktury i raporty
• przetwarzanie w tle (joby)

Strategia modernizacji zakłada:

• wprowadzanie jawnych granic domenowych
• przebudowę do modularnej architektury
• zastępowanie implicit zależności kontraktami (porty)
• przygotowanie pod stopniową ekstrakcję do mikroserwisów

Faza: 2026-02

1. Wydzielenie nowych modułów domenowych

W systemie zostały zaimplementowane i zarejestrowane nowe moduły:

• ebay
• messages
• listings
• shipping
• notifications

Każdy moduł posiada:

• warstwę aplikacyjną (use case’y)
• warstwę integracyjną
• repozytoria infrastrukturalne
• adaptery
• jasno określony zakres odpowiedzialności

To oznacza przejście z:

„płaskiego monolitu”

do:

„modularnego monolitu z wyraźnymi boundary”

2. Przebudowa integracji eBay

Powstał nowy moduł integracyjny eBay obsługujący:

• eBay Trading API (legacy)
• eBay REST API (nowe)

Wdrożone elementy:

• EbayIntegrationPort (kontrakt aplikacyjny)
• LocalEbayIntegrationAdapter
• HttpEbayIntegrationAdapter
• flow autoryzacji OAuth
• use case’y wymiany tokenów
• use case’y importu listingów
• use case’y integracji wiadomości

Dodatkowo:

• obsługa podłączania i odłączania kont
• obsługa callbacków
• webhook / endpoint account deletion

Efekt:

• logika integracyjna nie jest już osadzona bezpośrednio w modelach domenowych
• wyraźna separacja pomiędzy systemem a zewnętrznym providerem
• gotowość do wydzielenia jako osobny serwis

3. Moduł wiadomości (warstwa konwersacyjna)

Nowy moduł messages wprowadza:

• model wątków (threads)
• obsługę konwersacji
• dedykowany UI
• endpointy REST API

Funkcjonalności:

• lista wątków
• pobieranie wiadomości w wątku
• wysyłanie odpowiedzi
• oznaczanie jako przeczytane
• archiwizacja / przywracanie
• resync i reprocess

Architektura:

• MessagesChannelPort
• adapter eBay dla wiadomości
• repozytorium raw payloadów
• repozytorium domenowe
• use case’y dla sync, read, reply i reprocess

Efekt:

• komunikacja staje się pełnoprawnym obszarem domenowym
• koniec rozproszonej logiki wiadomości
• przygotowanie pod obsługę multi-channel

4. Moduł listingów

Nowy moduł listings obejmuje:

• dedykowaną warstwę API
• endpointy importu / upsert / reprocess
• linkowanie produktów
• przepływ ingestii danych zewnętrznych

Elementy architektury:

• registry providerów źródeł
• repozytorium payloadów zewnętrznych
• serwisy ingestii
• separację danych źródłowych od modelu domenowego

Efekt:

• listingi nie są już ściśle sprzężone z integracjami
• jasna ścieżka do wydzielenia logiki marketplace
• lepsza kontrola nad cyklem życia ingestii danych

5. Moduł shipping (DPD, DHL)

Nowy moduł shipping zawiera:

• ShippingIntegrationPort
• adaptery lokalne i HTTP
• dispatcher tworzenia etykiet
• architekturę opartą o providerów

Obsługiwani providerzy:

• DPD
• DHL

Efekt:

• spójna warstwa integracji kurierskich
• uproszczone dodawanie nowych providerów
• eliminacja rozproszonej logiki shippingowej

6. Moduł notyfikacji

Moduł notifications zapewnia:

• listę notyfikacji
• liczniki
• read / read-all
• archive / unarchive
• usuwanie

Zawiera:

• własny UI
• endpointy REST API

Efekt:

• komunikacja systemowa została uporządkowana
• fundament pod alerty i sygnalizację operacyjną
• separacja od workflow biznesowych

7. Porty i adaptery (kluczowa zmiana)

W systemie wdrożono:

• porty aplikacyjne (interfejsy / kontrakty)
• adaptery infrastrukturalne (local / HTTP)
• orkiestrację opartą o use case’y
• abstrakcję repozytoriów

Przykłady:

• EbayIntegrationPort
• MessagesChannelPort
• ShippingIntegrationPort

Efekt:

• przejście z implicit architektury do jawnej
• mocny fundament pod ekstrakcję usług
• lepsza testowalność i utrzymywalność

8. Model raw-first ingestion

Wprowadzono podejście:

• zapisu danych zewnętrznych jako raw payloadów
• oddzielenia fetch od przetwarzania domenowego
• wdrożenia możliwości reprocessingu

Dotyczy:

• listings
• messages

Efekt:

• większa odporność na błędy integracji
• możliwość replay i debugowania przepływów danych
• brak zależności od jednorazowego przetwarzania

9. Stateless + object storage

System przeszedł częściowo na model stateless:

• etykiety kurierskie → object storage (zgodne z S3)
• raporty → artefakty pobierane przez signed URL
• lokalny filesystem → wyłącznie tymczasowy workspace

Efekt:

• usunięcie zależności od trwałego storage lokalnego
• gotowość na środowiska kontenerowe / rozproszone
• zgodność z nowoczesnym, cloud-native modelem storage

10. Stabilizacja jobów i runtime

Nowy model jobów:

• kontenery jobowe oparte o Dockera
• współdzielony wrapper runtime
• MySQL advisory locks (distributed locking)
• timeouty
• structured logging
• jitter (przy starcie i iteracji)

Efekt:

• eliminacja duplikacji wykonań
• mniej race conditions
• większa obserwowalność
• bezpieczniejsze przetwarzanie wsadowe

11. Cleanup technologiczny

Środowisko runtime zostało zaktualizowane i ustabilizowane:

• upgrade do PHP 8.1 (z przygotowaniem pod nowsze wersje)
• konfiguracja oparta o .env
• usunięcie hardcoded credentials / danych konfiguracyjnych
• uporządkowanie zależności

Efekt:

• nowocześniejsze środowisko wykonawcze
• mniej długu technicznego
• większa spójność procesu deploymentu

12. UI

Nowe UI zostało wdrożone dla:

• modułu messages
• modułu notifications

Dodatkowo:

• uproszczono wybrane legacy widoki
• częściowo uporządkowano strukturę frontendową

Efekt:

• lepsza użyteczność dla użytkowników operacyjnych
• bardziej spójne wzorce interakcji
• przygotowanie gruntu pod przyszłą architekturę SPA / BFF

13. CI/CD i delivery

Proces delivery został usprawniony przez:

• pipeline’y CI
• wersjonowane release’y
• buildy obrazów kontenerowych
• uporządkowane środowiska runtime

Efekt:

• powtarzalne deploymenty
• lepszą kontrolę nad release’ami
• przygotowanie pod skalowalne środowiska

14. Dokumentacja

Modernizacja jest wspierana przez:

• dokumentacja techniczna
• notatki architektoniczne
• specyfikacje runtime
• planowanie migracji

Ten log będzie rozszerzany o kolejne fazy.

Faza: 2026-03 / 2026-05

1. Przejście od modułów do granic kontraktowych

Po pierwszej fazie porządkowania wybranych modułów modernizacja przesunęła się w stronę szerszej architektury kontraktowej.

Coraz więcej obszarów systemu nie jest już tylko wydzielonym folderem lub modułem wewnątrz monolitu. Wybrane domeny otrzymały własne API, read modele, porty, adaptery, procesy tła oraz warstwy pośrednie dla nowych konsumentów.

W praktyce oznacza to, że nowe elementy systemu mogą korzystać z jawnych kontraktów zamiast bezpośrednio odwoływać się do starszych modeli, kontrolerów lub tabel legacy.

Efekt:

• większa separacja odpowiedzialności
• większa gotowość wybranych modułów do wydzielenia
• możliwość podłączania nowych konsumentów, takich jak Core API, MCP i AI, bez obchodzenia granic domenowych
• mocniejszy fundament pod przyszłą ekstrakcję do mikroserwisów

2. Moduł activities i append-only audit log

Obszar activities został wydzielony jako osobny moduł odczytowy z API activities/v1.

Wdrożone elementy:

• lista aktywności
• szczegóły aktywności
• endpoint filtrów
• model odczytu
• mapowanie starych payloadów legacy do jawnych DTO
• ograniczanie dostępu na podstawie kontekstu sprzedawcy
• przeniesienie odczytu historii operacji za granicę modułu

Następnie storage aktywności został przebudowany w kierunku append-only.

Zamiast traktować historię operacji jak zwykłe, modyfikowalne rekordy, system zaczął używać modelu opartego o zapis zdarzeń i projekcję aktualnego stanu (activities_current).

Efekt:

• activity log stał się bezpieczniejszym audit trailem
• aktualizacje i usuwanie aktywności zostały zablokowane
• stare dane są normalizowane za warstwą modułu
• obszar jest przygotowany do dalszego użycia przez API, AI i przyszłe usługi

3. Moduł orders i synchronizacja zamówień zewnętrznych

Powstał nowy boundary orders, który porządkuje synchronizację i odczyt zamówień zewnętrznych.

Wdrożone elementy:

• append-only fundament synchronizacji zamówień
• port providerów zewnętrznych
• śledzenie przebiegów synchronizacji
• zapis raw payloadów z systemów zewnętrznych
• snapshoty zamówień i pozycji zamówień
• external references
• current-state read modele
• internal API orders/v1
• read-only boundary w comers-core-api
• narzędzia MCP dla zamówień
• osobny job synchronizacji zamówień zewnętrznych w runtime legacy

Szczególnie istotna była rozbudowa integracji eBay w stronę Sell Fulfillment API oraz obsługa danych związanych z terminami wysyłki.

Efekt:

• zamówienia zewnętrzne mają bardziej trwały i audytowalny model danych
• synchronizacja nie opiera się wyłącznie na jednorazowym pobraniu najnowszych rekordów
• dane o wysyłce i pilności mogą być używane przez API oraz AI
• moduł orders stał się jednym z najważniejszych kandydatów do dalszego wydzielenia

4. Rozwój modułu messages: tłumaczenia i odpowiedzi wspierane AI

Moduł messages został rozszerzony z obszaru synchronizacji i obsługi wątków w kierunku wielojęzycznego, wspieranego przez AI centrum komunikacji.

Wdrożone elementy:

• tłumaczenie pojedynczych wątków
• tłumaczenie list wątków
• tłumaczenie tytułów i treści wiadomości
• zapamiętywanie preferowanego języka tłumaczeń użytkownika
• worker tłumaczeń działający w tle
• integracja z comers-ai-gateway
• endpoint kontekstu kompozytora odpowiedzi
• sugerowanie draftu odpowiedzi na podstawie wątku
• poprawianie i komponowanie odpowiedzi na podstawie draftu użytkownika
• tłumaczenie odpowiedzi na docelowy język klienta
• zachowanie osobnego, jawnego flow wysyłania odpowiedzi

AI nie zostało podłączone bezpośrednio do widoku lub bazy danych. Tłumaczenia i generowanie odpowiedzi przechodzą przez use case’y, adaptery oraz capability gateway.

Efekt:

• operatorzy mogą obsługiwać wiadomości klientów w wielu językach
• AI pomaga przygotować odpowiedź, ale nie zastępuje jawnego procesu wysyłki
• tłumaczenia mogą działać jako proces tła
• komunikacja z klientami stała się jednym z pierwszych realnych obszarów AI-assisted operations w Comers

5. Rozszerzenie notifications do Core API i MCP

Moduł notifications istniał już w poprzedniej fazie modernizacji.

W tej fazie został rozszerzony o integrację z warstwą Core API oraz narzędziami MCP.

Wdrożone elementy:

• fasada notyfikacji w comers-core-api
• narzędzia MCP do listowania notyfikacji
• odczyt szczegółów notyfikacji
• oznaczanie notyfikacji jako przeczytane
• archiwizacja notyfikacji
• operacje zbiorcze
• przekazywanie zaufanego kontekstu użytkownika (X-Internal-User-Id)

Efekt:

• notyfikacje mogą być obsługiwane przez asystenta AI bez bezpośredniego dostępu do legacy
• operacje są wykonywane w kontekście konkretnego użytkownika
• istniejący moduł został rozszerzony o nowe typy konsumentów

6. Warstwa AI: ChatKit, MCP, Core API i Gateway

W systemie powstała pierwsza realna warstwa operacyjnego wsparcia AI.

Wdrożone elementy:

• comers-ai-webapp
• comers-ai-bff
• comers-ai-chatkit
• comers-ai-mcp
• comers-ai-gateway
• lokalny runtime ChatKit
• historia wątków rozmów
• streaming odpowiedzi
• narzędzia MCP dla messages, notifications i orders
• integracja MCP z comers-core-api
• capability gateway dla operacji AI

Asystent AI potrafi dziś korzystać z wybranych danych i akcji systemu przez jawne narzędzia domenowe.

Może między innymi:

• czytać listy i szczegóły wiadomości
• czytać notyfikacje
• czytać informacje o zamówieniach
• korzystać z danych activity logu
• oznaczać wiadomości i notyfikacje jako przeczytane
• archiwizować wiadomości i notyfikacje
• wspierać przygotowywanie odpowiedzi do klientów

Kluczową decyzją architektoniczną jest to, że AI nie omija granic aplikacji.

Ścieżka wykonania opiera się na kontraktach:

AI / ChatKit
→ MCP
→ Core API
→ wewnętrzne API i moduły legacy

Efekt:

• AI działa jako kontrolowany konsument systemu
• narzędzia są ograniczone do jawnie udostępnionych capability
• wrażliwe operacje są wykonywane w kontekście użytkownika
• powstała podstawa do dalszego rozwijania agentic operations bez destabilizowania legacy

7. AI Gateway i capability contracts

comers-ai-gateway został wprowadzony jako wewnętrzna warstwa capability dla operacji AI.

Wdrożone capability:

• translate.v1
• compose_reply.v1

Gateway odpowiada za:

• ukrycie szczegółów integracji z providerem AI
• wymuszanie struktury odpowiedzi
• obsługę OpenAI Responses API
• trwałe operacje dla tłumaczeń
• idempotentne tworzenie operacji
• odczyt statusu operacji
• background polling przez osobny kontener runtime

Efekt:

• aplikacja nie zależy bezpośrednio od surowego API providera AI
• długotrwałe operacje tłumaczeń mogą być obsługiwane poza request-response UI
• capability AI mają własne kontrakty i mogą ewoluować niezależnie
• gateway stał się miejscem dla kolejnych kontrolowanych funkcji AI

8. Separacja runtime i repozytoriów infrastrukturalnych

Runtime został wyraźniej oddzielony od kodu aplikacji.

Powstały lub zostały uporządkowane repozytoria:

• comers-infra-ai
• comers-infra-legacy

comers-infra-ai obejmuje runtime dla:

• AI webapp
• BFF
• MCP
• AI gateway
• gateway pollera
• ChatKit runtime

comers-infra-legacy obejmuje runtime legacy jako zestaw kontenerów:

• aplikacja
• web
• joby cykliczne
• synchronizacja zamówień zewnętrznych
• synchronizacja wątków wiadomości
• worker tłumaczeń wiadomości

Ważnym elementem tej fazy jest też stopniowe przejście do architektury poliglotycznej.

Legacy nadal działa w stacku PHP/Yii2, ale nowe usługi backendowe i przyszłe mikroserwisy domenowe są projektowane głównie w Node.js / TypeScript / NestJS / Fastify. Dotyczy to nie tylko warstwy AI, ale także elementów core systemu, takich jak comers-core-api, oraz planowanych ekstrakcji domen, np. orders i messages.

Warstwa frontendowa jest rozwijana dwutorowo:

• główne SPA pozostaje kierunkiem opartym o Angular,
• wybrane micro-frontendy, takie jak obecny czat AI, mogą być budowane w React/Vite.

Dodatkowo wyspecjalizowane runtime’y mogą używać osobnych technologii, jeżeli lepiej pasuje to do ich roli — przykładem jest Python dla backendowego runtime ChatKit.

Efekt:

• repozytoria aplikacyjne nie są już głównym miejscem definicji produkcyjnego runtime
• procesy tła stały się jawnie opisanymi jednostkami uruchomieniowymi
• łatwiej zarządzać deploymentem, konfiguracją i odpowiedzialnościami poszczególnych usług
• architektura jest bardziej gotowa do dalszej konteneryzacji i wydzielania usług
• nowe capability mogą powstawać w wyspecjalizowanych runtime’ach bez rozbudowywania legacy PHP/Yii2

Kolejne fazy

Planowane obszary dalszej transformacji:

• dalsza ekstrakcja wybranych modułów do osobnych usług
• rozwijanie comers-core-api jako stabilnej warstwy kontraktowej
• rozszerzanie MCP o kolejne narzędzia domenowe
• dalsze wzmacnianie trusted user context dla operacji wykonywanych przez AI
• rozwijanie comers-ai-gateway o kolejne capability
• dalsza separacja integracji marketplace i shipping
• zastąpienie części legacy modelu jobów architekturą event-driven
• głębsza separacja frontendu (SPA / BFF)
• stopniowe przenoszenie kolejnych obszarów do niezależnych runtime’ów

Powiązane

• Główne case study (Comers / comers.app): /case-studies/commerce-platform-modernization
• Architecture showcase (GitHub):
  https://github.com/rocketdeploy-dev/showcase-commerce-platform-modernization

To dokumentuje realną ewolucję Comers, a nie teoretyczny redesign.