fattain-naime/engineering-docs / skills/system-architecture-document
system-architecture-document
VerifiedCreate a System Architecture Document (SAD) with C4 model diagrams, 4+1 view decomposition, integration maps, NFR constraints, and an Architecture Decision Record log. Use when documenting how an entire system or major subsystem is structured.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.1 KB |
| adr-template.md | markdown | 3.1 KB |
| template.md | markdown | 18.7 KB |
adr-template.md
View on GitHub# Architecture Decision Record
**ADR ID:** ADR-[NNN]
**Title:** [Short, imperative noun phrase describing the decision - e.g., "Use PostgreSQL as the primary database"]
**Status:** `Proposed` | `Accepted` | `Deprecated` | `Superseded by ADR-[NNN]`
**Date:** YYYY-MM-DD
**Author:** [Name]
**Deciders:** [Names of people involved in the decision]
**Supersedes:** ADR-[NNN] (if applicable)
---
## Context
> Describe the situation that necessitates this decision. What is the problem or opportunity? What forces are at play - technical, organizational, business, regulatory? What constraints exist? A reader must understand the context without any prior knowledge of the decision.
>
> Write this section as if you will not be around to explain it in 2 years.
[Context description]
---
## Decision
> State the architectural decision clearly and directly. One sentence is ideal. The decision should be specific enough that a new engineer who reads it knows exactly what was chosen.
**We will [chosen approach].**
[Optional: 2-3 sentences elaborating on how the decision is applied in practice.]
---
## Rationale
> Why was this option chosen over the alternatives? What evidence, benchmarks, or principles support it? Be precise - avoid vague statements like "it seemed better." Reference specific evaluation criteria.
[Rationale with specific evidence and reasoning]
---
## Alternatives Considered
> This section is mandatory. Documenting rejected options prevents future engineers from re-investigating paths already evaluated. For each alternative, clearly state why it was rejected.
### Alternative 1: [Name]
**Description:** [Brief description of this approach]
**Why Rejected:**
- [Specific reason 1 - e.g., "Does not support our required throughput of 10K RPS based on benchmark X"]
- [Specific reason 2]
---
### Alternative 2: [Name]
**Description:** [Brief description]
**Why Rejected:**
- [Specific reason 1]
- [Specific reason 2]
---
### Alternative 3: [Name] (Optional)
**Description:** [Brief description]
**Why Rejected:**
- [Specific reason]
---
## Consequences
> What becomes easier and what becomes harder as a result of this decision? Be honest about both positive and negative consequences. No decision has only upsides.
### Positive Consequences
- [What improves - e.g., "Eliminates N+1 query risk by enforcing repository pattern at the ORM layer"]
- [What improves]
### Negative Consequences / Trade-offs
- [What gets harder - e.g., "Developers must learn the repository abstraction before writing data access code"]
- [What we lose]
- [New constraint introduced]
### Risks
| Risk | Probability | Impact | Mitigation |
| :--- | :--- | :--- | :--- |
| [Risk introduced by this decision] | `Low` / `Med` / `High` | `Low` / `Med` / `High` | [How mitigated] |
---
## Compliance and Standards
> If this decision is driven by or affects compliance requirements, list them here.
- [e.g., Aligns with PCI-DSS Requirement 6.3 - no sensitive data in logs]
- [e.g., Required by internal security policy SEC-042]
---
## References
- [Link to relevant specification, benchmark, article, or prior discussion]
- [Link to related ADR]
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |