Macha
Macha Project
The goal of the architect is to create a shape for the system that recognizes policy as the most essential element of the system while making the details irrelevant to that policy. This allows decisions about those details to be delayed and deferred.
— ©Robert C. Martin
Introduction
The Macha Project is a modular and scalable framework designed specifically for building robust e-commerce apps. Based on Clean Architecture1 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.
Why SVN?
SVN is well-suited for this project as it:
- Allows developers to check out individual modules for isolated development.
- Supports the monorepo structure by treating directories as standalone projects.
The structure ensures both flexibility and scalability, enabling developers to work independently while providing a standardized foundation for building robust customer solutions.
For more details see: Code Repository
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
The Macha Core is designed to remain highly flexible and adaptable, supporting various deployment strategies, including serverless, cloud-based, and traditional approaches. Its core principles ensure deployment style independence, allowing developers to utilize the technologies and tools best suited to their specific project requirements.
At its foundation, Macha Core is built only on general-purpose technologies, ensuring portability and wide compatibility across projects. This approach ensures core functionality is accessible and reusable in any environment or framework.
Core Technologies
For internal layers of the core projects, only the following general-purpose technologies are used:
- Java: A versatile programming language supporting diverse platforms and deployment methods (Read more).
- Apache Maven: A comprehensive build and dependency management tool that simplifies project workflows (Read more).
Developers can extend these core functionalities and apply any additional tools or libraries at the outer layers where project-specific requirements arise.
Extensibility for Target Applications
For outer layers or target project layers, developers are free to integrate any frameworks, languages, or tools appropriate to their application's context, such as:
- Web frameworks (e.g., Spring Boot).
- Front-end technologies (e.g., TypeScript).
- Cloud platforms (AWS, GCP, Azure).
- Any other tools based on project needs.
This modular philosophy allows Macha Core to remain lightweight while providing flexibility for diverse use cases.
Development Tools
To begin developing with Macha Core and its target projects, the following tools are required:
- Version Control: Use SVN, Git-SVN, or equivalent tools for managing source control.
- IDE: Work in your preferred environment, such as Eclipse or any modern IDE.
- PlantUML: For creating system architecture diagrams or detailed designs.
In addition, the following tools should be installed and configured on your development environment:
- Java: Use the Java version specified by your project requirements. While some projects might require Java 8 for backward compatibility, others may leverage newer features available in Java 17 or later. Ensure alignment with the specific project's configurations.
- Apache Maven: Use version 3.9.6 or later for building and managing dependencies.
- Docker Desktop: Required for containerized workflows or testing environments (Download here).
- Node.js: Necessary for front-end development or specific tools required by outer layers (Download here).
Development Practices
When working on a Macha project:
- Focus only on your specific target project. Do not modify the Macha Core—it should always be used as a library or dependency.
- If developing a new application or module, consider:
- Creating the project in a separate repository, linked to the necessary Macha Core dependencies.
- Managing lifecycle and deployment independently, integrating only the libraries and tools necessary for your specific use case.
This decoupled approach ensures that Macha Core remains clean, reusable, and adaptable across various environments while giving developers full control over their tools and frameworks in higher-level layers.
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:
Outermost Layer: Frameworks and Drivers
This is where the details like UI, databases, external interfaces, etc., reside. This layer is kept at the outermost so that changes in this layer least affect the core principles of the application.
Second layer: Interface Adapters
This layer contains code that converts data from the format most convenient for the outer layer to the format most convenient for the inner layers and vice versa (thus acting as an adapter). This includes Controllers, Presenters, and Gateways.
Third layer: Application Business Rules (Use Cases)
This layer encapsulates and implements all of the use cases of the system. This is where the application-specific business rules live, orchestrating the flow of data to and from the entities, and directing those entities to use their critical business rules to achieve the use cases.
Innermost Layer: Enterprise Business Rules (Entities)
Entities encapsulate the most general and high-level rules and policies of the organization. They are least likely to change when something external changes. For example, you would not expect these objects to be impacted by a change to page navigation, or security. They are the business rules that are the least likely to change with changes to external layers.
Principles Behind Clean Architecture:
- Dependency Rule: Source code dependencies can only point inwards. Nothing in an inner circle can know anything at all about something in an outer circle. Furthermore, when crossing the boundaries, the data must cross these boundaries in the most decoupled way possible, typically interfaces or abstract classes.
- Screaming Architecture: A concept promoted by Clean Architecture, suggesting that the structure and names of directories and components should clearly indicate their functionality or domain, rather than which frameworks or tools they utilize.
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.
Anteater
The Anteater is manual interactive test tool (External Accessor).
The main idea of External Accessor is to provide all possible ways of obtaining information and updating the state of the controlled system that developers have. These can be standard interfaces and any legal workarounds or backdoors used by developers.
For more information, please visit: http://ganteater.com.
Maven Configuration
The Macha Project uses Apache Maven as its build tool to manage dependencies and module configurations. When working with SNAPSHOT version artifacts, you need to update your local Maven settings.xml file to include the correct repository configuration for accessing snapshot artifacts.
Add the Following Configuration to settings.xml:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>snapshots</id> <!-- The profile for accessing snapshot versions -->
<repositories>
<repository>
<id>central-snapshots</id>
<url>https://central.sonatype.com/repository/maven-snapshots</url>
<releases>
<enabled>false</enabled> <!-- Disable release versions for this repository -->
</releases>
<snapshots>
<enabled>true</enabled> <!-- Enable snapshot versions -->
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>plugin-snapshots</id>
<url>https://central.sonatype.com/repository/maven-snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>snapshots</activeProfile> <!-- Activate the snapshots profile -->
</activeProfiles>
</settings>
For more detailed information about how to set up multiple repositories in Maven, please visit: Setting up Multiple Repositories.