# System Design Patterns

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-everyone-needs-a-copilot-claude-copilot-system-design-patterns`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Everyone-Needs-A-Copilot](https://agentstack.voostack.com/s/everyone-needs-a-copilot)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Everyone-Needs-A-Copilot](https://github.com/Everyone-Needs-A-Copilot)
- **Source:** https://github.com/Everyone-Needs-A-Copilot/claude-copilot/tree/main/.claude/skills/architecture/system-design-patterns
- **Website:** https://ineedacopilot.com

## Install

```sh
agentstack add skill-everyone-needs-a-copilot-claude-copilot-system-design-patterns
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# System Design Patterns

Architecture patterns, ADR methodology, and trade-off analysis frameworks for making and documenting sound design decisions.

ADR completeness is deterministic — the script checks required field presence and scores coverage. Pattern selection and trade-off quality are prose judgment, left to the model.

## Purpose

- Document architectural decisions with full context and rationale
- Select the right architectural pattern for the problem at hand
- Validate architecture with automated fitness functions
- Analyse trade-offs explicitly before committing to a direction

---

## ADR Template

Architecture Decision Records capture the context and consequences of significant design choices.

```markdown
# ADR-[number]: [Title]

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-[n]

## Context

What is the situation forcing a decision? What constraints exist?
What forces are at play (technical, political, organizational)?

## Decision

What was decided? State it as an active voice sentence:
"We will use [X] because [Y]."

## Consequences

**Positive:**
- [Benefit 1]
- [Benefit 2]

**Negative:**
- [Trade-off 1]
- [Trade-off 2]

**Neutral:**
- [Side effect that is neither good nor bad]

## Alternatives Rejected

| Alternative | Reason Rejected |
|-------------|----------------|
| [Option A]  | [Why not chosen] |
| [Option B]  | [Why not chosen] |

## References

- [Link to relevant documentation, RFC, or prior art]
```

---

## Architecture Pattern Decision Matrix

| Pattern | Best When | Avoid When | Key Trade-offs |
|---------|-----------|------------|----------------|
| **Layered (Monolith)** | Small team, simple domain, fast iteration needed | Independent deployment required, team > 10, polyglot stack | Fast to build; harder to scale independently |
| **Microservices** | Independent deployment needed, team autonomy, polyglot stack | Domain is unclear, team is small, ops maturity is low | High autonomy; high operational complexity |
| **Event-Driven** | Async workflows, eventual consistency acceptable, audit trail needed | Strong consistency required, debugging must be simple | Decoupled producers; complex event ordering |
| **CQRS** | Read/write asymmetry, complex queries, event sourcing in use | Simple CRUD, small team, low query complexity | Optimised reads/writes; two models to maintain |
| **API Gateway** | Multiple clients, rate limiting needed, auth aggregation | Single client, low traffic, gateway becomes bottleneck | Centralised cross-cutting concerns; single point of failure risk |

---

## Fitness Function Examples

Automated architecture tests that verify the system conforms to its intended structure.

### Dependency Rules

```typescript
// No circular dependencies between modules
import { checkCycles } from 'madge';

test('no circular dependencies', async () => {
  const result = await madge('./src', { fileExtensions: ['ts'] });
  expect(result.circular()).toHaveLength(0);
});
```

### Anti-Corruption Layer

```typescript
// All external calls go through anti-corruption layer
test('external integrations isolated', () => {
  const externalCalls = findFilesWithPattern('src/**/*.ts', /fetch|axios|http\.request/);
  const allowedPaths = ['src/infrastructure/', 'src/adapters/'];

  externalCalls.forEach(file => {
    expect(allowedPaths.some(p => file.startsWith(p))).toBe(true);
  });
});
```

### Performance Threshold

```typescript
// Response time p99  {
  const metrics = await loadTestEndpoint('/api/search', { rps: 100, duration: 60 });
  expect(metrics.p99).toBeLessThan(500); // 500ms SLA
});
```

### Layering Enforcement

```typescript
// No direct database access from presentation layer
test('presentation layer does not access database', () => {
  const violations = findImports('src/controllers/**/*.ts', /typeorm|prisma|knex|sequelize/);
  expect(violations).toHaveLength(0);
});
```

---

## Trade-Off Analysis Checklist

For every significant architectural decision, answer these questions before committing:

- [ ] **Quality attribute optimised:** What does this choice improve? (performance, scalability, reliability, maintainability, security, cost)
- [ ] **Quality attribute sacrificed:** What does this choice make worse?
- [ ] **Reversibility:** Can we undo this decision in  3 Hops** | Request triggers 4+ synchronous downstream calls | Latency multiplies; one slow service degrades everything |
| **Premature Decomposition** | Splitting into microservices before domain boundaries are understood | Wrong boundaries require expensive re-merging or re-splitting later |

---

## Invocation — ADR Completeness Scorer (L3 Script)

When reviewing ADRs for completeness, run the scorer to get structural coverage findings. Consume the script's **output only** — the script source never enters context.

**Deterministic core:** Structural field presence checking against the 7 required ADR fields (id, title, status, date, context, decision, consequences) + trade-off checklist coverage. Source: Nygard ADR format (adr.github.io) + ISO/IEC 25010 completeness criteria.

**Input format:** JSON array of ADR objects. Each object:
```json
[
  {
    "id":           "ADR-001",
    "title":        "Use PostgreSQL as primary database",
    "status":       "accepted",
    "date":         "2026-01-15",
    "context":      "We need a relational database that supports ACID transactions.",
    "decision":     "We will use PostgreSQL because it is battle-tested and open source.",
    "consequences": "Positive: ACID transactions. Negative: operational complexity.",
    "alternatives": [{"alternative": "MySQL", "reason": "Limited JSON support"}],
    "references":   ["https://postgresql.org"],
    "trade_off_checklist": {
      "quality_attribute_optimised": true,
      "quality_attribute_sacrificed": true,
      "reversibility": true,
      "evidence_based": true,
      "team_readiness": true,
      "failure_mode_understood": true,
      "migration_path": true,
      "documentation": true
    }
  }
]
```

**Required fields:** `id`, `title`, `status`, `date`, `context`, `decision`, `consequences`
**Optional fields:** `alternatives`, `references`, `trade_off_checklist`
**Valid status values:** `proposed`, `accepted`, `deprecated`, `superseded`, `rejected`

**Bash invocation (file argument):**
```bash
python .claude/skills/architecture/system-design-patterns/scripts/arch_fitness.py adrs.json
```

**Bash invocation (stdin):**
```bash
echo '[...]' | python .claude/skills/architecture/system-design-patterns/scripts/arch_fitness.py -
```

**Script output:**
1. A JSON block: `{ "documents": [...scored...], "summary": { "total", "complete", "adequate", "partial", "incomplete" } }`
2. A markdown table with coverage percentage and band per ADR.

**Coverage bands:**

| Band | Coverage | Meaning |
|------|----------|---------|
| COMPLETE | 90–100% | All required fields present |
| ADEQUATE | 70–89% | Minor gaps; usable but should be completed |
| PARTIAL | 50–69% | Significant gaps; rationale unclear |
| INCOMPLETE | 0–49% | Major gaps; not authoritative |

**What the agent does with the output:**
1. Any ADR with `band == "INCOMPLETE"` should not be referenced in architecture decisions until gaps are filled.
2. HIGH-severity gaps (missing context/decision/consequences) should be filled before the ADR is marked Accepted.
3. MEDIUM gaps (missing id/title/status/date) represent process gaps — flag to the team.
4. LOW gaps (trade-off checklist items) are advisory — note them but do not block.

**Error handling:** The script exits non-zero with an `ERROR:` message to stderr on bad JSON, non-array input, or non-object array elements.

---

## Related Resources

- [C4 Model](https://c4model.com/) — architecture diagramming
- [Architectural Decision Records](https://adr.github.io/) — ADR tooling and examples
- [Building Evolutionary Architectures](https://evolutionaryarchitecture.com/) — fitness functions
- Related skills: `docker-patterns`, `threat-modeling`

---

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| 2.0.0 | 2026-05-20 | L3 script `arch_fitness.py` added; Invocation section; allowed-tools updated |
| 1.0.0 | 2026-03-29 | Initial version with ADR template and patterns |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Everyone-Needs-A-Copilot](https://github.com/Everyone-Needs-A-Copilot)
- **Source:** [Everyone-Needs-A-Copilot/claude-copilot](https://github.com/Everyone-Needs-A-Copilot/claude-copilot)
- **License:** MIT
- **Homepage:** https://ineedacopilot.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-everyone-needs-a-copilot-claude-copilot-system-design-patterns
- Seller: https://agentstack.voostack.com/s/everyone-needs-a-copilot
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.