/designing-architecture

name: designing-architecture
description: Guides software architecture decisions, design patterns, and system design principles. Use when designing systems, choosing patterns, or making architectural decisions.
license: MIT
compatibility: opencode
metadata:
  category: design
  audience: developers

Designing Architecture

Principles and patterns for designing maintainable, scalable, and robust software systems.

When to Use This Skill

• Designing new systems or features
• Choosing between architectural patterns
• Making technology decisions
• Reviewing system design
• Planning for scalability
• Refactoring legacy systems

---

Core Architecture Principles

SOLID Principles

| Principle | Summary | Violation Sign | |-----------|---------|----------------| | **S**ingle Responsibility | One reason to change | Class does too many things | | **O**pen/Closed | Open for extension, closed for modification | Modifying existing code for new features | | **L**iskov Substitution | Subtypes replaceable for base types | Overrides break parent behavior | | **I**nterface Segregation | Small, focused interfaces | Classes implement unused methods | | **D**ependency Inversion | Depend on abstractions | High-level modules depend on low-level |

The Dependency Rule

Outer layers depend on inner layers, NEVER the reverse.

┌─────────────────────────────────────┐
│     Frameworks & Drivers           │  ← Database, Web, UI
├─────────────────────────────────────┤
│     Interface Adapters             │  ← Controllers, Presenters, Gateways
├─────────────────────────────────────┤
│     Application Business Rules     │  ← Use Cases
├─────────────────────────────────────┤
│     Enterprise Business Rules      │  ← Entities
└─────────────────────────────────────┘

Dependencies point INWARD only.

---

Architectural Patterns

Layered Architecture

┌─────────────────────────────────────┐
│     Presentation Layer             │  ← UI, API Controllers
├─────────────────────────────────────┤
│     Application Layer              │  ← Use Cases, Services
├─────────────────────────────────────┤
│     Domain Layer                   │  ← Business Logic, Entities
├─────────────────────────────────────┤
│     Infrastructure Layer           │  ← Database, External APIs
└─────────────────────────────────────┘

**Use when**: Traditional applications, clear separation needed **Avoid when**: High-performance needs, event-driven systems

Hexagonal Architecture (Ports & Adapters)

           ┌───────────────┐
           │   Primary     │
           │   Adapters    │  ← REST API, CLI, GraphQL
           └───────┬───────┘
                   │
        ┌──────────▼──────────┐
        │                     │
        │   ┌───────────┐     │
        │   │   Core    │     │
Primary │   │  Domain   │     │ Secondary
Ports   │   │  Logic    │     │ Ports
        │   └───────────┘     │
        │                     │
        └──────────┬──────────┘
                   │
           ┌───────▼───────┐
           │   Secondary   │
           │   Adapters    │  ← Database, Message Queue, External API
           └───────────────┘

**Use when**: Testability is critical, multiple interfaces needed **Avoid when**: Simple CRUD applications

Microservices Architecture

┌─────────┐  ┌─────────┐  ┌─────────┐
│ Service │  │ Service │  │ Service │
│    A    │  │    B    │  │    C    │
└────┬────┘  └────┬────┘  └────┬────┘
     │            │            │
     └────────────┴────────────┘
                  │
           ┌──────▼──────┐
           │   Message   │
           │    Bus      │
           └─────────────┘

**Use when**: Independent scaling, team autonomy, polyglot needs **Avoid when**: Small teams, simple domains, tight coupling required

Event-Driven Architecture

Event Source → Event Bus → Event Handlers
     │              │              │
     ▼              ▼              ▼
  Produces    Routes Events    Consumes
  Events      (Kafka, RabbitMQ)  Events

**Use when**: Async processing, decoupling, audit trails **Avoid when**: Immediate consistency required, simple workflows

---

Design Patterns

Creational Patterns

| Pattern | Purpose | When to Use | |---------|---------|-------------| | **Factory** | Create objects without specifying class | Object creation logic is complex | | **Builder** | Construct complex objects step-by-step | Many optional parameters | | **Singleton** | Single instance globally | Shared resource (use sparingly) | | **Dependency Injection** | Inject dependencies externally | Testability, loose coupling |

Structural Patterns

| Pattern | Purpose | When to Use | |---------|---------|-------------| | **Adapter** | Convert interface to another | Integrating incompatible systems | | **Decorator** | Add behavior dynamically | Extending functionality without inheritance | | **Facade** | Simplified interface to complex system | Hiding complexity | | **Repository** | Abstract data access | Separating domain from persistence |

Behavioral Patterns

| Pattern | Purpose | When to Use | |---------|---------|-------------| | **Strategy** | Interchangeable algorithms | Multiple ways to do something | | **Observer** | Notify dependents of changes | Event systems, reactive updates | | **Command** | Encapsulate actions as objects | Undo/redo, queuing, logging | | **Chain of Responsibility** | Pass request along handlers | Middleware, validation chains |

---

Domain-Driven Design Concepts

Strategic Design

| Concept | Definition | Example | |---------|------------|---------| | **Bounded Context** | Explicit boundary for a domain model | Order context, Shipping context | | **Ubiquitous Language** | Shared vocabulary between devs and domain experts | "Order", "Line Item", "Fulfillment" | | **Context Map** | How bounded contexts relate | Customer shared between Sales and Support |

Tactical Patterns

| Pattern | Purpose | Example | |-----