Mach-C Project

machc

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 Mach-C Project is a modular and scalable framework specifically designed for building robust software solutions in Python. Leveraging the principles described in "Clean Architecture: A Craftsman's Guide to Software Structure and Design"1 and "Clean Architectures in Python"2, Mach-C provides long-term maintainability, flexibility, and adaptability for various business needs while ensuring modularity and separation of concerns.

Mach-C provides essential tools and components for managing core functionalities, including reusable entities, interactors, and adapters that developers can further customize for Python-based applications. Mach-C includes reference implementations for applications and MachaOn projects, enabling developers to create customizable, container-ready solutions designed for versatility and scalability.

Project Structure

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

— ©Robert C. Martin

This project adopts Python as its core development language, enabling flexibility, modularity, and scalability in alignment with Machanism principles. However, due to Python’s limitations with packaging, the structure of the Mach-C project differs from its counterpart, Mach-А (Java), and the originally announced multi-module organization.

  1. Root Namespace Limitation:
    Python packaging, via PyPI (Python Package Index), does not natively support a root project naming scheme like @machc/core (as seen in npm.js for JavaScript). This means that Python does not have a direct equivalent for organizing and naming packages under a single root namespace (e.g. @machc).

  2. Namespace Packages as a Solution: To address this limitation, the Mach-C project leverages namespace packages, which allow:

    • Organization and distribution of packages under a shared namespace (e.g. machc.core).
    • Separate installation of internal modules while maintaining a cohesive namespace structure.

  3. Adjusted Structure:
    Due to the lack of native support for a unified root namespace, the project’s directory layout and naming conventions are slightly modified compared to Mach-А (Java). The Mach-C project is structured into the following components:

Core

An aggregator of the core logic and reusable components. It includes entities, interactors, and adapters necessary for creating modular applications.

Apps

This layer contains project-specific assemblies that adapt the reusable core modules for specific workflows. This is the space for examples, reference implementations, and integration testing. One specific implementation is named Goal, serving as an ultimate adaptable reference example.

MachaOn

Also known as the Infrastructure layer, these components represent completed variants of demo builds, combining core logic and application implementations into deployable solutions.

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 Mach-C project adheres to a modular library structure for use in customer projects. This modularity ensures that components are reusable, scalable, and loosely coupled, minimizing dependencies and allowing isolated modification and integration.

Tech Stack

Don’t marry the framework!

— ©Robert C. Martin

Mach-C’s architecture focuses on framework independence for maximum flexibility. The core modules use generic technologies that work across deployment styles, remaining adaptable whether targeting monolithic, microservices, or serverless environments.

Core Tech

  • Python 3.x
  • Tools aligned with Clean Architecture principles (e.g., flask, fastapi).

Outer Layer Components

For the application and infrastructure layers, developers can use any appropriate tools and frameworks:

  • Web Frameworks: Django, Flask, FastAPI.
  • Cloud Services: AWS Lambda, Azure Functions.3 4 5
  • Frontend Technologies: React, Angular, or Vue.js.
  • Database Integrations: PostgreSQL, MongoDB, and more.

Architecture

Mach-C project follows Clean Architecture1 2. Clean Architecture emphasizes modularity, testability, and independence, dividing software into layers to make it easier to scale and maintain.

Core Concepts of Clean Architecture:

  1. Independent of Frameworks: Frameworks are treated as tools, preventing them from dictating the design of the system.
  2. Testable: Business rules can be tested independently of UI, databases, or external elements.
  3. Independent of UI: Swapping the UI with another (e.g., console, web, mobile) does not impact business rules.
  4. Independent of Databases: The ability to change databases without requiring unnecessary modifications to business logic.
  5. Independent of External Agencies: The inner logic is resilient to changes or constraints imposed by external systems.

Layered Architecture in Mach-C:

  1. Outermost Layer (Frameworks and Drivers): UI, database, and infrastructure-specific details reside here.
  2. Interface Adapters: Controllers and gateways convert external data formats into structures usable by the inner layers.
  3. Application Business Rules: Encapsulates use cases and orchestrates entity interactions.
  4. Enterprise Business Rules (Entities): The innermost layer defining reusable and high-level organizational rules and policies.

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.

Unit Test

Unit testing is a cornerstone of the Mach-C project’s commitment to reliability, maintainability, and modularity. By focusing on testing individual components in isolation, developers can ensure the correctness of core business logic and foundational layers, all while catching defects earlier in the development lifecycle.

Mach-C uses pytest, a powerful and versatile testing framework, to simplify the process of writing and executing unit tests. With intuitive syntax, plugin support, and detailed reports, pytest enables developers to deliver high-quality, thoroughly tested Python modules.

For complete information and advanced usage tips, refer to the pytest documentation7.

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.

References

  1. Clean Architecture: A Craftsman's Guide to Software Structure and Design ↩↩

  2. Clean Architectures in Python ↩↩

  3. Building Lambda functions with Python ↩

  4. Create and deploy a HTTP Cloud Function by using Python ↩

  5. Developing RESTful APIs with Python and Flask ↩

  6. Create a local Python pip repository ↩

  7. Full pytest documentation] ↩