architecture
npx machina-cli add skill Roberdan/MyConvergio/architecture --openclawFiles (1)
SKILL.md
4.8 KB
Architecture Design Skill
Reusable workflow extracted from baccio-tech-architect expertise.
Design scalable, maintainable, secure system architectures using DDD, Clean Architecture, cloud-native patterns.
When to Use
New system design | Legacy modernization | Stack selection | Scalability planning | Microservices design | Cloud migration | Debt evaluation | Architecture review
Workflow
| Step | Actions |
|---|---|
| 1. Requirements | Gather functional/NFRs, constraints (budget, timeline, team), scale (users, data, traffic), compliance |
| 2. Domain Model | Apply DDD: bounded contexts, aggregates, entities, ubiquitous language |
| 3. Pattern Selection | Choose style (monolith/microservices/serverless), patterns (CQRS, Event Sourcing, Saga), Clean Architecture |
| 4. Tech Stack | Evaluate options vs requirements, team expertise, vendor lock-in, cost, compliance |
| 5. Scalability | Horizontal/vertical scaling, caching (app/CDN/DB), load balancing, sharding, geo-distribution |
| 6. Security | Zero-Trust, auth/authz, encryption (at-rest/in-transit), boundaries, defense-in-depth |
| 7. Observability | Structured logging, metrics (Prometheus, CloudWatch), tracing, dashboards, alerts |
| 8. Documentation | ADRs, C4 diagrams, API contracts/versioning, deployment architecture, capacity planning |
Inputs
- Business requirements (problem to solve)
- NFRs (performance, security, compliance)
- Scale (current/projected users, data, traffic)
- Constraints (budget, timeline, team skills, existing systems)
- Compliance (GDPR, HIPAA, SOC2, etc.)
Outputs
- Architecture Blueprint
- ADRs (decision records with rationale)
- Tech Stack Recommendation
- Scalability Plan
- Security Architecture
- Deployment Diagrams
- Migration Roadmap
Architecture Patterns
Styles
| Pattern | Traits |
|---|---|
| Monolithic | Single deployable, simpler, less scalable |
| Microservices | Independent services, complex, highly scalable |
| Serverless | Event-driven, pay-per-use, elastic |
| Modular Monolith | Compromise between monolith and microservices |
| SOA | Enterprise service bus |
Design Patterns
| Pattern | Use Case |
|---|---|
| DDD | Bounded contexts, aggregates, entities |
| Clean Architecture | Dependency inversion, layers, boundaries |
| CQRS | Command Query Responsibility Segregation |
| Event Sourcing | Event log as source of truth |
| Saga | Distributed transactions |
| API Gateway | Single entry point |
| BFF | Backend for Frontend (API per client) |
Communication
- Sync: REST, GraphQL, gRPC
- Async: Kafka, RabbitMQ, SQS
- Pub/Sub: Event-driven
- RPC: Request-Reply
ADR Template
## Decision: [Technology/Pattern]
### Context
[Problem, constraints]
### Options
1. **Option A**: [Pros/Cons/Cost]
2. **Option B**: [Pros/Cons/Cost]
### Decision
[Choice with rationale]
### Consequences
- Positive: [Benefits]
- Negative: [Drawbacks]
- Mitigation: [Actions]
NFR Checklist
See nfr-checklist.md for performance, availability, security, observability, maintainability requirements.
Example
Input: E-commerce platform, 10K users, 99.9% uptime, PCI DSS
Steps:
1. Requirements: User accounts, catalog, cart, checkout
2. Domain: User, Product, Cart, Order contexts
3. Pattern: Microservices + API Gateway + Event-driven
4. Stack: Node.js, PostgreSQL, Redis, Kafka, AWS ECS/RDS
5. Scale: Horizontal (ECS), read replicas, CDN
6. Security: OAuth2+JWT, PCI gateway, encryption
7. Observability: CloudWatch, X-Ray, Grafana
8. Docs: ADRs, C4 diagrams, API specs
Output: Blueprint + ADRs + diagrams
Tech Stack Evaluation
| Criterion | Weight | Option A | Option B | Option C |
|---|---|---|---|---|
| Team expertise | 20% | 8/10 | 5/10 | 6/10 |
| Scalability | 25% | 9/10 | 7/10 | 8/10 |
| Cost | 15% | 6/10 | 9/10 | 7/10 |
| Community | 10% | 9/10 | 8/10 | 6/10 |
| Compliance | 15% | 8/10 | 7/10 | 9/10 |
| Lock-in | 15% | 7/10 | 5/10 | 8/10 |
| Total | 100% | 7.9 | 6.9 | 7.5 |
Related Agents
- baccio-tech-architect - Full reasoning/decision-making
- luca-security-expert - Security validation
- dan-engineering-gm - Leadership alignment
- marco-devops-engineer - Infrastructure/deployment
- domik-mckinsey-strategic-decision-maker - Strategic decisions
Engineering Fundamentals
- Document ADRs for all major decisions
- Apply proven design patterns
- Trade studies before decisions
- Technical spikes for high-risk unknowns
- Design for NFRs from day one
- Infrastructure as Code
- GitOps workflows
Source
git clone https://github.com/Roberdan/MyConvergio/blob/master/.claude/skills/architecture/SKILL.mdView on GitHub Overview
Architecture design helps craft scalable, maintainable systems using DDD, Clean Architecture, and cloud-native patterns. It aligns business domains with technical boundaries to support growth, resilience, and secure deployments.
How This Skill Works
Begin with requirements and constraints, model the domain with DDD (bounded contexts, aggregates, ubiquitous language), and choose patterns (CQRS, Event Sourcing, Saga) and an appropriate tech stack. Then design for scalability, security, and observability, capturing decisions in ADRs, C4 diagrams, and deployment diagrams.
When to Use It
- New system design
- Legacy modernization
- Microservices design
- Cloud migration
- Architecture review
Quick Start
- Step 1: Gather business requirements, NFRs, constraints, and success metrics.
- Step 2: Define the domain model with DDD, including bounded contexts and ubiquitous language.
- Step 3: Select an architectural style and patterns (monolith, microservices, serverless) and draft ADRs and deployment diagrams.
Best Practices
- Start with domain boundaries using DDD to establish clear bounded contexts and ubiquitous language.
- Document decisions with ADRs and use C4 diagrams for clarity.
- Evaluate pattern choices (CQRS, Event Sourcing, Saga) and ensure alignment with Clean Architecture.
- Plan security early: Zero-Trust, auth/authz, encryption, and defense-in-depth.
- Design for scalability: horizontal/vertical scaling, caching, load balancing, and geo-distribution.
Example Use Cases
- E-commerce platform blueprint with microservices, API gateway, and event-driven communication.
- Cloud migration using serverless or containerized services with CI/CD pipelines.
- Legacy modernization by extracting domains into bounded contexts and introducing ADRs.
- High-availability deployments with multi-region setups, CDN caching, and autoscaling.
- Architecture reviews that surface debt and produce ADRs and migration roadmaps.
Frequently Asked Questions
Add this skill to your agents
