# {Pattern Name}

**Category**: [Architecture | Design | Code | Testing | Deployment]
**Applicable To**: [What types of projects or components this pattern applies to]
**Status**: [Stable | Experimental | Deprecated]

---

## Overview

[Provide a high-level description of what this pattern is and when to use it. Include the problem space it addresses and the general approach it takes.]

**Example**: "The Service Layer Pattern provides a clear separation between business logic and data access, enabling better testability, maintainability, and code reuse across different interfaces (API, CLI, etc.)."

---

## When to Use This Pattern

[Describe the scenarios where this pattern is appropriate:]

✅ **Use this pattern when:**
- Condition 1
- Condition 2
- Condition 3

❌ **Don't use this pattern when:**
- Condition 1
- Condition 2
- Condition 3

**Example**:

✅ **Use this pattern when:**
- You have complex business logic that needs to be shared across multiple interfaces
- You want to isolate business logic from infrastructure concerns
- You need to test business logic independently of data access

❌ **Don't use this pattern when:**
- Your application is very simple with minimal business logic
- You're building a thin wrapper around a database
- The overhead of additional layers outweighs the benefits

---

## Core Principles

[List the fundamental concepts that underpin this pattern:]

1. **Principle 1**: [Description]
2. **Principle 2**: [Description]
3. **Principle 3**: [Description]
4. **Principle 4**: [Description]

**Example**:

1. **Separation of Concerns**: Business logic is isolated from data access and presentation
2. **Single Responsibility**: Each service handles one domain concept
3. **Dependency Injection**: Services receive their dependencies rather than creating them
4. **Interface-Based Design**: Services depend on abstractions, not concrete implementations

---

## Implementation

[Provide detailed implementation guidance with code examples:]

### Structure

[Describe the overall structure of the pattern]

```
directory-structure/
├── component1/
│   └── file1.ext
└── component2/
    └── file2.ext
```

### Code Example

[Provide a complete, working example:]

```typescript
// Example implementation
interface ExampleInterface {
  method(): Promise<Result>;
}

class ExampleImplementation implements ExampleInterface {
  constructor(private dependency: Dependency) {}
  
  async method(): Promise<Result> {
    // Implementation
    return result;
  }
}
```

### Key Components

[Break down the major components:]

#### Component 1: [Name]
[Description and purpose]

```typescript
// Code example for this component
```

#### Component 2: [Name]
[Description and purpose]

```typescript
// Code example for this component
```

---

## Examples

[Provide multiple real-world examples showing different use cases:]

### Example 1: [Use Case Name]

[Description of the scenario]

```typescript
// Complete code example
class ConcreteExample {
  // Implementation
}

// Usage
const example = new ConcreteExample();
const result = await example.doSomething();
```

### Example 2: [Use Case Name]

[Description of the scenario]

```typescript
// Complete code example
```

---

## Benefits

[List the advantages of using this pattern:]

### 1. [Benefit Name]
[Detailed explanation of this benefit and why it matters]

### 2. [Benefit Name]
[Detailed explanation of this benefit and why it matters]

### 3. [Benefit Name]
[Detailed explanation of this benefit and why it matters]

**Example**:

### 1. Testability
Business logic can be tested in isolation without requiring database connections or external services. Mock dependencies can be easily injected for unit testing.

### 2. Reusability
The same business logic can be used across multiple interfaces (REST API, GraphQL, CLI, etc.) without duplication.

### 3. Maintainability
Changes to business logic are centralized in service classes, making the codebase easier to understand and modify.

---

## Trade-offs

[Honestly assess the downsides and limitations:]

### 1. [Trade-off Name]
**Downside**: [Description]
**Mitigation**: [How to minimize this downside]

### 2. [Trade-off Name]
**Downside**: [Description]
**Mitigation**: [How to minimize this downside]

**Example**:

### 1. Additional Complexity
**Downside**: Adds extra layers and files to the codebase, which can feel like over-engineering for simple applications.
**Mitigation**: Only apply this pattern when complexity justifies it. Start simple and refactor to this pattern as needs grow.

### 2. Performance Overhead
**Downside**: Additional function calls and abstractions can add minor performance overhead.
**Mitigation**: In most applications, this overhead is negligible. Profile before optimizing.

---

## Anti-Patterns

[Document what NOT to do - common mistakes and misuses:]

### ❌ Anti-Pattern 1: [Name]

**Description**: [What people do wrong]

**Why it's bad**: [Consequences]

**Instead, do this**: [Correct approach]

```typescript
// ❌ Bad example
class BadExample {
  // What not to do
}

// ✅ Good example
class GoodExample {
  // Correct approach
}
```

### ❌ Anti-Pattern 2: [Name]

[Similar structure as above]

**Example**:

### ❌ Anti-Pattern 1: God Service

**Description**: Creating a single service class that handles all business logic for the entire application.

**Why it's bad**: Violates single responsibility principle, becomes difficult to test and maintain, creates tight coupling.

**Instead, do this**: Create focused services, each handling a specific domain concept.

```typescript
// ❌ Bad: Everything in one service
class ApplicationService {
  createUser() {}
  deleteUser() {}
  createProduct() {}
  deleteProduct() {}
  processPayment() {}
  sendEmail() {}
}

// ✅ Good: Focused services
class UserService {
  createUser() {}
  deleteUser() {}
}

class ProductService {
  createProduct() {}
  deleteProduct() {}
}

class PaymentService {
  processPayment() {}
}
```

---

## Testing Strategy

[Describe how to test code that uses this pattern:]

### Unit Testing
[Approach for unit tests]

```typescript
// Example unit test
describe('ExampleService', () => {
  it('should do something', async () => {
    // Test implementation
  });
});
```

### Integration Testing
[Approach for integration tests]

```typescript
// Example integration test
```

---

## Related Patterns

[Link to related patterns and explain relationships:]

- **[Pattern Name](./pattern-name.md)**: [How it relates]
- **[Pattern Name](./pattern-name.md)**: [How it relates]
- **[Pattern Name](./pattern-name.md)**: [How it relates]

**Example**:
- **[Repository Pattern](./repository-pattern.md)**: Often used together; services use repositories for data access
- **[Factory Pattern](./factory-pattern.md)**: Can be used to create service instances with proper dependencies
- **[Dependency Injection](./dependency-injection.md)**: Essential for implementing this pattern correctly

---

## Migration Guide

[If adopting this pattern in an existing codebase, provide migration steps:]

### Step 1: [Action]
[Detailed description]

### Step 2: [Action]
[Detailed description]

### Step 3: [Action]
[Detailed description]

**Example**:

### Step 1: Identify Business Logic
Review existing code and identify business logic that's currently mixed with data access or presentation code.

### Step 2: Extract to Services
Create service classes and move business logic into them. Start with the most complex or frequently used logic.

### Step 3: Refactor Dependencies
Update calling code to use the new services. Inject dependencies rather than creating them directly.

---

## References

[Link to external resources, papers, books, or articles:]

- [Resource 1](URL): Description
- [Resource 2](URL): Description
- [Resource 3](URL): Description

**Example**:
- [Martin Fowler - Service Layer](https://martinfowler.com/eaaCatalog/serviceLayer.html): Original pattern description
- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html): Related architectural concepts
- [Domain-Driven Design](https://www.domainlanguage.com/ddd/): Context for service design

---

## Checklist for Implementation

[Provide a checklist to ensure proper implementation:]

- [ ] Services are focused on single domain concepts
- [ ] Dependencies are injected, not created internally
- [ ] Business logic is isolated from infrastructure concerns
- [ ] Services have clear, well-documented interfaces
- [ ] Unit tests cover business logic in isolation
- [ ] Integration tests verify end-to-end functionality
- [ ] Error handling is consistent and appropriate
- [ ] Logging provides adequate visibility

---

**Status**: [Current status of this pattern document]
**Recommendation**: [When and how to use this pattern]
**Last Updated**: [YYYY-MM-DD]
**Contributors**: [Names or "Community"]