architecture

Files (2)

• SKILL.md
• repository-pattern.md · patterns/

SKILL.md (first lines)

# Software Architecture

## When to Use

- Designing new systems or features
- Making decisions about code organization
- Refactoring existing code
- Reviewing architectural patterns
- Choosing between different approaches

## Core Principles

### SOLID Principles

| Principle | Description | Violation Sign |
|-----------|-------------|----------------|
| **S**ingle Responsibility | A class should have one reason to change | Class doing too many things |
| **O**pen/Closed | Open for extension, closed for modification | Frequent edits to existing classes |
| **L**iskov Substitution | Subtypes must be substitutable for base types | Checks for specific types in code |
| **I**nterface Segregation | Many specific interfaces over one general | Clients implementing unused methods |
| **D**ependency Inversion | Depend on abstractions, not concretions | Hard-coded dependencies |

### Separation of Concerns

Organize code into distinct layers:

```
┌─────────────────────────────┐
│     Presentation Layer      │  UI, API endpoints, CLI
├─────────────────────────────┤
│      Application Layer      │  Use cases, orchestration
├─────────────────────────────┤
│        Domain Layer         │  Business logic, entities
├─────────────────────────────┤
│    Infrastructure Layer     │  Database, external services
└─────────────────────────────┘
```

**Key rules:**
- Each layer only depends on layers below it
- Domain layer has no external dependencies
- Infrastructure implements interfaces defined in domain

## Design Patterns

### Dependency Injection

Prefer constructor injection for required dependencies:

```python
# Good: Dependencies are explicit and testable
class OrderService:
    def __init__(self, repository: OrderRepository, notifier: Notifier):
        self.repository = repository
        self.notifier = notifier

# Bad: Hidden dependencies, hard to test
class OrderService:
    def __init__(self):
        self.repository = PostgresOrderRepository()
        self.notifier = EmailNotifier()
```

### Repository Pattern

Abstract data access behind a clean interface:

```python
class UserRepository(Protocol):
    def get_by_id(self, user_id: str) -> User | None: ...
    def save(self, user: User) -> None: ...
    def find_by_email(self, email: str) -> User | None: ...
```

### Service Layer

Encapsulate business operations:

```python
class UserService:
    def register(self, email: str, password: str) -> User:
        # Validation
        # Business logic
        # Persistence
        # Side effects (email, events)
```

## Architectural Decisions

### Monolith vs Microservices

**Start with a monolith when:**
- Team is small (< 10 developers)
- Domain is not well understood
- Rapid iteration is needed
- Deployment simplicity is important

**Consider microservices when:**
- Clear bounded contexts exist
- Independent scaling is required
- Different tech stacks needed per service
- Team is large enough to own services

### API Design

**REST conventions:**
- Use nouns for resources: `/users`, `/orders`
- Use HTTP methods correctly: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)
- Return appropriate status codes
- Support filtering, pagination, sorting

**GraphQL considerations:**
- Use for complex, nested data requirements
- When clients need flexibility in queries
- Avoid for simple CRUD operations

### Database Design

**Normalization:**

From nathan-oakes/AI-DLC, MIT.