npm package: @johnamuesi/mach-architecture-assessment
Description: MACH architectural principles assessment tool for microservices
Author: John Amuesi
Latest version: 1.1.0

# MACH Architecture Assessment

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

## Installation

```bash
npm install -g mach-architecture-assessment
```

## Quick Start

1. **Initialize configuration** in your project:
```bash
mach-assess init
```

2. **Run assessment** on your components:
```bash
mach-assess assess
```

3. **Generate HTML report**:
```bash
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:

```javascript
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
```bash
# 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
```yaml
# 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.