MACH Architecture Assessment

A comprehensive assessment tool for evaluating microservices architectures against MACH (Microservices, API-first, Cloud-native, Headless) principles.

Installation

npm install -g mach-architecture-assessment

Quick Start

1. Initialize configuration in your project:

mach-assess init

2. Run assessment on your components:

mach-assess assess

3. Generate HTML report:

mach-assess assess --format html

Assessment Principles

This tool evaluates your microservices against 10 key architectural principles:

1. Design for Autonomous Service Evolution - Independent deployment and development
2. Embrace Observable Resilience - Comprehensive logging, monitoring, and error handling
3. API-First Integration Strategy - Well-defined APIs with proper documentation
4. Security-by-Design Architecture - Built-in security measures and best practices
5. Federated Data Consistency - Distributed data management patterns
6. Progressive Feature Delivery - Feature flags and gradual rollout capabilities
7. Cloud-Native Scalability - Containerization and cloud-ready deployment
8. Configuration-Driven Behavior - Externalized configuration management
9. Graceful Service Degradation - Circuit breakers and fallback mechanisms
10. Continuous Architecture Evolution - Documentation and change management

Configuration

Create a mach-assessment.config.js file in your project root:

export default {
  // Root path where components are located
  componentsPath: './components',

  // Pattern to find component directories
  componentPattern: '*/package.json',

  // Source code patterns to analyze
  sourcePatterns: [
    'src/**/*.ts',
    'src/**/*.js',
    'src/**/*.tsx',
    'src/**/*.jsx'
  ],

  // Assessment configuration
  assessment: {
    enabledPrinciples: [
      'autonomous-evolution',
      'observable-resilience',
      'api-first-integration',
      'security-by-design'
    ]
  },

  // Output configuration
  output: {
    directory: './reports',
    includeMetrics: true,
    includeRecommendations: true
  }
};

Commands

mach-assess init

Creates a configuration file in your project with default settings.

mach-assess assess [options]

Runs the architecture assessment.

Options:

• -p, --path <path> - Project root path (defaults to current directory)
• --format <format> - Output format: json, backstage, detailed, html (default: detailed)

Output Formats

• detailed - Comprehensive JSON report with component scores and recommendations
• backstage - Backstage-compatible format for software catalog integration
• html - Interactive HTML report with filtering and search capabilities
• json - Basic JSON summary report

Report Interpretation

Component Scores

• 85-100: Excellent - Exemplary implementation
• 70-84: Good - Solid implementation with minor improvements needed
• 55-69: Moderate - Acceptable but needs attention
• 0-54: Poor - Requires significant improvement

Recommendations

Each component receives specific recommendations based on failed checks and warnings from the assessment principles.

Examples

Basic Assessment

# Run assessment on current directory
mach-assess assess

# Run on specific project path
mach-assess assess -p /path/to/your/project

# Generate HTML report
mach-assess assess --format html

CI/CD Integration

# GitHub Actions example
- name: Architecture Assessment
  run: |
    npm install -g mach-architecture-assessment
    mach-assess assess --format backstage > architecture-assessment.json

Project Structure

The tool expects your project to follow this structure:

your-project/
├── components/           # Your microservices
│   ├── user-service/
│   │   ├── package.json
│   │   ├── src/
│   │   └── schema.graphql
│   └── product-service/
│       ├── package.json
│       └── src/
├── mach-assessment.config.js
└── reports/             # Generated reports

License

MIT

Contributing

Issues and pull requests are welcome. Please ensure all tests pass before submitting.