architecture-planner

This skill auto-activates when the agent describes:

• "Plan component architecture for..."
• "Design module structure with..."
• "Separate concerns into layers..."
• "Structure the codebase with..."
• "Organize components using..."
• "Define interfaces between..."
• "Create extension points for..."
• "Apply architectural pattern..."

1. Component Identification and Boundaries

What it provides:

• Identification of distinct components based on responsibilities
• Clear component boundaries following Single Responsibility Principle
• Component naming conventions and file organization
• Determination of component granularity (not too large, not too small)

Guidance:

• Each component should have ONE primary responsibility
• Components should be independently testable
• Components should have minimal coupling with others
• Use descriptive names that reflect the component's purpose

Example:

```python

# Good: Clear, focused components

components = [

{

"name": "FeatureProcessor",

"responsibility": "Process feature requests according to business rules",

"file": "src/core/processor.py"

},

{

"name": "DataValidator",

"responsibility": "Validate input data against schemas",

"file": "src/core/validator.py"

},

{

"name": "ResultFormatter",

"responsibility": "Format processing results for output",

"file": "src/core/formatter.py"

}

]

# Bad: Too broad, multiple responsibilities

components = [

{

"name": "FeatureHandler",

"responsibility": "Process, validate, format, store, and log features",

"file": "src/feature_handler.py" # Too many responsibilities!

}

]

```

2. Layer Separation (Presentation, Business, Data)

What it provides:

• Three-layer architecture design
• Clear separation between concerns
• Dependencies flow from outer layers (presentation) to inner layers (business logic)
• Data layer abstraction through repositories or adapters

Layer Definitions:

Presentation Layer (Interfaces):

• CLI interfaces
• REST API endpoints
• GraphQL resolvers
• Event handlers
• External system interfaces

Business Layer (Core):

• Business logic and rules
• Domain models and entities
• Service orchestration
• Use cases and workflows
• Validation logic

Data Layer (Implementations):

• Database adapters
• External service clients
• File system operations
• Caching mechanisms
• Data access repositories

Example:

```python

# Layered Architecture Structure

architecture = {

"presentation_layer": {

"location": "src/interfaces/",

"components": [

"src/interfaces/cli/commands.py",

"src/interfaces/api/routes.py",

"src/interfaces/api/schemas.py"

],

"dependencies": ["business_layer"]

},

"business_layer": {

"location": "src/core/",

"components": [

"src/core/processor.py",

"src/core/validator.py",

"src/core/models.py",

"src/core/services.py"

],

"dependencies": ["data_layer (via interfaces)"]

},

"data_layer": {

"location": "src/adapters/",

"components": [

"src/adapters/database.py",

"src/adapters/external_api.py",

"src/adapters/file_storage.py"

],

"dependencies": ["external systems"]

}

}

```

3. Dependency Injection Patterns

What it provides:

• Constructor injection for required dependencies
• Property injection for optional dependencies
• Interface-based dependency injection
• Dependency inversion principle application
• Mock-friendly architecture for testing

Benefits:

• Testability: Easy to inject mocks and test doubles
• Flexibility: Change implementations without modifying client code
• Decoupling: Components depend on abstractions, not concretions

Example:

```python

# Good: Dependency Injection

from abc import ABC, abstractmethod

from typing import Protocol

# Define interface (abstraction)

class IDataRepository(Protocol):

async def save(self, data: dict) -> bool:

...

async def retrieve(self, id: str) -> dict:

...

# Business logic depends on interface

class FeatureProcessor:

def __init__(self, repository: IDataRepository):

"""Inject repository dependency via constructor."""

self.repository = repository

async def process(self, feature_data: dict) -> dict:

# Process data

result = self._apply_business_rules(feature_data)

# Save using injected repository

await self.repository.save(result)

return result

# Implementation can be swapped

class PostgresRepository:

async def save(self, data: dict) -> bool:

# PostgreSQL implementation

pass

async def retrieve(self, id: str) -> dict:

# PostgreSQL implementation

pass

class MongoRepository:

async def save(self, data: dict) -> bool:

# MongoDB implementation

pass

async def retrieve(self, id: str) -> dict:

# MongoDB implementation

pass

# Usage: Inject different implementations

processor_postgres = FeatureProcessor(PostgresRepository())

processor_mongo = FeatureProcessor(MongoRepository())

# Testing: Inject mock

class MockRepository:

async def save(self, data: dict) -> bool:

return True

async def retrieve(self, id: str) -> dict:

return {"id": id, "status": "test"}

processor_test = FeatureProcessor(MockRepository())

```

4. Module Organization and File Structure

What it provides:

• Directory structure recommendations
• File naming conventions
• Module boundaries and dependencies
• Import organization

Standard Structure:

```

src/

├── interfaces/ # Presentation layer

│ ├── cli/

│ │ └── commands.py

│ └── api/

│ ├── routes.py

│ └── schemas.py

├── core/ # Business layer

│ ├── models.py # Domain models

│ ├── services.py # Business services

│ ├── processor.py # Core processing logic

│ └── validator.py # Validation logic

├── adapters/ # Data layer

│ ├── database.py # Database adapter

│ ├── external_api.py # External API client

│ └── cache.py # Cache adapter

├── config/ # Configuration

│ └── settings.py

└── utils/ # Shared utilities

└── helpers.py

tests/

├── unit/ # Unit tests (mirror src structure)

│ ├── core/

│ └── adapters/

└── integration/ # Integration tests

└── api/

```

5. Extension Points and Plugin Architecture

What it provides:

• Strategy pattern for pluggable algorithms
• Observer pattern for event handling
• Factory pattern for object creation
• Plugin registration mechanisms

Example:

```python

# Extension point using Strategy Pattern

from abc import ABC, abstractmethod

from typing import Dict

class ProcessingStrategy(ABC):

"""Base class for processing strategies (extension point)."""

@abstractmethod

async def process(self, data: dict) -> dict:

"""Process data using specific strategy."""

pass

class FastProcessingStrategy(ProcessingStrategy):

"""Fast processing with lower accuracy."""

async def process(self, data: dict) -> dict:

# Fast implementation

return {"result": "fast"}

class AccurateProcessingStrategy(ProcessingStrategy):

"""Slower processing with higher accuracy."""

async def process(self, data: dict) -> dict:

# Accurate implementation

return {"result": "accurate"}

# Plugin registration

class ProcessorFactory:

_strategies: Dict[str, ProcessingStrategy] = {}

@classmethod

def register_strategy(cls, name: str, strategy: ProcessingStrategy):

"""Register new processing strategy (plugin)."""

cls._strategies[name] = strategy

@classmethod

def get_strategy(cls, name: str) -> ProcessingStrategy:

"""Retrieve registered strategy."""

return cls._strategies.get(name)

# Register built-in strategies

ProcessorFactory.register_strategy("fast", FastProcessingStrategy())

ProcessorFactory.register_strategy("accurate", AccurateProcessingStrategy())

# Users can register custom strategies

class CustomStrategy(ProcessingStrategy):

async def process(self, data: dict) -> dict:

return {"result": "custom"}

ProcessorFactory.register_strategy("custom", CustomStrategy())

```

6. Design Pattern Application

What it provides:

• Repository Pattern for data access abstraction
• Strategy Pattern for algorithm selection
• Factory Pattern for object creation
• Observer Pattern for event handling
• Adapter Pattern for external system integration

Pattern Selection Guide:

• Repository: Abstract data access logic
• Strategy: Multiple algorithms for same operation
• Factory: Complex object creation
• Observer: Event-driven communication
• Adapter: Integrate with external systems

Step 1: Identify Core Functionality

```

Analyze requirements → Extract core features → Define boundaries

```

Step 2: Determine Layers

```

Identify interfaces (CLI, API) → Core logic → Data access

```

Step 3: Define Components

```

For each layer → List components → Define responsibilities

```

Step 4: Establish Dependencies

```

Map dependencies → Apply dependency injection → Define interfaces

```

Step 5: Select Patterns

```

Identify needs → Choose patterns → Document rationale

```

Step 6: Plan Extension Points

```

Identify future needs → Design plugin mechanisms → Document APIs

```

Step 7: Document Architecture

```

Create diagrams → Document decisions → Provide examples

```

Step 8: Validate Design

```

Check SOLID principles → Verify testability → Review maintainability

```

1. Follow SOLID Principles

- Single Responsibility: Each component has one reason to change

- Open/Closed: Open for extension, closed for modification

- Liskov Substitution: Subtypes must be substitutable for base types

- Interface Segregation: Many specific interfaces better than one general

- Dependency Inversion: Depend on abstractions, not concretions

1. Keep Components Small and Focused

- Maximum 500 lines per file

- Single responsibility per component

- Clear, descriptive names

- Minimal coupling

1. Use Dependency Injection

- Constructor injection for required dependencies

- Avoid global state and singletons

- Enable easy testing with mocks

1. Design for Testability

- Inject dependencies

- Use interfaces/protocols

- Avoid static methods and global state

- Keep business logic pure (no side effects)

1. Document Architectural Decisions

- Explain pattern choices

- Document trade-offs

- Provide usage examples

- Include diagrams

1. Plan for Extension

- Identify likely future changes

- Create extension points

- Use plugin architectures

- Version APIs

architecture-patterns.md

Comprehensive guide to architectural patterns including:

• Layered Architecture (presentation, business, data layers)
• Hexagonal Architecture (ports and adapters)
• Event-Driven Architecture
• Microservices patterns
• Clean Architecture principles
• Pattern selection criteria and trade-offs

component-design-guide.md

Detailed component design guidelines including:

• Single Responsibility Principle application
• Dependency Injection patterns and examples
• Interface design best practices
• Module boundary definition
• Extension point design
• Component interaction patterns

Input (from Architecture Designer agent):

```

"Design component architecture for a feature that processes user uploads, validates content, stores files, and sends notifications."

```

Output (architecture-planner skill provides):

```python

architecture = {

"layers": {

"interfaces": [

"src/interfaces/api/upload_routes.py - REST API endpoints",

"src/interfaces/api/schemas.py - Request/response schemas"

],

"core": [

"src/core/upload_processor.py - Main processing orchestration",

"src/core/content_validator.py - Content validation logic",

"src/core/notification_service.py - Notification business logic",

"src/core/models.py - Domain models"

],

"adapters": [

"src/adapters/file_storage.py - File storage adapter (S3/local)",

"src/adapters/notification_client.py - Notification service client"

]

},

"components": [

{

"name": "UploadProcessor",

"file": "src/core/upload_processor.py",

"responsibility": "Orchestrate upload processing workflow",

"dependencies": ["ContentValidator", "IFileStorage", "INotificationClient"],

"interface": None,

"pattern": "Service layer with dependency injection"

},

{

"name": "ContentValidator",

"file": "src/core/content_validator.py",

"responsibility": "Validate uploaded content (size, type, malware scan)",

"dependencies": [],

"interface": None,

"pattern": "Pure function (stateless validation)"

},

{

"name": "IFileStorage",

"file": "src/adapters/file_storage.py",

"responsibility": "Abstract file storage operations",

"dependencies": [],

"interface": "Protocol/ABC",

"pattern": "Repository pattern for file storage"

}

],

"patterns_applied": [

"Dependency Injection: All services receive dependencies via constructor",

"Repository Pattern: File storage abstraction through IFileStorage",

"Strategy Pattern: Pluggable validators for different content types",

"Adapter Pattern: External notification service wrapped in adapter"

],

"extension_points": [

"IFileStorage can support S3, Azure Blob, local filesystem",

"ContentValidator can add new validation strategies",

"INotificationClient can support email, SMS, push notifications"

]

}

```

Used By:

• @architecture-designer (Primary) - Phase 2 sub-agent for architecture design

Integrates With:

• data-modeler skill - Data models designed after component structure
• api-designer skill - API contracts defined after component interfaces
• sequential-thinking-mcp - Deep reasoning for pattern selection

Workflow Position:

1. Analysis Specialist completes requirements analysis
2. Architecture Designer receives analysis
3. architecture-planner skill designs component structure (Step 3)
4. data-modeler skill designs data models (Step 4)
5. api-designer skill designs API contracts (Step 5)
6. Results synthesized into PRP

---

Version: 2.0.0

Auto-Activation: Yes

Phase: 2 - Design & Planning

Created: 2025-10-29