1. Analyze Requirements → Identify components, responsibilities, and boundaries
2. Apply SOLID Principles → Design with SRP, OCP, LSP, ISP, DIP
3. Define Clean Architecture → Establish layers, boundaries, and dependency rules
4. Design Testing Strategy → Plan unit tests, integration tests, and test boundaries
5. Document Decisions → Create Architecture Decision Records (ADRs)

• Refactor legacy code into clean architecture
• Design a new feature with proper separation of concerns
• Review existing architecture for SOLID violations
• Create testable components with clear boundaries
• Document architectural decisions
• Establish dependency injection patterns
• Plan modular design strategies

"Good architecture is a byproduct of good team processes and communication"

• Framework Independence - Business logic doesn't depend on frameworks
• Testability - Architecture enables easy testing
• UI Independence - UI can change without affecting business rules
• Database Independence - Business rules don't know about the database
• External Agency Independence - Business rules don't depend on external services

1. Break down feature into distinct responsibilities
2. Identify core business logic vs infrastructure concerns
3. Recognize cross-cutting concerns (logging, analytics, caching)
4. Map data flow through the system
5. Identify potential architectural boundaries

• What is the core business logic?
• What are the external dependencies (network, database, UI)?
• What needs to be testable in isolation?
• What components might change independently?
• What are the inputs and outputs of each component?

references/modular_design.md

• Each class/module has one reason to change
• Separate business logic from infrastructure
• One responsibility per component

• ❌ A class that loads data AND presents it
• ❌ A view controller that makes network requests
• ❌ A model that knows how to save itself

• ✅ Separate UseCase for business logic
• ✅ Separate Loader for data fetching
• ✅ Separate Presenter for view logic

• Open for extension, closed for modification
• Use protocols/interfaces for abstraction
• Compose behaviors instead of inheritance

// Open for extension via protocols
protocol FeedLoader {
    func load(completion: @escaping (Result<[FeedItem], Error>) -> Void)
}

// Closed for modification - implementations extend behavior
class RemoteFeedLoader: FeedLoader { ... }
class LocalFeedLoader: FeedLoader { ... }
class FallbackFeedLoader: FeedLoader { ... }

• Subtypes must be substitutable for base types
• Contracts must be honored by implementations
• No surprising behavior in substitutions

• Clients shouldn't depend on interfaces they don't use
• Create focused, specific interfaces
• Avoid fat interfaces

// ❌ Fat interface
protocol DataStore {
    func save(_ data: Data)
    func load() -> Data
    func delete()
    func migrate()
    func backup()
}

// ✅ Segregated interfaces
protocol DataSaver {
    func save(_ data: Data)
}

protocol DataLoader {
    func load() -> Data
}

• High-level modules don't depend on low-level modules
• Both depend on abstractions
• Abstractions don't depend on details

// High-level policy
class FeedViewController {
    private let loader: FeedLoader  // Depends on abstraction
    
    init(loader: FeedLoader) {
        self.loader = loader
    }
}

// Low-level detail
class APIFeedLoader: FeedLoader { ... }

references/solid_principles.md

┌─────────────────────────────────────────┐
│          Presentation Layer             │
│    (UI, ViewModels, Presenters)        │
└─────────────────┬───────────────────────┘
                  │ depends on
┌─────────────────▼───────────────────────┐
│         Domain/Business Layer           │
│      (Use Cases, Entities, Rules)      │
└─────────────────┬───────────────────────┘
                  │ depends on
┌─────────────────▼───────────────────────┐
│         Infrastructure Layer            │
│   (Network, Database, Framework Code)  │
└─────────────────────────────────────────┘

1. Use Cases (Interactors)
   • Contain business rules
   • Orchestrate data flow
   • Independent of UI and frameworks
2. Boundaries (Protocols/Interfaces)
   • Define contracts between layers
   • Enable testability and flexibility
   • Invert dependencies
3. Adapters
   • Convert data between layers
   • Implement boundary protocols
   • Handle framework-specific code
4. Composition Root
   • Wire dependencies together
   • Configure the object graph
   • Keep business logic clean

Feature/
├── Domain/
│   ├── UseCases/
│   │   └── LoadFeedUseCase.swift
│   ├── Entities/
│   │   └── FeedItem.swift
│   └── Boundaries/
│       └── FeedLoader.swift
├── Infrastructure/
│   ├── Network/
│   │   └── RemoteFeedLoader.swift
│   └── Cache/
│       └── LocalFeedLoader.swift
└── Presentation/
    ├── Views/
    │   └── FeedViewController.swift
    └── Presenters/
        └── FeedPresenter.swift

references/clean_architecture.md

        ┌──────────┐
        │    UI    │ Few - End to End
        ├──────────┤
        │Integration│ Some - Integration
        ├──────────┤
        │   Unit   │ Many - Fast & Isolated
        └──────────┘

1. Domain Layer Testing (Unit Tests)
   • Test use cases in isolation
   • Mock all dependencies
   • Fast, reliable, independent
2. Infrastructure Layer Testing (Integration Tests)
   • Test adapters with real dependencies
   • Test network, database, etc.
   • May be slower, still valuable
3. Presentation Layer Testing (Unit Tests)
   • Test presenters/view models in isolation
   • Mock use cases and boundaries
   • Verify UI logic without UI framework

• Stubs: Provide canned answers
• Spies: Record calls for verification
• Mocks: Verify behavior expectations
• Fakes: Working implementations for testing

class LoadFeedUseCaseTests: XCTestCase {
    func test_load_deliversItemsOnLoaderSuccess() {
        let (sut, loader) = makeSUT()
        let items = [makeItem(), makeItem()]
        
        expect(sut, toCompleteWith: .success(items), when: {
            loader.complete(with: items)
        })
    }
    
    func test_load_deliversErrorOnLoaderFailure() {
        let (sut, loader) = makeSUT()
        
        expect(sut, toCompleteWith: .failure(anyError()), when: {
            loader.complete(with: anyError())
        })
    }
    
    // MARK: - Helpers
    
    private func makeSUT() -> (sut: LoadFeedUseCase, loader: LoaderSpy) {
        let loader = LoaderSpy()
        let sut = LoadFeedUseCase(loader: loader)
        return (sut, loader)
    }
}

• Test behavior, not implementation
• Test one thing at a time
• Use descriptive test names
• Arrange, Act, Assert pattern
• Extract helper methods for clarity

references/testing_strategies.md

• Enables easy unit testing with test doubles
• Allows runtime composition of different implementations
• Follows Dependency Inversion Principle
• Makes dependencies explicit and clear

• More protocols to maintain
• Requires composition root configuration
• Initial learning curve for team members

1. Service Locator pattern - Rejected due to hidden dependencies
2. Property injection - Rejected due to optional dependencies
3. Concrete types - Rejected due to tight coupling

**Documentation Requirements**:

1. **Architecture Overview**
   - System context diagram
   - Component diagram
   - Layer relationships

2. **Component Documentation**
   - Purpose and responsibilities
   - Dependencies and boundaries
   - Usage examples

3. **Design Patterns Used**
   - Which patterns and why
   - Implementation examples
   - Trade-offs considered

4. **Testing Strategy**
   - What gets tested and how
   - Test organization
   - Mock/stub strategies

**Output**: Complete architectural documentation

**Reference**: See `examples/` for real-world examples

---

• Separate business logic from infrastructure
• Depend on abstractions, not concretions
• Make dependencies explicit through injection
• Write tests for all business logic
• Keep components small and focused
• Document significant decisions
• Use composition over inheritance
• Design for testability from the start

• Let business logic depend on frameworks
• Use singletons for dependency management
• Skip testing because "it's too hard"
• Mix presentation and business logic
• Create god classes with multiple responsibilities
• Couple modules tightly together
• Ignore the Single Responsibility Principle
• Make untestable components

1. Clean Architecture (Recommended)
   • Clear separation of concerns
   • Dependency rule: inward only
   • Framework independence
2. Hexagonal Architecture (Ports & Adapters)
   • Business logic at the center
   • Ports define boundaries
   • Adapters implement ports
3. MVVM (Model-View-ViewModel)
   • Separation of UI and logic
   • Testable view models
   • Data binding support
4. MVC (Model-View-Controller)
   • Traditional separation
   • Can be combined with Clean Architecture
   • Controller as composition root

examples/generic/

1. Start with requirements → Use Cases → BDD scenarios
2. Apply this skill → Architecture → Component design
3. Implement → Following architectural patterns
4. Test → Using defined testing strategy

• Use protocols for abstractions
• Leverage Swift's value types
• Apply Composition Root pattern in AppDelegate/SceneDelegate
• Use dependency injection containers if needed

examples/swift/

• Apply SOLID principles universally
• Use interfaces/traits/protocols depending on language
• Adapt patterns to language features
• Maintain Clean Architecture layers

examples/generic/

references/

• clean_architecture.md - Clean Architecture layers and rules
• solid_principles.md - Detailed SOLID explanations with examples
• design_patterns.md - Common patterns (Adapter, Decorator, Composite, Null Object, etc.)
• null_object_pattern.md - Null Object Pattern in detail with testing examples
• command_query_separation.md - CQS principle for cache design
• dependency_management.md - DI patterns and strategies
• testing_strategies.md - Testing patterns and best practices
• modular_design.md - Module organization and boundaries

examples/

• swift/ - Real implementations from Essential Feed
• generic/ - Language-agnostic examples

1. Component Analysis - Identified components and responsibilities
2. SOLID Review - Applied principles with rationale
3. Architecture Diagram - Layers and dependencies (Mermaid)
4. Testing Strategy - Test structure and coverage plan
5. ADRs - Key decisions documented
6. Implementation Guide - Step-by-step refactoring or implementation plan

• Essential Feed Case Study
• Essential Developer Resources

• 1.0.0 - Initial release with 5-step process