Architecture

Velocity's architecture is based on the principles of Hexagonal Architecture (also known as Ports and Adapters). This architectural pattern allows us to isolate the core logic of our application from the devices that send input to it and present output from it. This isolation makes our application more flexible, maintainable, and scalable.

In Hexagonal Architecture, the application is at the center, and it's surrounded by ports. Ports are interfaces that represent a boundary between the application and the outside world. There are two types of ports:

• Primary or Driving ports: These are the interfaces that the application exposes to the outside world. They represent the use cases that the application supports.
• Secondary or Driven ports: These are the interfaces that the application uses to interact with the outside world. They represent the services that the application needs.

Adapters are the implementation of these ports. They translate the application's data and actions to a form that external entities (like databases, web services, or user interfaces) can understand. There are two types of adapters:

• Primary or Driving adapters: These adapters use the primary ports to drive the application. They are usually triggered by an external entity (like a user or an automated system).
• Secondary or Driven adapters: In the context of Velocity, these are referred to as "connectors". They implement the secondary ports and are driven by the application itself to interact with external systems.

Here's a diagram representing the original Hexagonal Architecture:

In Velocity, we have multiple shops, each representing a different e-commerce application. These shops are our core applications. They contain all the client-specific logic and are isolated from external concerns by adapters.

Connectors in Velocity are reusable and composable pieces of code that handle interaction with external systems. They provide a way for our shops to interact with the outside world without being directly coupled to specific technologies or platforms. The secondary ports in Velocity are defined by the "@etribes/connector-contract" package located in packages/connectors/contract.

One way Velocity's architecture differs from the original Hexagonal Architecture is in its handling of the user interface. Currently, the UI is not abstracted as there are no primary adapters. We anticipate that B2C e-commerce will remain web-based for the foreseeable future. However, this might change in the future. For now, we've chosen not to abstract the UI due to the complexity it introduces. Exposing E-Commerce logic via a port can be quite challenging for client applications that are often quite individual, due to the unique requirements of each client.

Here's a diagram representing the Velocity architecture:

This architecture allows us to develop a lot of shops with as much code reuse as possible, while still building very individual e-commerce applications. It provides a clear separation of concerns and makes it easier to test and modify individual parts of the system.

Link to Further Resources

For more information on Hexagonal Architecture, you can refer to the following resources:

• Hexagonal Architecture: Three principles and an implementation example
• Alistair Cockburn's original article on Hexagonal Architecture
• Hexagonal Architecture: What Is It and How Does It Work?

Remember, the key to understanding and effectively using Hexagonal Architecture is practice. As you work more with Velocity and develop new shops and connectors, you'll become more comfortable with this architectural pattern and its benefits.