Modernization of Comers, a Multi-Organization E-commerce Platform, to a Microservices Architecture

Contents

• System Context
• Why a Monolith Was the Right Decision 10 Years Ago
• Why Modernization Is Necessary Today
• Transformation Strategy
• Modernization Progress
• Current State
• Current Outcome
• Architecture Showcase

System Context

This project concerns the modernization of Comers, a proprietary online sales management platform available at comers.app, designed and continuously developed by our team for approximately 10 years.

The system was originally built as an internal operational platform supporting a network of online stores operating across multiple European Union countries.

Comers serves as a centralized sales and integration system that is still actively evolving. In addition to classic sales operations, the system now includes increasingly explicit module boundaries, background processing, and the first areas of operational AI support. The platform enables:

• integration of multiple online stores,
• integration with marketplaces (e.g. Amazon, eBay),
• full order lifecycle management,
• carrier integrations and shipping operations,
• inventory and warehouse management,
• returns handling,
• service and warranty workflows,
• product listing management,
• invoice generation,
• operational reporting and analytics,
• translation and handling of message threads,
• operator support when preparing customer replies,
• operational use of AI through explicit contracts and domain tools.

Comers is multi-organization by design. Within a single instance, multiple organizations can operate independently, each with:

• its own sales integrations,
• its own operational configuration,
• its own user structure and permissions.

Within each organization, users operate under different operational roles and access levels.

The platform also automatically sends transactional and operational emails to customers and staff, acting as a central communication hub.

Why a Monolith Was the Right Decision 10 Years Ago

At the time the system was designed:

• microservices architecture was not yet an operational standard for mid-scale platforms,
• container orchestration infrastructure was not widely adopted,
• delivery speed and operational stability were primary goals,
• the operations team needed one cohesive system to manage sales workflows.

Building a modular monolith was a deliberate architectural decision:

• one deployable artifact,
• one shared runtime environment,
• one relational database,
• a simplified deployment model,
• full control over operational flows.

Over the years, that approach proved its business value.

The system was not an experiment. It was a real operational tool supporting sales and logistics at scale.

Why Modernization Is Necessary Today

After a decade of growth, the system reached a natural architectural inflection point. Modernization is no longer only a target plan — some of the new boundaries, background processes, API layers, and AI mechanisms are already running in the active platform runtime.

1. Growing integration density

The platform integrates with:

• online stores,
• marketplaces,
• carriers,
• invoicing systems,
• communication mechanisms.

Over time, integration logic became significantly denser in key domain areas.

Formalizing boundaries became necessary in order to:

• reduce blast radius,
• improve separation of responsibilities,
• enable independent evolution of high-I/O areas.

2. Shared runtime across multiple execution contexts

The system handles:

• interactive HTTP requests,
• batch operations,
• scheduled scripts (cron),
• queue processing.

All of those execution paths use the same application runtime.

Historically, that model was operationally efficient, but it now limits flexibility and scalability.

3. Need for a clear frontend boundary

Originally, the system functioned as a server-rendered operational interface.

Current requirements include:

• introducing a SPA layer,
• separating frontend contracts from domain models,
• establishing a Backend-for-Frontend (BFF) layer.

The BFF is treated as a core part of the architecture, not merely an HTTP adapter.

Transformation Strategy

The modernization effort is being led by the same team that designed and evolved the platform over the past decade.

The approach is evolutionary, not revolutionary.

Phase 1: Boundary formalization

• separating orchestration from state transitions,
• isolating integration adapters,
• introducing explicit contracts between layers.

The priority is structural clarity before physical service extraction.

Phase 2: Extraction of high-I/O domains

Selected domain areas will be extracted into independent services.

Extraction order is based on:

• integration density,
• orchestration complexity,
• change risk and operational impact.

This is the beginning of the move toward a microservices architecture.

Phase 3: Introduction of the BFF layer

Before full SPA migration:

• existing JSON endpoints are being formalized as contract boundaries,
• the BFF layer takes responsibility for response shaping,
• frontend development becomes decoupled from internal domain structures.

Phase 4: Transformation toward a microservices architecture

The target architecture includes:

• domain-oriented independent services,
• dedicated execution contexts,
• separation of batch processing from interactive flows,
• the ability to scale independently.

The transformation is being carried out under live production conditions.

Phase 5: Operational AI support

Originally, AI was treated as a long-term development direction. Today, the first operational AI layer has already been implemented in selected areas, especially communication, translation, reply handling, MCP tools, and the capability gateway.

AI will:

• operate exclusively on explicit contracts,
• generate recommendations and summaries,
• support operational decisions,
• remain an augmentation layer rather than an uncontrolled bypass of system logic.

Key Architectural Decisions

• Modernization while the production system remains active.
• Operational continuity is more important than fast, radical refactoring.
• Boundaries are defined before runtime isolation.
• Extraction order is based on integration density, not folder structure.
• Contracts are established early, before service-level separation.

Modernization Progress (Real Changes)

Modernization is not limited to plans or architectural direction. Key parts of the transformation have already been implemented and are running in the live system.

Work completed so far includes:

• building new domain modules (ebay, messages, listings, shipping, notifications),
• rebuilding the eBay integration (Trading API + REST API) using ports and adapters,
• introducing a message-thread communication model with a dedicated interface,
• extracting the listings module with its own API and ingestion pipeline,
• restructuring carrier integrations (DPD, DHL) into a shared shipping layer,
• introducing a notifications module with its own API and UI,
• adding explicit contracts (ports) and adapters in key areas of the system,
• applying a raw-first ingestion model with reprocessing support,
• moving artifacts (e.g. labels) to object storage as part of a stateless model,
• stabilizing job runtime behavior (DB locks, timeouts, concurrency control),
• cleaning up runtime environment and configuration management (env-based),
• introducing CI/CD pipelines and preparing for containerization,
• refreshing selected parts of the user interface.

Latest stage: contract boundaries, AI, and runtime

In the next phase, modernization moved beyond organizing selected modules inside the monolith. The system started evolving toward a contract-driven architecture in which the legacy application, internal APIs, the Core API layer, AI tools, the gateway, and background processes have increasingly explicit responsibilities.

The most important new areas of work include:

• extracting the activities area through the activities/v1 API, a read model, and the activities_current projection,
• moving activity history toward an append-only audit log without classic record updates or deletes,
• creating a new orders boundary for external order synchronization, eBay Fulfillment data, shipping deadlines, and read access through Core API and MCP,
• extending the messages module with thread and thread-list translation, user language preference, a translation worker, and AI support for suggesting and composing replies,
• extending the existing notifications module with a Core API facade and MCP tools operating in a specific user context,
• implementing the first operational AI layer with separate repositories for the webapp, BFF, ChatKit runtime, MCP, and AI gateway,
• introducing comers-ai-gateway as an internal capability layer for translate.v1 and compose_reply.v1,
• moving runtime definitions into dedicated infrastructure repositories: comers-infra-ai and comers-infra-legacy.

In practice, this means Comers is no longer only a modernized monolith with several new modules. It is an actively evolving operational platform where new features and new types of consumers are connected through explicit contracts instead of direct access to older application logic.

This stage also marks a technology shift for the platform as a whole, not only for the AI layer. The legacy application remains based on PHP/Yii2, while new backend services and future extracted domain microservices are being designed primarily around Node.js / TypeScript / NestJS / Fastify. This includes comers-core-api, the BFF, MCP, the gateway, and planned domain extractions, including orders and messages.

The frontend direction is split intentionally: the main SPA direction remains Angular-based, while selected micro-frontend surfaces, such as the current AI chat UI, can be built with React/Vite. Specialized runtime components, such as ChatKit, may use separate technologies like Python when that better fits their role.

Real AI capabilities at the current stage

In the latest stage, the AI layer stopped being only a future direction. The system now has an operational assistant that uses explicit contracts and controlled domain tools.

The assistant can answer questions based on real system data and perform selected actions. It can read customer message lists and details, notifications, order information, and the activity log. It can also mark messages and notifications as read and move them to the archive.

The messages module is especially important. Comers supports translation of threads, titles, and conversation lists into a selected language, remembers the user’s language preference, and runs translations in the background. AI can suggest a reply to a customer based on the conversation context, as well as improve, structure, and translate a draft prepared by an operator into the customer’s target language.

These features were not added as a loose integration with an AI model. They are embedded in the architecture through comers-ai-webapp, comers-ai-bff, comers-ai-chatkit, comers-ai-mcp, comers-core-api, and comers-ai-gateway. As a result, AI operates through APIs, tools, and capability contracts instead of direct access to legacy models.

Readiness of selected modules for extraction

More and more areas of the system now have their own boundaries, contracts, APIs, read models, ports, adapters, and separate runtime processes. This is especially visible in messages, activities, orders, notifications, shipping, and marketplace integrations.

This means modernization is no longer only about organizing code inside the monolith. Selected modules are increasingly close to technical readiness for extraction into independent services, because new system consumers can use explicit contracts instead of internal legacy models.

Selected Comers platform views

×

UI screenshots from Comers (comers.app) are shown with anonymized data; any visible branding is limited to the Comers product identity.

Full technical change log:

👉 Architecture evolution and modernization log

Current State

The system remains fully operational and continues to evolve. Its current state sits between a modular monolith, a contract-driven architecture, and the first separated runtimes supporting new capabilities.

Modernization is incremental:

• boundaries are being formalized,
• contracts are being strengthened,
• new modules with explicit boundaries are being developed,
• additional extraction candidates are being prepared,
• new layers such as Core API, MCP, BFF, and the AI gateway are being developed as controlled access points to system domains.

Some of the key transformation elements have already been implemented and are described in the section above.

Current Outcome

The project demonstrates:

• responsible modernization of a production system,
• architectural evolution without operational disruption,
• long-term system thinking guided by domain continuity.

This is not a greenfield project or a full rewrite.

It is a production-proven operational platform, Comers (comers.app), being transformed in a controlled, contract-driven way by the same team that designed and operated it from the beginning.

Architecture showcase (GitHub)

This case study describes the context, evolution, and transformation strategy of the system.

If you want to see:

• how the modular monolith is organized today,
• which boundaries have already been identified and formalized,
• how domain extraction toward microservices is being sequenced,
• which architectural decisions and trade-offs are driving the transformation,

we have prepared a dedicated architecture showcase.

The repository includes:

• runtime architecture and execution-context descriptions,
• module and integration mapping,
• a step-by-step modernization model,
• domain boundary analysis,
• operational and evolutionary design assumptions,

without exposing business logic or sensitive data.

👉 Architecture showcase (GitHub)
https://github.com/rocketdeploy-dev/showcase-commerce-platform-modernization