Introduction

The Macha Project is a modular and scalable framework designed specifically for building robust e-commerce apps. Based on Clean Architecture principles, it ensures long-term maintainability, flexibility, and adaptability to evolving business needs. Macha provides essential tools and components for managing key e-commerce functionalities, including product catalogs, user profiles, order processing, payment integrations, and vendor management. With its modular design and reference implementations like apps and MachaOn projects, Macha enables developers to create customizable, cloud-ready e-commerce solutions, making it ideal for businesses of all sizes seeking scalability and reliability.

Project structure

A module should be responsible to one, and only one, actor.

— ©Robert C. Martin

Macha project contains following parts:

• core - it is an aggregator of the core and common modules for creating applications.
• apps - contains assemblies of various sets of target project implementations and is used for end-to-end testing, as well as examples and a reference implementation. The name of Koicha will also be used to name a specific implementation of the application.
• machaOn - (aka Infrastructure) completed variants of demo builds.

People who want to reuse software components cannot, and will not, do so unless those components are tracked through a release process and are given release numbers.

— ©Robert C. Martin

The Macha project is designed as a library to be used in customer projects. To achieve this, we follow a highly modular structure where each module has specific responsibilities and can depend only on the base modules and necessary project or third-party libraries.

We opted for a monorepo structure with a root parent pom.xml to manage all submodules. While a multi-repo approach is technically possible, it introduces challenges in managing and building the project. The monorepo structure simplifies dependencies, builds, and integration.

To manage the repository, SVN is used:

• Developers can checkout specific submodules and work on them independently.

Tech stack

Don’t marry the framework!

There are some frameworks that you simply must marry. If you are using C++, for example, you will likely have to marry STL—it’s hard to avoid. If you are using Java, you will almost certainly have to marry the standard library.

That’s normal — but it should still be a decision. You must understand that when you marry a framework to your application, you will be stuck with that framework for the rest of the life cycle of that application. For better or for worse, in sickness and in health, for richer, for poorer, forsaking all others, you will be using that framework. This is not a commitment to be entered into lightly.

— ©Robert C. Martin

It is very important because Macha Core should support many different way to application deploy. Some deployment styles, such as serverless, require a more strict approach to the libraries and tools used but macha entities and interactor should use anywhare.

For the internal layers core projects we can use only general technology:

• Java
• Apache Maven 3.9.6

For the outer layers and all layers for the target (apps) projects we can use everything we need:

• Spring Boot
• TypeScript
• Cloud (AWS, GCP, Azure)
• and other

Tools:

• SVN or Git-Svn
• Eclipse (or other)
• PlantUML

To start development Macha project you need to install:

• Docker desktop 4.35.1
• Java
• Apache Maven 3.9.6
• Node v19.8.1

You should work only on your project, all other parts of Macha project should be used as libraries. As one of the options for developing a project - this is creating a project in a separate personal repository with dependencies on the necessary Macha projects.

Architecture

Macha project following Clean Architecture rules.

Clean Architecture is a software design philosophy introduced by Robert C. Martin, also known as Uncle Bob. It emphasizes the separation of concerns which divides the software into layers making it easier to manage and maintain. The main goal of Clean Architecture is to produce a system that is independent of frameworks, UI, database, and any external agency. In other words, it aims at creating software that is loosely coupled, highly maintainable, and scalable. Core Concepts of Clean Architecture:

• Independent of Frameworks: The architecture does not rely on the existence of some library of feature-laden software. This allows you to use such frameworks as tools, rather than having to cram your system into their limited constraints.
• Testable: The business rules can be tested without the UI, database, web server, or any other external element.
• Independent of UI: The UI can easily change without changing the rest of the system. A Web UI could be replaced with a console UI, for example, without changing the business rules.
• Independent of Database: You can swap out Oracle or SQL Server for MongoDB, BigTable, CouchDB, or something else. Your business rules are not bound to the database.
• Independent of any external agency: In fact, your business rules simply don’t know anything at all about the outside world.

The Layers of Clean Architecture:

©Robert C. Martin

Benefits of Clean Architecture:

• Improved maintainability due to reduced dependencies across the system.
• Increased developability as different teams can work on separate layers with minimal conflicts.
• Enhanced testability as the business rules and logic can be tested without any external elements.
• Greater flexibility to adapt or replace frameworks and drivers without significant impact on the core system.

Clean Architecture is a part of a broader movement toward more maintainable, scalable, and understandable software, with other similar architectures such as Hexagonal (Ports and Adapters), Onion Architecture, and cqs (Command Query Responsibility Segregation). Each of these architectural styles places an emphasis on separating concerns and reducing dependencies, which are crucial for building enterprise-level apps.

Test

The tests are part of the system, and they participate in the architecture just like every other part of the system does. In some ways, that participation is pretty normal. In other ways, it can be pretty unique.

— ©Robert C. Martin

If you want to get serious about automated tests for your software there is one key concept you should know about: the test pyramid. Mike Cohn came up with this concept in his book Succeeding with Agile. It's a great visual metaphor telling you to think about different layers of testing. It also tells you how much testing to do on each layer.

— ©The Practical Test Pyramid

Development

The Macha project uses an SVN repository to manage its code. This approach was chosen to avoid creating multiple Git repositories, as the project consists of numerous subprojects that are developed and published independently. SVN's ability to treat directories as separate repositories ensures that you can selectively download only the subproject you need, rather than the entire codebase.

If you prefer to work with Git, you can integrate SVN using git-svn. This allows you to perform Git operations while maintaining compatibility with the SVN repository. Example: Cloning a Subproject Using git-svn

$ git svn clone -T . module_scm_url

“module_scm_url” value you can copy from Source Code Management page.

For more details, refer to the documentation on git-svn.