Machc Project

machb

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 Machc 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, Machc provides long-term maintainability, flexibility, and adaptability for various business needs while ensuring modularity and separation of concerns.

Machc provides essential tools and components for managing core functionalities, including reusable entities, interactors, and adapters that developers can further customize for Python-based applications. Machc 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

The Machc 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 Machc 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

Machc’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

Machc 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 Machc:

  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.

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 ↩