Skip to content

12-Factor Assessment Tool - Architecture

Overview

The 12-Factor Assessment Tool is designed as a modular, extensible system for evaluating software projects against the 12-Factor App methodology principles.

Directory Structure

12factor-kit/
├── src/                           # Source code
│   ├── twelve-factor-assessment.sh  # Main assessment engine
│   └── lib/                      # Shared libraries
│       ├── colors.sh            # Color definitions and output formatting
│       └── utils.sh             # Utility functions
├── bin/                          # Executable wrappers
│   └── twelve-factor-reviewer   # CLI entry point
├── tests/                        # Test suite
│   ├── test-core-assessment.sh  # Main test suite
│   ├── test-input-validation.sh # Input validation tests
│   ├── test-edge-cases.sh       # Edge case tests
│   ├── test-error-handling.sh   # Error handling tests
│   ├── test-quick-validation.sh # Quick validation tests
│   └── run-comprehensive-tests.sh # Complete test runner
├── docs/                         # Documentation
│   ├── README.md                 # Documentation hub
│   ├── 3-design/                 # Architecture and design
│   ├── 4-development/            # Developer guides
│   └── 5-testing/                # Test documentation
├── config/                       # Configuration files
├── scripts/                      # Helper scripts
│   ├── batch-assessment.sh      # Batch processing
│   ├── coverage-analysis.sh     # Code coverage analysis (bashcov)
│   ├── coverage-summary.sh      # Coverage report display
│   └── test-runner.sh           # Test execution
└── examples/                     # Usage examples

Components

1. Core Assessment Engine (src/twelve-factor-assessment.sh)

The main assessment logic that: - Analyzes project structure - Evaluates each of the 12 factors - Calculates scores - Generates reports

Key Functions:

  • assess_factor_*() - Individual factor assessment functions
  • generate_*_report() - Report generation in various formats
  • calculate_score() - Scoring logic

2. Libraries (src/lib/)

colors.sh

  • Color code definitions
  • Output formatting functions
  • Status symbols

utils.sh

  • File system operations
  • Project detection utilities
  • Common helper functions

3. CLI Wrapper (bin/12factor-assess)

A lightweight wrapper that: - Validates environment - Locates the main script - Passes arguments through

4. Test Suite (tests/)

Comprehensive testing including: - Unit tests for each factor - Integration tests - Performance benchmarks - Mock project generators

Data Flow

flowchart TD
  Input["User Input"] --> CLI["CLI Wrapper"]
  CLI --> Engine["Assessment Engine"]
  Engine --> Factors["Factor Evaluators"]
  Factors --> Scoring["Scoring System"]
  Scoring --> Report["Report Generator"]
  Report --> Output["Output (Terminal / JSON / MD)"]

Assessment Process

  1. Initialization
  2. Parse command-line arguments
  3. Validate project directory

  4. Set configuration options

  5. Project Analysis

  6. Detect project type
  7. Identify technology stack

  8. Scan for configuration files

  9. Factor Assessment

  10. Execute 12 individual factor assessments
  11. Each factor scores 0-10 points

  12. Collect detailed findings

  13. Score Calculation

  14. Sum individual scores
  15. Calculate percentage

  16. Determine compliance grade

  17. Report Generation

  18. Format findings based on output type
  19. Include remediation suggestions
  20. Generate final report

Scoring System

Score Ranges

  • 0-3: Poor compliance
  • 4-6: Fair compliance
  • 7-8: Good compliance
  • 9-10: Excellent compliance

Grade Calculation

  • A+ (90-100%): Excellent 12-Factor Compliance
  • A (80-89%): Very Good Compliance
  • B (70-79%): Good Compliance
  • C (60-69%): Fair Compliance
  • D (50-59%): Poor Compliance
  • F (<50%): Needs Significant Improvement

Extensibility

Adding New Factors

To add a new assessment factor:

  1. Create assessment function in main script: 

    assess_factor_new() {
    local score=0
    local details=""
    local remediation=""

    # Assessment logic here

    FACTOR_SCORES[13]=$score
    FACTOR_DETAILS[13]="$details"
    REMEDIATION_SUGGESTIONS[13]="$remediation"
}

  2. Update the assessment loop

  3. Add to report generation

Adding Language Support

To support a new programming language:

  1. Add detection logic in detect_project_type()
  2. Add dependency file checks in Factor II
  3. Add language-specific patterns throughout

Performance Considerations

  • Uses find with -maxdepth to limit directory traversal
  • Employs early exit strategies for efficiency
  • Caches detection results when possible
  • Targets < 5 second execution time

Security Considerations

  • No external network calls
  • Read-only operations on project files
  • Safe string handling for JSON output
  • Proper input validation

Future Enhancements

  1. Plugin System
  2. Allow custom factor definitions

  3. Support for organization-specific rules

  4. Caching

  5. Cache assessment results

  6. Track improvements over time

  7. Reporting

  8. HTML report generation
  9. Trend analysis

  10. Comparative assessments

  11. Integration

  12. IDE plugins
  13. Git hooks
  14. CI/CD templates