CtrlK
BlogDocsLog inGet started
Tessl Logo

pantheon-ai/software-design-principles

Apply software design principles across architecture and implementation using deterministic decision workflows, SOLID checks, structural patterns, and anti-pattern detection; use when reviewing designs, refactoring modules, or resolving maintainability and coupling risks.

Does it follow best practices?

Evaluation99%

1.01x

Agent success when using this tile

Validation for skill structure

Overview
Skills
Evals
Files

adapt-anti-corruption-layer.mdreferences/

title:
Build Anti-Corruption Layers for External Systems
impact:
MEDIUM
impactDescription:
protects domain from external model pollution
tags:
adapt, anti-corruption, external, isolation

Build Anti-Corruption Layers for External Systems

When integrating with external systems that have different models, build an anti-corruption layer (ACL) that translates between their model and yours. Never let external concepts pollute your domain.

Incorrect (external model leaks into domain):

// Domain polluted with Stripe's model
public class Order {
    private String id;
    private List<OrderItem> items;
    // Stripe-specific fields in domain
    private String stripeCustomerId;
    private String stripePaymentIntentId;
    private String stripePaymentMethodId;

    public void processPayment(Stripe stripe) {
        // Domain directly calls Stripe
        PaymentIntent intent = PaymentIntent.create(
            PaymentIntentCreateParams.builder()
                .setCustomer(this.stripeCustomerId)
                .setPaymentMethod(this.stripePaymentMethodId)
                .setAmount(this.calculateTotal().cents())
                .setCurrency("usd")
                .build()
        );
        this.stripePaymentIntentId = intent.getId();
    }
}

// If we switch to PayPal, Order must change

Correct (anti-corruption layer isolates external model):

// domain/Order.java - Pure domain, no external concepts
public class Order {
    private OrderId id;
    private CustomerId customerId;
    private List<OrderItem> items;
    private PaymentStatus paymentStatus;

    public Money calculateTotal() {
        return items.stream()
            .map(OrderItem::lineTotal)
            .reduce(Money.zero(), Money::add);
    }

    public void markPaid(PaymentReference reference) {
        this.paymentStatus = PaymentStatus.paid(reference);
    }
}

// domain/ports/PaymentProcessor.java - Domain-defined port
public interface PaymentProcessor {
    PaymentResult charge(CustomerId customer, Money amount);
}

// Domain-defined value objects
public record PaymentResult(PaymentReference reference, PaymentStatus status) {}
public record PaymentReference(String value) {}

// infrastructure/stripe/StripePaymentProcessor.java - ACL
public class StripePaymentProcessor implements PaymentProcessor {
    private final CustomerMappingRepository customerMapping;

    public PaymentResult charge(CustomerId customerId, Money amount) {
        // Translate domain CustomerId to Stripe customer
        String stripeCustomerId = customerMapping.getStripeId(customerId);

        // Call Stripe with their model
        PaymentIntent intent = PaymentIntent.create(
            PaymentIntentCreateParams.builder()
                .setCustomer(stripeCustomerId)
                .setAmount(amount.cents())
                .setCurrency("usd")
                .setConfirm(true)
                .build()
        );

        // Translate Stripe response back to domain model
        return new PaymentResult(
            new PaymentReference(intent.getId()),
            translateStatus(intent.getStatus())
        );
    }

    private PaymentStatus translateStatus(String stripeStatus) {
        return switch (stripeStatus) {
            case "succeeded" -> PaymentStatus.COMPLETED;
            case "processing" -> PaymentStatus.PENDING;
            case "requires_action" -> PaymentStatus.REQUIRES_ACTION;
            default -> PaymentStatus.FAILED;
        };
    }
}

Benefits:

  • Domain model remains clean and business-focused
  • Switch payment providers by implementing new ACL
  • External API changes isolated to ACL

Reference: Anti-Corruption Layer Pattern

Install with Tessl CLI

npx tessl i pantheon-ai/software-design-principles@0.1.4

SKILL-FULL.md

SKILL.md

tile.json