# System Architecture

> Use after the requirements are set, when a non-trivial system needs designing before it's built — components, boundaries, data flow, and the seams that keep it testable. Skip for a small feature; its structure lives in the plan.

- **Type:** Skill
- **Install:** `agentstack add skill-njoyimpeguy-augments-system-architecture`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [NjoyimPeguy](https://agentstack.voostack.com/s/njoyimpeguy)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [NjoyimPeguy](https://github.com/NjoyimPeguy)
- **Source:** https://github.com/NjoyimPeguy/augments/tree/main/skills/design/system-architecture

## Install

```sh
agentstack add skill-njoyimpeguy-augments-system-architecture
```

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

## About

# System Architecture

Design the shape of the solution before anyone builds it: what the pieces are, how they fit, and where the seams go. Aim for **deep modules**, not a sprawl of shallow ones.

## When to use

- You have approved requirements and the work is non-trivial — a new subsystem, several components, real integration.
- **Skip** for a small feature; its structure lives in `writing-plans`' interface map, not a separate design.

## Procedure

1. **Components and boundaries.** Name each module by what it *does* and what it deliberately *doesn't*. A module earns its place if removing it would spread its complexity across the callers; if complexity merely relocates, it's shallow — merge it.
2. **Data flow.** Trace the request/response and event paths end to end. Each should be followable from entry to effect.
3. **External services.** Map every third party (payments, mail, realtime, storage). For each, state the testability strategy: how you trace the data path through it, and how you behave — and test — when it's unavailable.
4. **Seams.** Put boundaries where you'd swap an implementation, and inject across them. Don't add a port for a *hypothetical* seam — two real adapters justify one; one doesn't.
5. **Decide the load-bearing choices deliberately.** For each significant, hard-to-reverse structural decision, weigh the real options and record the result as an ADR — `architecture-decisions` owns how to weigh them.
6. **Name things in the domain's language**, not generic "service / manager / handler". The vocabulary is itself a design decision.
7. **Write the architecture section** of the shared design document `.augments/designs/{{YYYY-MM-DD}}-{{topic}}.md` (the standard designs location; another path only if the user has set one).

## Common mistakes

- Shallow modules — an interface as wide as the implementation behind it.
- Untested external-service paths — "it'll work in prod" is not a design.
- Designing for hypothetical futures (a port with one adapter, "for extensibility").
- Generic vocabulary that hides the domain.

For a high-stakes design, once the document is compiled, dispatch `design-review.md` — a fresh subagent that checks the whole design before anyone builds against it.

The module-design terms used here (deep module, seam, adapter, leverage) are defined once in `refactor-architecture`'s `vocabulary.md` — both skills use them with the same meaning.

## Source & license

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

- **Author:** [NjoyimPeguy](https://github.com/NjoyimPeguy)
- **Source:** [NjoyimPeguy/augments](https://github.com/NjoyimPeguy/augments)
- **License:** MIT

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:** no
- **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-njoyimpeguy-augments-system-architecture
- Seller: https://agentstack.voostack.com/s/njoyimpeguy
- 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%.