opencode-skill/skills/architecture/SKILL.md

name, description

name	description
architecture	Master architecture skill combining system design, architecture patterns, ADRs, C4 modeling, and senior architect tools. Use when designing systems, making architecture decisions, or reviewing designs.

Architecture Master

Comprehensive architecture skill combining: requirements analysis, trade-off evaluation, ADR documentation, architecture patterns, C4 modeling, and system design.

---

Quick Reference

Task	Use Section
Make architecture decisions	Architecture Decision Framework
Choose architecture patterns	Architecture Patterns
Document decisions	ADRs
Design system architecture	System Design
Create C4 diagrams	C4 Model
Review architecture	Architecture Review

---

Architecture Decision Framework

Core Principle: "Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."

Decision Process

1. Gather Requirements - Functional and non-functional
2. Identify Constraints - Budget, timeline, technology, team
3. Evaluate Options - Compare alternatives with trade-off analysis
4. Document Decision - ADR with context, decision, consequences
5. Communicate - Explain rationale to stakeholders

Questions to Ask

• What problem are we solving?
• What are the non-functional requirements?
• What constraints must we work within?
• What trade-offs are we willing to make?
• How will this scale?

---

Architecture Patterns

When to Use: Designing new systems or refactoring existing ones.

Common Patterns

Layered Architecture

┌─────────────────────┐
│    Presentation     │
├─────────────────────┤
│    Application     │
├─────────────────────┤
│      Domain        │
├─────────────────────┤
│    Infrastructure  │
└─────────────────────┘

Clean Architecture

┌─────────────────────┐
│   External Actors   │
├─────────────────────┤
│   Input Adapters   │
├─────────────────────┤
│   Use Cases        │
├─────────────────────┤
│  Output Adapters   │
├─────────────────────┤
│     Entities       │
└─────────────────────┘

Hexagonal Architecture (Ports & Adapters)

• Core: Business logic (hexagon)
• Ports: Interfaces for input/output
• Adapters: Implementations of ports

Event-Driven Architecture

• Event sources → Event channel → Event processors
• Decoupled, scalable, real-time

Microservices Architecture

• Single responsibility per service
• API gateway, service discovery
• Distributed data management

Monorepo Architecture

• Shared code, unified tooling
• Atomic commits across projects
• Consistent dependencies

---

Architecture Decision Records (ADRs)

When to Use: Documenting significant architecture decisions.

ADR Template

# ADR-001: [Title]

## Status
Accepted | Deprecated | Superseded

## Context
[Problem statement, constraints, requirements]

## Decision
[Chosen approach]

## Consequences
### Positive
- ...

### Negative
- ...

### Neutral
- ...

When to Create an ADR

• Significant technology choice
• Cross-cutting concerns
• High-cost implementation
• Reversal cost is high

---

C4 Model

When to Use: Visualizing system architecture at different levels.

C4 Levels

Level 1: Context

• Highest level view
• Shows users, systems, relationships
• External systems labeled

Level 2: Container

• Applications, databases, services
• Technology choices visible
• Responsibilities defined

Level 3: Component

• Major components within a container
• Responsibilities and collaborations
• Implementation details emerging

Level 4: Code

• Implementation details
• Class diagrams, function signatures
• Most detailed level

Tools

• PlantUML
• Mermaid
• Structurizr
• draw.io

---

System Design

API Design

• RESTful vs GraphQL vs gRPC
• Versioning strategy
• Authentication/Authorization
• Rate limiting
• Error handling

Database Design

• Relational vs NoSQL vs NewSQL
• Schema design
• Indexing strategy
• Replication and sharding
• Backup and recovery

Authentication Patterns

• JWT tokens
• OAuth 2.0 / OIDC
• SAML
• Session management
• MFA integration

Messaging Patterns

• Point-to-point
• Pub/Sub
• Event streaming
• Message formats (JSON, Avro, Protobuf)

---

Architecture Review

Review Checklist

• Requirements satisfied?
• Non-functional requirements met?
• Trade-offs documented?
• Risks identified and mitigated?
• Scalability considered?
• Security baked in?
• Observability included?
• Documentation complete?

Anti-Patterns to Avoid

• Big bang rewrite
• Gold plating
• Architecture astronautism
• Single point of failure
• Premature optimization

---

Related Skills

Skill	Use For
@database-architect	Database-specific architecture
@backend-architect	Backend system design
@c4-architecture-c4-architecture	C4 diagram creation
@software-architecture	General software architecture

---

Best Practices

1. Start Simple - YAGNI, avoid over-engineering
2. Document Decisions - ADRs for significant choices
3. Consider Trade-offs - Every decision has pros/cons
4. Plan for Change - Flexibility over perfection
5. Communicate Visually - Diagrams communicate faster
6. Review Regularly - Architecture evolves