software-architecture_skill

Overview

This skill implements proven software architecture patterns and principles for JavaScript systems, including Clean Architecture and the SOLID principles. It helps design modular, testable, and maintainable systems by providing concrete patterns (repositories, factories, strategies, observers) and layer separation guidance. Use it to establish structure, evaluate architecture, and guide implementation choices.

How this skill works

The skill inspects system designs and recommends structural changes aligned with domain-driven boundaries and dependency direction (inward dependencies for Clean Architecture). It enforces SOLID practices by suggesting refactors: single responsibility splits, interface segregation, dependency inversion via abstractions, and extension-friendly designs. It also maps use cases to application and interface adapter layers and proposes concrete patterns for persistence, factories, strategies, and eventing.

When to use it

• Designing a new system or greenfield service to set a long-lived architecture
• Reviewing or refactoring an existing codebase to reduce coupling and improve testability
• Defining boundaries between domain, application, and infrastructure layers
• Choosing patterns for repositories, factories, pricing/strategy, or event handling
• Creating ADRs for important architectural decisions

Best practices

• Keep domain entities and value objects pure and independent of frameworks
• Design use cases in the application layer to orchestrate domain behavior and side effects
• Depend on interfaces or abstractions; inject concrete implementations in outer layers
• Split responsibilities: one reason to change per class or module
• Document major decisions with ADRs and avoid premature optimization

Example use cases

• Implement a CreateUser use case that validates business rules, hashes passwords, persists via repository, and triggers welcome email through an injected service
• Refactor a monolithic controller into controllers (interface adapters), use cases, and domain entities for clearer test boundaries
• Introduce a PricingStrategy to support multiple pricing rules without modifying Order code
• Replace direct DB usage with a Repository interface and provide Prisma and mock implementations for production and tests
• Create ADRs to justify technology choices like PostgreSQL vs. NoSQL and capture trade-offs