README

Academic research implementation of modern software architecture patterns.

A comprehensive study and practical implementation of Clean Architecture, Hexagonal Architecture (Ports & Adapters), and Onion Architecture patterns. This project provides reference implementations, performance benchmarks, architectural analysis, and real-world examples to help developers and researchers understand and apply these patterns effectively.

🎓 Academic Purpose

This project was developed as part of software engineering research to:

• Demonstrate practical implementation of theoretical architecture patterns
• Provide performance benchmarks comparing different architectural approaches
• Offer educational examples for learning advanced software design
• Document best practices and trade-offs in architectural decisions

📚 Architecture Patterns Implemented

1. Clean Architecture (Uncle Bob's Architecture)

• Domain Layer: Pure business logic, framework-independent
• Application Layer: Use cases and application services
• Infrastructure Layer: Framework, database, external services
• Presentation Layer: Controllers, CLI, API endpoints

2. Hexagonal Architecture (Ports & Adapters)

• Domain: Core business logic
• Ports: Interfaces defining contracts
• Adapters: Concrete implementations of ports
• Primary Adapters: Driving the application (HTTP, CLI)
• Secondary Adapters: Driven by application (Database, Email, Cache)

3. Onion Architecture

• Core: Domain models and business rules
• Services: Domain services and business workflows
• Infrastructure: Technical implementations
• Dependency Rule: Inner layers never depend on outer layers

🚀 Features

• Complete Pattern Implementations: Full working examples of each architecture
• Performance Benchmarks: Detailed performance analysis and comparisons
• Architectural Tests: Automated tests to enforce architectural boundaries
• Dependency Analysis: Tools to visualize and validate dependencies
• Real-World Examples: E-commerce domain implementation in each pattern
• Research Documentation: Academic papers and detailed analysis
• UML Diagrams: Visual representations of each architecture
• Migration Guides: How to transition between patterns

📦 Installation

composer require syeedalireza/architecture-patterns-lab

🎯 Quick Start

Clean Architecture Example

use ArchitecturePatternsLab\CleanArchitecture\Application\UseCases\CreateOrder;
use ArchitecturePatternsLab\CleanArchitecture\Domain\Entities\Order;
use ArchitecturePatternsLab\CleanArchitecture\Infrastructure\Repositories\InMemoryOrderRepository;

// Infrastructure (outer layer)
$repository = new InMemoryOrderRepository();

// Application layer (use case)
$createOrder = new CreateOrder($repository);

// Execute use case
$order = $createOrder->execute([
    'customer_id' => '123',
    'items' => [
        ['product_id' => 'p1', 'quantity' => 2, 'price' => 29.99]
    ]
]);

Hexagonal Architecture Example

use ArchitecturePatternsLab\HexagonalArchitecture\Domain\Order;
use ArchitecturePatternsLab\HexagonalArchitecture\Ports\OrderRepository;
use ArchitecturePatternsLab\HexagonalArchitecture\Adapters\PostgresOrderRepository;

// Primary Port (interface)
interface CreateOrderPort
{
    public function create(array $data): Order;
}

// Domain Service implements Port
class OrderService implements CreateOrderPort
{
    public function __construct(private OrderRepository $repository) {}

    public function create(array $data): Order
    {
        $order = new Order($data);
        $this->repository->save($order);
        return $order;
    }
}

// Secondary Adapter (infrastructure)
$repository = new PostgresOrderRepository($pdo);
$orderService = new OrderService($repository);

// Primary Adapter (HTTP Controller)
$order = $orderService->create($_POST);

Onion Architecture Example

use ArchitecturePatternsLab\OnionArchitecture\Core\Order;
use ArchitecturePatternsLab\OnionArchitecture\Services\OrderService;
use ArchitecturePatternsLab\OnionArchitecture\Infrastructure\OrderRepositoryImpl;

// Core domain
$order = Order::create('customer-123');

// Service layer
$orderService = new OrderService(
    new OrderRepositoryImpl()
);

// Execute business workflow
$result = $orderService->placeOrder($order);

📊 Performance Benchmarks

Run benchmarks to compare patterns:

composer benchmark

Sample Benchmark Results

Note: Results may vary based on implementation details and hardware.

🧪 Testing

Run all tests:

composer test

Run with coverage:

composer test-coverage

Architectural Testing

Validate architectural boundaries:

composer architecture

This ensures:

• Domain layer has no framework dependencies
• Dependency rules are enforced
• No circular dependencies exist
• Proper layer isolation

📖 Documentation

Research Papers

• Comparative Analysis of Modern Architecture Patterns
• Performance Implications of Layered Architectures
• Dependency Management in Hexagonal Architecture

Architecture Diagrams

See docs/diagrams/ for:

• UML class diagrams
• Component diagrams
• Sequence diagrams
• Dependency graphs

Detailed Guides

• Clean Architecture Implementation Guide
• Hexagonal Architecture Best Practices
• Onion Architecture Patterns
• Pattern Selection Guide

🔍 Architecture Comparison

🎓 Educational Use

This project is ideal for:

• Students learning software architecture
• Developers wanting to understand advanced patterns
• Architects evaluating pattern trade-offs
• Researchers studying software design
• Teams establishing architectural standards

📈 Use Cases

Each pattern is demonstrated with a complete e-commerce example including:

• Order management
• Product catalog
• User authentication
• Payment processing
• Inventory tracking
• Notification system

🤝 Contributing

Contributions are welcome! This is an academic project, and we value:

• New pattern implementations
• Performance optimizations
• Additional benchmarks
• Documentation improvements
• Bug fixes

Please see CONTRIBUTING.md for details.

📝 Citation

If you use this project in academic research, please cite:

@software{architecture_patterns_lab,
  author = {Alireza Aminzadeh},
  title = {Architecture Patterns Lab: Comparative Study of Modern Software Architectures},
  year = {2024},
  url = {https://github.com/syeedalireza/architecture-patterns-lab}
}

📚 References

• Martin, R. C. (2017). Clean Architecture. Prentice Hall.
• Cockburn, A. (2005). Hexagonal Architecture. Alistair Cockburn Blog.
• Palermo, J. (2008). The Onion Architecture. Programming with Palermo.
• Evans, E. (2003). Domain-Driven Design. Addison-Wesley.
• Vernon, V. (2013). Implementing Domain-Driven Design. Addison-Wesley.

📄 License

The MIT License (MIT). Please see License File for more information.

👨‍🔬 Author

Alireza Aminzadeh

• Email: alireza.aminzadeh@hotmail.com
• GitHub: @syeedalireza
• Research: Research Profile

🙏 Acknowledgments

Special thanks to:

• Robert C. Martin (Uncle Bob) for Clean Architecture
• Alistair Cockburn for Hexagonal Architecture
• Jeffrey Palermo for Onion Architecture
• The DDD community for inspiration

Note: This is a research and educational project. While the implementations are production-quality, they are primarily intended for learning and reference purposes.