Software Patterns Primer

Overview

Architectural patterns solve specific structural problems. This skill provides a decision framework for when to apply each pattern, not a catalog to memorize.

Core philosophy: Patterns solve problems. No problem? No pattern needed.

When to Use This Skill

Activate when:

• Designing a new system or major feature
• Adding external service integrations
• Code becomes difficult to test or modify
• Services start calling each other in circles
• Failures in one component cascade to others
• Business logic scatters across multiple locations

Pattern Hierarchy

Foundational (Apply by Default)

These patterns provide the structural foundation for maintainable systems. Apply unless you have specific reasons not to.

DI quick example — before and after:

# BEFORE: tight coupling, hard to test
class OrderService:
    def __init__(self):
        self.db = PostgresDatabase()       # concrete dependency
        self.mailer = SmtpMailer()         # concrete dependency

# AFTER: dependencies injected, easily testable
class OrderService:
    def __init__(self, db: Database, mailer: Mailer):
        self.db = db
        self.mailer = mailer
# In tests: OrderService(db=FakeDatabase(), mailer=FakeMailer())

Situational (Apply When Triggered)

These patterns address specific problems. Don't apply preemptively.

→ [Foundational Patterns Detail](references/foundational-patterns.md) → [Situational Patterns Detail](references/situational-patterns.md)

Quick Decision Tree

Is code hard to test?
├─ Yes → Apply Dependency Injection
└─ No → Continue

Is business logic scattered?
├─ Yes → Apply Service-Oriented Architecture
└─ No → Continue

Do services know database details?
├─ Yes → Apply Repository Pattern
└─ No → Continue

Do services call each other in cycles?
├─ Yes → Apply Domain Events
└─ No → Continue

Does external API change break your code?
├─ Yes → Apply Anti-Corruption Layer
└─ No → Continue

Does one slow service break everything?
├─ Yes → Apply Circuit Breaker
└─ No → Current patterns sufficient

→ [Complete Decision Trees](references/decision-trees.md)

Implementation Priority

When starting a new system:

1. First: Establish DI container/pattern
2. Second: Define service boundaries (SOA)
3. Third: Add Repository for data access
4. Then: Layer situational patterns as problems emerge

When refactoring existing system:

1. First: Identify the specific pain point
2. Second: Apply the minimal pattern that solves it
3. Third: Validate improvement before adding more

Navigation

Pattern Details

• [Foundational Patterns](references/foundational-patterns.md): DI and SOA implementation guides, when to deviate
• [Situational Patterns](references/situational-patterns.md): Repository, Domain Events, ACL, Circuit Breaker details

Decision Support

• [Decision Trees](references/decision-trees.md): Complete flowcharts for pattern selection
• [Anti-Patterns](references/anti-patterns.md): Common misapplications and how to recognize them
• [Code-Smell Signals](references/code-smell-signals.md): Low-level code smells (large switches, nested loops, parameter reassignment, high complexity/coupling) mapped to the architectural problems they signal and the pattern that fixes each — derived from CAST Highlight _multi quality indicators (https://doc.casthighlight.com/)

Implementation

• [Examples](references/examples.md): Language-agnostic pseudocode for each pattern combination

Red Flags - STOP

STOP when:

• "Let me add all these patterns upfront" → Apply only what solves current problems
• "This pattern is best practice" → Best practice for what problem?
• "We might need this later" → YAGNI - add when needed
• "Service Locator is simpler" → Hidden dependencies cause testing pain
• "I'll just call this service directly" → Consider if events would decouple better
• "External API is stable, no need for ACL" → APIs always change eventually

ALL of these mean: STOP. Identify the specific problem first.

Integration with Other Skills

• test-driven-development: DI enables testability; TDD validates pattern application
• systematic-debugging: Clear boundaries (SOA) simplify debugging
• root-cause-tracing: Well-structured services have clearer call chains

Pattern Combinations

Common effective combinations:

Remember: Patterns exist to solve problems. Start with the problem, not the pattern.