PANTHER Core Framework¤

Central orchestration engine for PANTHER network protocol testing framework, implementing sophisticated experiment lifecycle management through event-driven architecture and plugin-based extensibility.

Architecture Overview¤

The core module implements a multi-layered architecture combining several design patterns for enterprise-grade scalability and maintainability.

Primary Components¤

ExperimentManager - Central facade orchestrating experiment lifecycle - Event-driven coordination using EventManager + EmitterRegistry - Observer pattern for pluggable monitoring and analysis - Strategy pattern delegating to PluginManager for extensible execution - Context manager pattern for automatic resource cleanup

TestCase - Mixin-composed test execution engine - Six specialized mixins providing modular capability composition - State machine with explicit transitions (PENDING → RUNNING → DONE) - Docker orchestration for multi-service container management - Comprehensive performance metrics and timing collection

Plugin System - Extensible execution backend - Singleton PluginManager with thread-safe initialization - Multi-level caching with TTL for performance optimization - Protocol, service, and environment plugin types - Docker integration with automated container building

Design Philosophy¤

The core architecture employs enterprise-grade patterns for scalability and maintainability:

Event-Driven Architecture: Central event bus coordinates all subsystem communication
Observer Pattern: Pluggable observers for metrics, logging, and analysis
Strategy Pattern: Pluggable algorithms for experiment execution strategies
Facade Pattern: ExperimentManager provides unified interface to complex subsystems
Mixin Composition: Modular capabilities through multiple inheritance

Core Functional Groups¤

PANTHER's core is organized into focused functional groups, each with comprehensive documentation:

Functional Group	Purpose	Documentation
Experiment Engine	Test execution orchestration and lifecycle management	Core experiment coordination
Configuration System	Schema-driven configuration loading and validation	Type-safe YAML configuration
Event System	Event-driven architecture with typed events	Entity-specific event management
Observer Pattern	Event-driven component communication	Decoupled architecture
Metrics System	Performance monitoring and data collection	Comprehensive experiment analysis
Command Processor	Structured command generation and processing	Safe command execution
Reporting System	Automatic experiment report generation	Status summaries and failure analysis
Configuration Validation	Advanced configuration validation and auto-fixing	Protocol-aware port management
CLI Interface	Command-line operations and user interaction	Primary user interface

Module Organization¤

Core Components by Directory¤

Modular Architecture

Each core component is designed to be independent and replaceable. This modular design allows for future enhancements without breaking existing functionality.

panther/core/
├── experiment_manager.py      # Central experiment orchestration
├── experiment_strategy.py     # Test execution strategies
├── events/                   # Event-driven architecture with typed events
│   ├── base/                 # Base event classes and emitters
│   ├── experiment/           # Experiment lifecycle events
│   ├── test/                 # Test execution events
│   ├── service/              # Service management events
│   ├── environment/          # Environment setup/teardown events
│   ├── metrics/              # Metrics collection events
│   ├── step/                 # Test step events
│   ├── assertion/            # Test assertion events
│   └── plugin/               # Plugin lifecycle events
├── metrics/                  # Performance monitoring and data collection
│   ├── metrics_collector.py  # Central metrics collection
│   ├── metrics_exporter.py   # Export to various formats
│   ├── metrics_reporter.py   # Analysis and reporting
│   └── resource_monitor.py   # System resource monitoring
├── command_processor/        # Structured command generation and processing
│   ├── command.py            # Command objects and validation
│   ├── command_builder.py    # Command construction utilities
│   ├── command_processor.py  # Main processing engine
│   └── command_utils.py      # Command utilities and helpers
├── observer/                 # Event-driven communication
│   ├── base/                 # Observer interfaces
│   ├── impl/                 # Observer implementations
│   ├── factory/              # Observer factory pattern
│   ├── management/           # Event and results management
│   └── plugins/              # Observer plugin system
├── docker_builder/           # Container build system (see [Docker Builder README](docker_builder/README.md))
├── test_cases/               # Test framework interfaces
├── results/                  # Result collection and processing
├── reporting/                # Experiment report generation
│   ├── status_collector.py   # Test result aggregation
│   ├── experiment_reporter.py # Report generation engine
│   └── templates/            # Report templates
├── storage/                  # Event and data storage
├── state/                    # State management
├── template/                 # Template rendering system
├── workflow/                 # Workflow tracking
├── outputs/                  # Output aggregation and collection
├── exceptions/               # Framework-specific errors
└── utils/                    # Supporting utilities

panther/config/               # Configuration management
├── core/
│   ├── manager.py            # ConfigurationManager (primary interface)
│   ├── base.py               # BaseConfig (Pydantic + OmegaConf hybrid)
│   ├── models/               # Typed config models (experiment, service, global, ...)
│   ├── mixins/               # Mixin composition for manager capabilities
│   ├── components/           # Validators, builders, loaders, merger
│   └── validators/           # Pydantic validator factories
└── tutorial/                 # Config tutorial helpers

panther/cli_click/            # Click-based CLI
├── core/main.py              # CLI entry point
└── commands/                 # Command implementations (run, config, plugins, ...)

Integration Overview¤

The core systems work together to provide a cohesive framework:

Flow:

CLI processes user commands and loads configurations
Configuration System validates and provides typed configuration
Experiment Engine orchestrates test execution using configuration
Event System provides typed events for all component interactions
Observer Pattern coordinates component communication through events
Command Processor generates and validates execution commands
Metrics System collects performance data throughout execution
Results System collects and processes test outputs (event-driven)
Reporting System generates comprehensive experiment reports automatically

Component Interaction¤

┌─────────────────┐    ┌──────────────┐    ┌─────────────┐
│ Experiment      │───▶│ Event        │───▶│ Observers   │
│ Manager         │    │ System       │    │             │
└─────────────────┘    └──────────────┘    └─────────────┘
         │                       │                 │
         ▼                       ▼                 ▼
┌─────────────────┐    ┌──────────────┐    ┌─────────────┐
│ Command         │    │ Test Cases   │    │ Metrics     │
│ Processor       │    │              │    │ System      │
└─────────────────┘    └──────────────┘    └─────────────┘
         │                       │                 │
         ▼                       ▼                 ▼
┌─────────────────┐    ┌──────────────┐    ┌─────────────┐
│ Plugin          │    │ Docker       │    │ Results     │
│ Manager         │    │ Builder      │    │ Manager     │
└─────────────────┘    └──────────────┘    └─────────────┘

Quick Start¤

Basic Experiment Execution¤

from panther.config.core.manager import ConfigurationManager
from panther.core.experiment_manager import ExperimentManager

# Load and validate configuration
config_manager = ConfigurationManager()
config = config_manager.load_and_validate_config(
    "experiment-config/base/experiment_config_example_minimal.yaml"
)

# Create and run experiment
experiment_manager = ExperimentManager(global_config=config)
experiment_manager.run_tests()

Command Line Usage¤

# Run experiment
panther run --config experiment-config/base/experiment_config_example_minimal.yaml

# Validate configuration
panther config validate --config config.yaml

# List available plugins
panther plugins list

Development Guidelines¤

Extending Core Functionality¤

Follow the Observer Pattern — Use events for component communication
Maintain Type Safety — Use dataclasses and proper type annotations
Plugin Integration — Ensure new features work with the plugin system
Documentation — Update functional group docs for significant changes

Code Organization¤

Single Responsibility — Each module has a clear, focused purpose
Dependency Injection — Components receive dependencies through constructors
Error Handling — Use custom exceptions from panther/core/exceptions/
Testing — Write tests that validate both success and error scenarios

Related Documentation:

Configuration Guide — Complete YAML configuration reference
Plugin Development — Creating framework extensions
Quick Start — Getting started with PANTHER