# Software Architecture Hexagonal

> Guides the implementation of hexagonal (ports and adapters) architecture, focusing on best practices for decoupling business logic from external concerns.

- Skill: `paulpas/software-architecture-hexagonal` (Agent Skill)
- Install (CLI): `npx skillmds@latest add paulpas/software-architecture-hexagonal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paulpas/software-architecture-hexagonal/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: paulpas (https://skillmd.com/u/paulpas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/paulpas/software-architecture-hexagonal

---






# Hexagonal Architecture

  archetypes: tactical, educational
  anti_triggers: tightly coupled design
  response_profile:
    verbosity: medium
    directive_strength: high
    abstraction_level: tactical

Guides the implementation of hexagonal (ports and adapters) architecture, focusing on best practices for decoupling business logic from external concerns.

## When to Use

- When you need a flexible architecture that accommodates changes easily.
- For applications with complex domain logic.
- When you need to integrate multiple external systems.

## Core Workflow

1. **Define the Domain Model** – Centralize your core domain logic.
2. **Establish Ports** – Create interfaces for external services and applications.
3. **Implement Adapters** – Build adapters to connect the domain to outside technology.

## Implementation Patterns

### Enhanced Examples of Hexagonal Architecture
1. **Core Domain Logic Implementation**:
   ```python
   # Example demonstrating core domain logic separate from infrastructure
   class Account:
       def __init__(self, id, balance):
           self.id = id
           self.balance = balance

   class AccountService:
       def __init__(self, repository):
           self.repository = repository

       def create_account(self, id, initial_balance):
           account = Account(id, initial_balance)
           self.repository.save(account)
   ```

2. **Establishing Ports and Adapters**:
   ```python
   # Defining an Adapter for external service interactions
   class PaymentProcessor:
       def process_payment(self, account_id, amount):
           # Logic to process payment through an external API
           print(f'Processing payment of {amount} for account {account_id}')
   ```

3. **Integration Example**:
   ```yaml
   # Example showing integration with external services via adapters
   payments:
     url: http://payment-service/api
     description: Service to handle payment processing
   ```

### Real-World Applications
- Discuss examples of how organizations like Netflix and Uber implement hexagonal architecture for scalability and maintainability.
- Provide insights into trade-offs between hexagonal architecture and other architectural styles such as layered architecture or microservices.

### Pattern 1: Central Domain Logic

```python
class Product:
    def __init__(self, name, price):
        self.name = name
        self.price = price

class ProductService:
    def add_product(self, product):
        # Add logic for adding the product
        pass

# Adapter example
class ExternalServiceAdapter:
    def call_service(self):
        # Logic to interact with an external service
        pass
```

## Constraints

### MUST DO
- Ensure clear separations of concerns.
- Use automated tests to validate interactions.

### MUST NOT DO
- Allow direct dependencies from the domain to external services.
- Mix external framework concerns with core logic in the same layer.