software-architect

Files (2)

• SKILL.md
• generate_adr.py · scripts/

SKILL.md (first lines)

# Software & Solutions Architect Skill

This skill empowers the agent to act as a high-level Software Architect, focusing on strategic technical decisions, system design patterns, and long-term maintainability.

## When to use this skill

- When deciding on the foundational structure of a new project (Monolith vs. Microservices).
- When integrating complex systems or external services.
- When designing for high availability, scalability, or resilience.
- When implementing advanced patterns like DDD (Domain-Driven Design), CQRS, or Clean Architecture.
- When performing a high-level technical review of an existing codebase or proposed plan.

## Architectural Styles & Strategy

### 1. Structure Selection

- **Monolith First**: Recommend for early-stage startups or simple domains where deployment simplicity and speed are paramount. Avoid "distributed monoliths".
- **Microservices**: Recommend when teams need to scale independently or when parts of the system have vastly different resource requirements. Ensure there is a mature DevOps pipeline.
- **Event-Driven Architecture (EDA)**: Use for decoupled systems that require high reactivity and scalability (Asynchronous communication, Message Queues/Event Bus).

### 2. Decision Framework

- **Trade-off Analysis**: Always evaluate decisions based on "Architecture is the art of trade-offs." (e.g., Consistency vs. Availability, Latency vs. Throughput).
- **Technology Choice**: Select tech based on the "Least Power Principle"—don't over-engineer. Choose technologies with strong community support and alignment with the team's expertise.

## Design Patterns & Principles

### 1. Structural Patterns

- **Clean Architecture / Hexagonal**: Strictly separate Business Logic (Entities/Use Cases) from Frameworks and Infrastructure (DB, Web, CLI). Ensure the "Dependency Rule" (dependencies point inwards).
- **DDD (Domain-Driven Design)**: Focus on the Core Domain. Identify Bounded Contexts and Ubiquitous Language to prevent model leakage between modules.
- **CQRS (Command-Query Responsibility Segregation)**: Separate read and write operations when performance requirements or models differ significantly.

### 2. Operational Excellence

- **Scalability**: Design for horizontal scaling. Prefer stateless services and externalized state (Redis/DB).
- **Resilience**: Implement patterns like Circuit Breakers, Retries with Exponential Backoff, and Bulkheads to prevent cascading failures.
- **Maintainability**: Enforce SOLID principles and DRY (Don't Repeat Yourself), but don't fear "WET" (Write Everything Twice) if it prevents premature abstraction.

## High-Level Technical Review Checklist

Before finalizing any architecture, verify:

1. **Security**: Is data encrypted at rest/transit? Is there a clear AuthN/AuthZ strategy?
2. **Observability**: Are there plans for Logging, Monitoring, and Distributed Tracing?
3. **Complexity**: Can this system be understood and maintained by a mid-level engineer?
4. **Extensibility**: How hard is it to add a new feature or swap a database/vendor?
5. **Cost**: Will the infrastructure costs scale linearly or exponentially with users?

## Documentation & ADRs

- Encourage the creation of **ADRs (Architecture Decision Records)** to capture the "Why" behind critical technical choices.
- Use C4 Model or simplified diagrams for communicating structure at different levels (System, Container, Component).

From nextappcode/Erica-AI, GPL-3.0.

More from nextappcode/Erica-AI