🎯 Hierarchy Framework - Unified Interface¶

Single Header, Complete Framework

Part of the AudioLab Hierarchy Framework (05_01_interfaces).

🎯 Overview¶

The unified interface provides a single-header facade for the entire Hierarchy Framework. Instead of including 8+ different headers, just include one:

#include <audiolab/hierarchy/hierarchy_framework.hpp>

Benefits: - ✅ Simplified API surface - ✅ Consistent naming and behavior - ✅ Coordinated subsystem interactions - ✅ Reduced coupling to internals - ✅ Easier version upgrades

🏗️ Architecture¶

Facade Pattern¶

┌─────────────────────────────────────────────────────────────┐
│          hierarchy_framework.hpp (Public API)               │
│                                                              │
│  ┌────────────────────────────────────────────────────┐    │
│  │         HierarchyFramework (Facade)                │    │
│  │                                                     │    │
│  │  - validate_architecture()                         │    │
│  │  - quick_check()                                   │    │
│  │  - calculate_build_order()                         │    │
│  │  - collect_metrics()                               │    │
│  │  - enforce()                                       │    │
│  │  - generate_report()                               │    │
│  └──────────────┬──────────────────────────────────────┘    │
│                 │                                            │
└─────────────────┼────────────────────────────────────────────┘
                  │
      ┌───────────┴───────────┐
      │                       │
┌─────▼──────┐       ┌────────▼────────┐
│  Internal  │       │    Internal     │
│ Components │       │   Components    │
│            │       │                 │
│ - Rules    │       │ - Patterns      │
│ - Graph    │       │ - Build Order   │
│ - Metrics  │       │ - Enforcement   │
└────────────┘       └─────────────────┘

Key Classes¶

`HierarchyFramework`¶

Main facade class that coordinates all subsystems.

`ArchitectureValidationResult`¶

Unified result structure containing all validation outputs.

📚 Quick Start¶

1. Include the Header¶

#include <audiolab/hierarchy/hierarchy_framework.hpp>

using namespace audiolab::hierarchy;

2. Define Your Architecture¶

std::map<std::string, ModuleMetadata> modules;

// L0 Kernel
ModuleMetadata osc;
osc.name = "Oscillator";
osc.level = ModuleLevel::L0_KERNEL;
modules["Oscillator"] = osc;

// L1 Atom
ModuleMetadata voice;
voice.name = "Voice";
voice.level = ModuleLevel::L1_ATOM;
voice.dependencies = {"Oscillator"};
modules["Voice"] = voice;

// L2 Cell
ModuleMetadata synth;
synth.name = "Synth";
synth.level = ModuleLevel::L2_CELL;
synth.dependencies = {"Voice"};
modules["Synth"] = synth;

3. Validate¶

Simple Validation¶

if (validate(modules)) {
    std::cout << "✅ Valid architecture!\n";
} else {
    std::cout << "❌ Invalid architecture\n";
}

Get Health Score¶

double health = get_health_score(modules);
std::cout << "Health: " << health << "/100\n";

Get Summary¶

std::cout << summary(modules);

4. Comprehensive Analysis¶

HierarchyFramework framework;
auto result = framework.validate_architecture(modules);

std::cout << result.summary();

std::cout << "\nMetrics:\n";
std::cout << "  Overall Health: " << result.overall_health << "/100\n";
std::cout << "  Violations: " << result.rule_violations.size() << "\n";
std::cout << "  Anti-Patterns: " << result.anti_patterns.size() << "\n";
std::cout << "  Good Patterns: " << result.good_patterns.size() << "\n";

🎯 Common Use Cases¶

1. CI/CD Validation¶

#include <audiolab/hierarchy/hierarchy_framework.hpp>

int main(int argc, char** argv) {
    // Load architecture from file
    auto modules = load_architecture("modules.json");

    // Quick check
    if (!validate(modules)) {
        std::cerr << "Architecture validation failed\n";
        std::cerr << summary(modules);
        return 1;
    }

    std::cout << "Architecture validation passed\n";
    return 0;
}

2. Quality Gate with Thresholds¶

HierarchyFramework framework;
auto result = framework.validate_architecture(modules);

// Check thresholds
if (result.overall_health < 70.0) {
    std::cerr << "Health score too low: " << result.overall_health << "\n";
    return 1;
}

if (result.anti_patterns.size() > 0) {
    std::cerr << "Anti-patterns detected\n";
    return 1;
}

std::cout << "Quality gate passed\n";
return 0;

3. Build Order Generation¶

HierarchyFramework framework;

BuildConfig config;
config.max_parallel_jobs = 4;
config.optimize_for_time = true;

auto build_result = framework.calculate_build_order(modules, config);

if (build_result.has_value()) {
    for (const auto& stage : build_result->parallel_stages) {
        std::cout << "Stage (parallel):\n";
        for (const auto& mod : stage.modules) {
            std::cout << "  - " << mod << "\n";
        }
    }
}

4. Metrics Tracking Over Time¶

HierarchyFramework framework;

// Collect snapshots over time
for (int day = 0; day < 30; ++day) {
    auto modules = load_architecture_for_day(day);
    auto snapshot = framework.collect_metrics(modules);
    framework.history().add_snapshot(snapshot);
}

// Check trend
if (framework.history().is_improving(7)) {
    std::cout << "Quality improving over last week!\n";
}

// Generate trend report
std::cout << framework.history().generate_trend_report();

5. Enforcement with Exemptions¶

HierarchyFramework framework(EnforcementPolicy::strict());

// Check enforcement
auto enf_result = framework.enforce(modules);

if (!enf_result.passed) {
    std::cout << "Enforcement failed. Requesting exemption...\n";

    // Request exemption
    auto& exemptions = framework.exemptions();
    std::string ex_id = exemptions.request_exemption(
        "MyModule", "NO_UPWARD_DEPENDENCY",
        "Temporary workaround", "2025-12-31",
        ExemptionType::TEMPORARY
    );

    // Approve (in real system, would be manual)
    exemptions.approve_exemption(ex_id, "Tech Lead");

    std::cout << "Exemption approved: " << ex_id << "\n";
}

6. Complete Report Generation¶

HierarchyFramework framework;

// Generate comprehensive report
std::string report = framework.generate_report(modules);

// Save to file
std::ofstream file("architecture_report.txt");
file << report;
file.close();

// Also generate HTML dashboard
auto snapshot = framework.collect_metrics(modules);
std::string html = MetricsReporter::generate_html_dashboard(snapshot);
std::ofstream("dashboard.html") << html;

🔧 API Reference¶

Convenience Functions¶

`validate()`¶

bool validate(const std::map<std::string, ModuleMetadata>& modules);

Quick validation - returns true if architecture is valid.

Example:

if (validate(modules)) {
    std::cout << "Valid!\n";
}

`get_health_score()`¶

double get_health_score(const std::map<std::string, ModuleMetadata>& modules);

Get overall health score (0-100).

Example:

double health = get_health_score(modules);
std::cout << "Health: " << health << "/100\n";

`summary()`¶

std::string summary(const std::map<std::string, ModuleMetadata>& modules);

Generate summary report.

Example:

std::cout << summary(modules);

HierarchyFramework Class¶

Constructor¶

HierarchyFramework();  // Default (balanced policy)
HierarchyFramework(const EnforcementPolicy& policy);  // Custom policy

`validate_architecture()`¶

ArchitectureValidationResult validate_architecture(
    const std::map<std::string, ModuleMetadata>& modules
);

Comprehensive validation with all checks.

Returns: ArchitectureValidationResult with: - is_valid: Overall validity - rule_violations: Composition rule violations - anti_patterns: Detected anti-patterns - good_patterns: Detected good patterns - metrics: Complete metrics snapshot - overall_health: Health score (0-100)

Example:

HierarchyFramework framework;
auto result = framework.validate_architecture(modules);

if (result.is_valid) {
    std::cout << "Valid! Health: " << result.overall_health << "\n";
}

`quick_check()`¶

bool quick_check(const std::map<std::string, ModuleMetadata>& modules);

Fast validation (rules only).

Example:

if (framework.quick_check(modules)) {
    std::cout << "Basic validation passed\n";
}

`calculate_build_order()`¶

std::optional<BuildOrder> calculate_build_order(
    const std::map<std::string, ModuleMetadata>& modules,
    const BuildConfig& config = BuildConfig{}
);

Calculate build order.

Example:

BuildConfig config;
config.max_parallel_jobs = 4;

auto result = framework.calculate_build_order(modules, config);
if (result.has_value()) {
    // Use result->sequential_order or result->parallel_stages
}

`collect_metrics()`¶

MetricsSnapshot collect_metrics(
    const std::map<std::string, ModuleMetadata>& modules
);

Collect architecture metrics.

Example:

auto snapshot = framework.collect_metrics(modules);
std::cout << "Health: " << snapshot.overall_health_score << "\n";

`enforce()`¶

EnforcementResult enforce(
    const std::map<std::string, ModuleMetadata>& modules
);

Enforce architecture policy.

Example:

auto result = framework.enforce(modules);
if (!result.passed) {
    for (const auto& v : result.blocked_violations) {
        std::cerr << v.description << "\n";
    }
}

`generate_report()`¶

std::string generate_report(
    const std::map<std::string, ModuleMetadata>& modules
);

Generate comprehensive report.

Example:

std::string report = framework.generate_report(modules);
std::ofstream("report.txt") << report;

`exemptions()`¶

ExtendedExemptionManager& exemptions();

Access exemption manager.

Example:

auto& mgr = framework.exemptions();
std::string id = mgr.request_exemption(...);

`history()`¶

MetricsHistory& history();

Access metrics history.

Example:

auto& hist = framework.history();
hist.add_snapshot(snapshot);
double trend = hist.calculate_trend(5);

`set_policy()` / `get_policy()`¶

void set_policy(const EnforcementPolicy& policy);
const EnforcementPolicy& get_policy() const;

Set/get enforcement policy.

Example:

framework.set_policy(EnforcementPolicy::strict());

ArchitectureValidationResult¶

struct ArchitectureValidationResult {
    bool is_valid;
    std::vector<RuleViolation> rule_violations;
    std::vector<AntiPatternInstance> anti_patterns;
    std::vector<PatternInstance> good_patterns;
    MetricsSnapshot metrics;
    double overall_health;

    std::string summary() const;
};

🧪 Testing¶

Build and run the example:

cd build
make complete_workflow
./examples/complete_workflow

Interactive menu with 6 workflows: 1. Basic Validation 2. Comprehensive Analysis 3. Build Order Calculation 4. Metrics Collection & Tracking 5. Enforcement & Exemptions 6. Complete Report Generation

📖 See Also¶

Level Definitions - Hierarchy levels
Validation Engine - Dependency validation
Metrics Collector - Quality metrics
Integration Tests - E2E tests

📜 License¶

Part of the AudioLab project.

Last Updated: 2025-10-10 Maintainer: AudioLab Core Team Status: ✅ Production Ready

🎯 Hierarchy Framework - Unified Interface¶

🎯 Overview¶

🏗️ Architecture¶

Facade Pattern¶

Key Classes¶

HierarchyFramework¶

ArchitectureValidationResult¶

📚 Quick Start¶

1. Include the Header¶

2. Define Your Architecture¶

3. Validate¶

Simple Validation¶

Get Health Score¶

Get Summary¶

4. Comprehensive Analysis¶

🎯 Common Use Cases¶

1. CI/CD Validation¶

2. Quality Gate with Thresholds¶

3. Build Order Generation¶

4. Metrics Tracking Over Time¶

5. Enforcement with Exemptions¶

6. Complete Report Generation¶

🔧 API Reference¶

Convenience Functions¶

validate()¶

get_health_score()¶

summary()¶

HierarchyFramework Class¶

Constructor¶

validate_architecture()¶

quick_check()¶

calculate_build_order()¶

collect_metrics()¶

enforce()¶

generate_report()¶

exemptions()¶

history()¶

set_policy() / get_policy()¶

ArchitectureValidationResult¶

🧪 Testing¶

📖 See Also¶

📜 License¶

`HierarchyFramework`¶

`ArchitectureValidationResult`¶

`validate()`¶

`get_health_score()`¶

`summary()`¶

`validate_architecture()`¶

`quick_check()`¶

`calculate_build_order()`¶

`collect_metrics()`¶

`enforce()`¶

`generate_report()`¶

`exemptions()`¶

`history()`¶

`set_policy()` / `get_policy()`¶