swe-workflow-skills 0.1.0

package/skills/architecture-design/references/solid-principles.md

@@ -0,0 +1,106 @@
+# SOLID Principles Reference
+
+## Contents
+- Open/Closed Principle (OCP)
+- Liskov Substitution Principle (LSP)
+- Interface Segregation Principle (ISP)
+- Dependency Inversion Principle (DIP)
+
+SRP is already covered extensively in the review checklist and refactoring skill. This reference focuses on the four principles that are less intuitive and more often misapplied.
+
+## Open/Closed Principle (OCP)
+
+**Software entities should be open for extension but closed for modification.**
+
+When a new requirement arrives, you should be able to add new behavior without changing existing, tested code. Changing existing code risks breaking things that already work.
+
+How to achieve it:
+- **Polymorphism**: Define a base type with a contract. New behaviors become new implementations, not if/else branches in existing code.
+- **Strategy pattern**: Pass behavior as a parameter instead of hard-coding it.
+- **Plugin architecture**: Define extension points where new functionality can be registered.
+
+When OCP matters most:
+- Code that is stable and widely depended upon — changing it has high blast radius
+- Frameworks and libraries consumed by others
+- Business rule engines where rules are added frequently
+
+When to relax OCP:
+- Early in a feature's life when the abstraction isn't clear yet — premature abstraction violates KISS
+- Internal code with few consumers — just change it
+- When the "extension" mechanism would be more complex than the modification it avoids
+
+**The smell**: A growing switch/if-else chain where each new case modifies the same function. This is the classic OCP violation — each addition risks breaking existing cases.
+
+## Liskov Substitution Principle (LSP)
+
+**Subtypes must be substitutable for their base types without altering the correctness of the program.**
+
+If code works with a base type, it must also work with any subtype. Violations create bugs that surface far from the offending code — a subtype behaves unexpectedly in a context that expects the base type's contract.
+
+The contract includes:
+- **Preconditions**: A subtype cannot strengthen preconditions (require more from callers)
+- **Postconditions**: A subtype cannot weaken postconditions (promise less to callers)
+- **Invariants**: A subtype must maintain all invariants of the base type
+- **History constraint**: A subtype cannot change state in ways the base type cannot
+
+Classic violations:
+- `Square extends Rectangle` where setting width also sets height — breaks `Rectangle`'s contract that width and height are independent
+- A `ReadOnlyList` that throws on `add()` — callers of `List` expect `add()` to work
+- A cache implementation that silently drops entries — callers expect `get()` after `put()` to return the value
+
+How to detect LSP violations:
+- Look for `instanceof` / type checks in code consuming the base type — these indicate the base type's contract is insufficient
+- Look for overridden methods that throw `UnsupportedOperationException` — the subtype can't fulfill the contract
+- Look for subtypes that ignore or no-op base type methods
+
+How to fix:
+- Redesign the hierarchy — often the inheritance relationship is wrong
+- Use composition instead of inheritance
+- Split the base type into smaller interfaces (leads naturally to ISP)
+
+## Interface Segregation Principle (ISP)
+
+**Clients should not be forced to depend on interfaces they do not use.**
+
+Fat interfaces create unnecessary coupling. When a client depends on methods it never calls, changes to those methods can still force recompilation, redeployment, or unexpected breakage.
+
+Signs of ISP violation:
+- An interface with 10+ methods where most implementors only use a subset
+- Classes that implement interface methods with empty bodies or `throw new NotImplementedException()`
+- A "god interface" that every module depends on but each uses a different slice
+
+How to apply ISP:
+- Split large interfaces into smaller, role-specific ones: `Readable`, `Writable`, `Closeable` instead of `FileHandler`
+- Define interfaces from the client's perspective — what does the consumer need? — not from the implementor's perspective
+- A class can implement multiple small interfaces, so splitting costs nothing
+
+Relationship to other principles:
+- ISP violations often cause LSP violations (implementors that can't fulfill the full contract)
+- ISP supports DIP (small, focused abstractions are easier to depend on)
+- ISP aligns with CRP at the component level (don't depend on what you don't use)
+
+## Dependency Inversion Principle (DIP)
+
+**High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions.**
+
+This is the architectural principle behind Clean Architecture's Dependency Rule. Without DIP, high-level business logic becomes coupled to infrastructure — changing a database or API client forces changes to business rules.
+
+How it works:
+1. High-level module defines an interface for what it needs (e.g., `OrderRepository`)
+2. Low-level module implements that interface (e.g., `PostgresOrderRepository`)
+3. Both depend on the abstraction — the high-level module owns the interface definition
+4. A composition root (main, DI container) wires implementations to interfaces
+
+Key insight: **the interface belongs to the consumer, not the provider**. `OrderService` defines `OrderRepository`; the database layer implements it. This means the database layer depends on the business layer, not the other way around.
+
+When DIP matters:
+- Business logic that should survive infrastructure changes (database, API, messaging)
+- Code that needs to be testable in isolation (inject test doubles through the interface)
+- Boundaries between teams — interface ownership defines the dependency direction
+
+When to skip DIP:
+- Internal code where the "low-level" module will never change (e.g., wrapping a string utility)
+- When there's only one possible implementation and no testing benefit — the abstraction adds noise
+- Early prototyping where speed matters more than structure
+
+**The test**: Can you test your business logic without a database, network, or file system? If not, DIP is likely missing at a critical boundary.

package/skills/architecture-design/templates/adr.md

@@ -0,0 +1,63 @@
+# ADR Template
+
+```markdown
+# ADR-[NNN]: [Decision Title]
+
+**Date**: [YYYY-MM-DD]
+**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-[NNN]
+**Deciders**: [Names/roles]
+
+## Context
+
+[What is the situation? What forces are at play? What triggered this decision?
+Include relevant technical context, business constraints, and team factors.]
+
+## Decision
+
+[State the decision clearly in 1-2 sentences.]
+
+We will [decision].
+
+## Options Considered
+
+### Option 1: [Name]
+[2-3 sentence description]
+
+**Pros**: [what this option does well]
+**Cons**: [what this option does poorly]
+**Complexity**: [Low/Medium/High]
+**Reversibility**: [Easy/Moderate/Difficult]
+
+### Option 2: [Name]
+[Same structure]
+
+### Option 3: [Name] (if applicable)
+[Same structure]
+
+## Decision Rationale
+
+[Why this option over the others. Reference specific quality attributes,
+principles, and constraints. Acknowledge what you're trading off.]
+
+## Consequences
+
+### Positive
+- [Expected benefit 1]
+- [Expected benefit 2]
+
+### Negative
+- [Accepted trade-off 1]
+- [Accepted trade-off 2]
+
+### Risks
+- [Risk and its mitigation]
+
+## Revisit Triggers
+
+Revisit this decision if any of these conditions arise:
+- [Condition 1, e.g., "request volume exceeds 10K/sec"]
+- [Condition 2, e.g., "team grows beyond 8 engineers"]
+
+## References
+- [Related ADRs, design docs, or external resources]
+```

package/skills/architecture-documentation/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: architecture-documentation
+description: "Design and maintain architecture documentation with multi-level diagrams (C4) and docs-as-code. Triggers: architecture diagram, document the architecture, C4 diagram, system context, container diagram, component diagram, architecture docs, docs-as-code, PlantUML, Structurizr, D2, Mermaid architecture, infrastructure diagram, runtime flow. Use architecture-design for ADRs."
+model: opus
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Architecture Documentation
+
+Help the user create and maintain architecture documentation that is version-controlled, multi-layered, and useful. Good architecture docs answer "what exists and how does it connect?" — not by drawing everything, but by drawing the right things at the right abstraction level.
+
+## Workflow
+
+### Step 1: Assess Documentation Scope
+
+Understand what exists and what's needed before creating anything:
+
+- **Current state**: Are there existing diagrams, READMEs with architecture sections, or whiteboard photos? Scan the repo for `docs/`, `architecture/`, `.puml`, `.d2`, or Mermaid blocks in markdown.
+- **Audience**: Who will read this? New hires need conceptual overviews. Ops teams need runtime topology. Architects need structural boundaries.
+- **System complexity**: How many services, data stores, and external dependencies? This determines which abstraction levels are worth creating.
+
+A simple monolith may only need one conceptual diagram. A distributed system with 5+ services likely needs canonical and runtime levels too.
+
+### Step 2: Choose Abstraction Levels
+
+Architecture documentation works at three distinct levels. Not every system needs all three — apply YAGNI.
+
+| Level | Purpose | Answers | Stability |
+|-------|---------|---------|-----------|
+| **Canonical** | What exists structurally | "What are the building blocks?" | Stable — changes with architecture |
+| **Runtime** | How it behaves operationally | "How does data flow? Where does code run?" | Medium — changes with deployment |
+| **Conceptual** | How to explain it | "What's the mental model?" | Ephemeral — changes with audience |
+
+**Guidelines for selection:**
+- **Always start with Conceptual** — even a quick sketch helps align understanding
+- **Add Canonical** when the system has multiple services, teams, or bounded contexts
+- **Add Runtime** when deployment topology, data flows, or infrastructure matter for operations
+
+See [references/abstraction-levels.md](references/abstraction-levels.md) for detailed guidance on each level, traceability rules, and the promotion model.
+
+### Step 3: Select Tooling and Establish Conventions
+
+Choose tools that fit the team's stack. The framework is tool-agnostic — what matters is consistent usage, not specific tools.
+
+**Recommended defaults by level:**
+
+| Level | Recommended Tools | Alternatives |
+|-------|------------------|--------------|
+| Canonical | C4-PlantUML, Structurizr DSL | Mermaid C4 extension, Ilograph |
+| Runtime | D2, Mermaid | PlantUML sequence/deployment, Diagrams-as-code (Python) |
+| Conceptual | Mermaid, Excalidraw | Whiteboard photos, ASCII diagrams |
+
+**Conventions to establish:**
+- **Shared vocabulary**: Create a glossary of system names. Every diagram must use these names exactly — no aliasing or renaming per diagram.
+- **File naming**: Use a consistent pattern like `{level}-{scope}.{ext}` (e.g., `canonical-system-context.puml`, `runtime-checkout-flow.d2`)
+- **Repository structure**: Set up `docs/architecture/` using the template at [templates/architecture-doc.md](templates/architecture-doc.md)
+- **Docs-as-code**: All diagrams must be text-based, version-controlled, and reviewable in PRs
+
+See [references/diagram-tooling.md](references/diagram-tooling.md) for tool comparison and syntax examples.
+
+### Step 4: Create Diagrams
+
+Work top-down — start at the highest level and add detail only where needed:
+
+1. **System Context** (canonical): The system as a black box, showing users and external dependencies. This is the single most valuable diagram.
+2. **Container diagram** (canonical): Zoom into the system — services, data stores, message brokers, frontends.
+3. **Runtime views** (as needed): Data flow diagrams, sequence diagrams for key interactions, deployment/infrastructure topology.
+4. **Component diagrams** (rarely): Internal structure of a single service. Only create when a service is complex enough to warrant it.
+
+**Per diagram:**
+- Define scope — one diagram, one concern
+- Identify elements and relationships
+- Add brief annotations explaining non-obvious connections
+- Ensure traceability: every element in a detailed diagram should trace to a parent in a higher-level diagram
+
+**Linking to decisions:** When an ADR changes architecture, reference the affected diagrams in the ADR and update them. For ADR creation, use the `architecture-design` skill.
+
+### Step 5: Validate
+
+Run through the validation checklist before considering documentation complete:
+
+- [ ] All services/systems in the codebase appear in canonical diagrams
+- [ ] Runtime diagrams reference only elements defined in canonical diagrams (infrastructure-only components like load balancers are exceptions)
+- [ ] Naming is consistent across all diagrams and matches the glossary
+- [ ] ADRs that changed architecture reference affected diagrams
+- [ ] Diagrams are version-controlled and render correctly
+- [ ] Conceptual diagrams are clearly labeled as non-canonical
+- [ ] A new team member can orient themselves using only these docs
+
+### Step 6: Establish Maintenance Governance
+
+Documentation that isn't maintained becomes misleading. Define when and how diagrams get updated:
+
+**Update triggers:**
+- New service or data store added
+- Service boundary changed or service split/merged
+- New external dependency integrated
+- ADR accepted that affects architecture (use `architecture-design` skill)
+
+**Promotion model:** Diagrams mature over time:
+```
+Conceptual sketch (idea / RFC)
+   ↓  proves valuable, referenced repeatedly
+Runtime diagram (structured, tooled)
+   ↓  represents stable structural change
+Canonical diagram (source of truth)
+```
+
+**Review cadence:**
+- Canonical diagrams: review quarterly or after major architecture changes
+- Runtime diagrams: review when deployment topology changes
+- Conceptual diagrams: no formal review — treat as disposable
+
+## Principles Applied
+
+- **KISS**: Start with one system context diagram. Add layers only when they serve a clear audience.
+- **YAGNI**: A monolith doesn't need four C4 levels. Document what exists, not what might exist.
+- **Separation of Concerns**: Each abstraction level serves a different purpose. Don't mix structural truth with runtime behavior in the same diagram.
+- **DRY**: Canonical diagrams are the single source of truth for system structure. Other diagrams reference — never redefine — those elements.
+
+## Cross-Skill References
+
+- **architecture-design**: For making and documenting architectural decisions (ADRs). Use when a documentation effort reveals undocumented or contested decisions.
+- **project-documentation**: For README, CONTRIBUTING, API docs, and other non-architecture documentation.
+- **infrastructure-as-code**: For aligning runtime/deployment diagrams with actual IaC definitions.
+- **containerization**: For Kubernetes-specific topology diagrams that align with actual manifests.

package/skills/architecture-documentation/evals/evals.json

@@ -0,0 +1,44 @@
+[
+  {
+    "name": "Microservices architecture documentation from scratch",
+    "description": "Happy path: documenting a moderately complex distributed system for new hires",
+    "prompt": "We have a system with 8 microservices: a React frontend, a BFF API gateway, a user service, an order service, a payment service, a notification service, a search service, and a recommendation engine. We use PostgreSQL, Redis, RabbitMQ, and Elasticsearch. Everything runs on Kubernetes. We have no architecture diagrams and need to document this for new hires joining next month.",
+    "assertions": [
+      "Recommends starting with a system context diagram showing the system, users, and external dependencies",
+      "Identifies that all three abstraction levels are appropriate for this complexity",
+      "Prioritizes canonical and conceptual levels for the onboarding use case",
+      "Proposes a repository structure for organizing diagrams",
+      "Establishes or recommends a glossary with consistent naming for all 8 services",
+      "Suggests specific tooling appropriate for each level",
+      "Does not try to create all diagrams at once — suggests a phased approach",
+      "Produces at least a system context diagram as the first deliverable"
+    ]
+  },
+  {
+    "name": "Over-documentation for simple system",
+    "description": "Edge case: pushing back on unnecessary documentation complexity",
+    "prompt": "I have a simple CRUD application — Express.js backend, PostgreSQL database, deployed on a single EC2 instance behind nginx. My manager read about C4 and wants me to create all four C4 levels plus deployment diagrams plus data flow diagrams. Can you help me set this up?",
+    "assertions": [
+      "Pushes back on creating all four C4 levels for a simple monolith",
+      "Applies YAGNI — recommends only the diagrams that add value for this system's complexity",
+      "Recommends at most a system context and a single container diagram",
+      "Explains that Code-level C4 diagrams are almost never worth maintaining manually",
+      "Does not refuse the request entirely — provides a pragmatic subset",
+      "Suggests conceptual-level documentation may be sufficient for this system",
+      "Explains what would trigger the need for more detailed documentation in the future"
+    ]
+  },
+  {
+    "name": "Architecture decision vs architecture documentation",
+    "description": "Scope boundary: separating decision-making from documentation",
+    "prompt": "We're debating whether to extract our authentication logic into a separate service or keep it in the monolith. Can you also create architecture diagrams showing what the system would look like after the split?",
+    "assertions": [
+      "Recognizes the decision-making aspect and defers to the architecture-design skill for the ADR",
+      "Does not make the architectural decision within this skill's workflow",
+      "Offers to diagram the proposed architecture as a conceptual or draft diagram to support the decision",
+      "Clearly separates the decision process from the documentation process",
+      "If diagramming the proposed state, labels it as non-canonical since the decision hasn't been made yet",
+      "Suggests that canonical diagrams should only be updated after the decision is accepted"
+    ]
+  }
+]

package/skills/architecture-documentation/references/abstraction-levels.md

@@ -0,0 +1,91 @@
+# Abstraction Levels for Architecture Documentation
+
+Architecture documentation must operate at different abstraction levels to serve different audiences and purposes. Mixing levels in a single diagram creates confusion — a system context diagram cluttered with Kubernetes pods, or a deployment diagram that also tries to show business boundaries.
+
+## The Three Levels
+
+### Canonical (Structural Truth)
+
+The authoritative representation of what exists in the system. Uses the C4 model hierarchy:
+
+1. **System Context**: The system as a whole, its users, and external systems it depends on or integrates with. Every architecture should have this diagram.
+2. **Container**: The major deployable units inside the system — services, databases, message brokers, frontends, batch jobs. This is the most commonly useful C4 level.
+3. **Component**: Internal structure of a single container — modules, major classes, or subsystems. Only create when a service is complex enough that its internals are architecturally significant.
+4. **Code**: Class diagrams or module diagrams. Almost never worth maintaining manually — IDEs generate these on demand.
+
+**Rules:**
+- Canonical diagrams define system structure. If a service, data store, or external dependency exists, it should appear here.
+- Changes to canonical diagrams represent actual architectural changes — these should be infrequent and deliberate.
+- Canonical diagrams should be minimal and stable. Resist adding runtime or deployment details.
+
+### Runtime (Operational Behavior)
+
+How the system behaves when running. These diagrams show movement, flow, and infrastructure:
+
+- **Data flow diagrams**: How data moves through the system (e.g., RAG pipeline, ETL flow, event streaming)
+- **Sequence diagrams**: Step-by-step interaction for key scenarios (e.g., checkout flow, authentication handshake)
+- **Deployment/infrastructure topology**: Where code runs — Kubernetes clusters, cloud regions, CDNs, load balancers
+- **Integration diagrams**: How external systems connect at runtime (webhooks, polling, file drops)
+
+**Rules:**
+- Runtime diagrams must reference elements defined in canonical diagrams. Don't introduce new system names here.
+- Infrastructure-only components (load balancers, ingress controllers, service meshes, CI runners) are exceptions — they may appear only at the runtime level since they're not architecturally significant at the canonical level.
+- Focus on relationships and flows, not ownership or boundaries (those belong in canonical diagrams).
+
+### Conceptual (Communication)
+
+Lightweight diagrams for human understanding. These serve communication, not governance:
+
+- **Onboarding overviews**: Simplified system maps for new team members
+- **RFC/ADR illustrations**: Quick visuals to support a written proposal
+- **Presentation diagrams**: Architecture slides for stakeholders
+- **PR explanations**: "Here's what this change does" diagrams
+
+**Rules:**
+- Conceptual diagrams are non-canonical. They may simplify, omit, or group elements for clarity.
+- They should never be treated as the source of truth.
+- Label them clearly (e.g., "Simplified overview — see canonical diagrams for authoritative structure").
+- They are disposable by default. If one proves valuable and gets referenced repeatedly, promote it.
+
+## Traceability
+
+Elements should be traceable across levels:
+
+```
+Decision (ADR)
+   ↓  justifies why the architecture looks this way
+Canonical (C4)
+   ↓  defines what exists structurally
+Runtime (D2/sequence/deployment)
+   ↓  shows how it behaves operationally
+Code / Deployment
+   ↓  implements the architecture
+```
+
+**Practical traceability rules:**
+- Every container in a canonical diagram should correspond to a deployable unit in the codebase
+- Every element in a runtime diagram should trace to a container or external system in the canonical diagram (with the infrastructure-only exception noted above)
+- ADRs that change architecture should reference the canonical diagrams they affect
+- Conceptual diagrams are exempt from strict traceability — they serve communication, not governance
+
+## The Promotion Model
+
+Diagrams have a maturity lifecycle. Not every sketch needs to become a canonical diagram.
+
+```
+Conceptual (sketch / idea / RFC)
+   ↓  proves valuable — referenced repeatedly, used for onboarding
+Runtime (structured, uses proper tooling, follows naming conventions)
+   ↓  represents a stable structural change to the system
+Canonical (source of truth, reviewed, maintained)
+```
+
+**When to promote:**
+- A conceptual diagram gets referenced in 3+ documents or conversations → consider promoting to runtime level with proper tooling
+- A runtime diagram reveals a structural boundary that isn't captured canonically → update the canonical diagrams
+- An ADR introduces a new service or changes boundaries → update canonical diagrams directly (skip promotion)
+
+**When NOT to promote:**
+- A conceptual diagram was useful for one presentation but isn't referenced again → let it age naturally
+- A runtime diagram shows a temporary deployment configuration → keep at runtime level
+- The system is simple enough that canonical diagrams capture everything needed → don't create runtime diagrams just to have them

package/skills/architecture-documentation/references/diagram-tooling.md

@@ -0,0 +1,141 @@
+# Diagram Tooling Reference
+
+This reference helps select and use diagram tools for architecture documentation. The framework is tool-agnostic — choose tools that fit your team. What matters is consistent usage and docs-as-code practices, not specific tools.
+
+## Tool Comparison
+
+### Canonical Architecture (C4 Model)
+
+| Tool | Pros | Cons | Best For |
+|------|------|------|----------|
+| **C4-PlantUML** | Mature ecosystem, CI-friendly, extensive C4 support | Verbose syntax, layout control is limited | Teams already using PlantUML |
+| **Structurizr DSL** | Purpose-built for C4, model-first approach, generates multiple views from one model | Requires Structurizr tooling (Lite/Cloud) | Teams wanting a single model with multiple diagram outputs |
+| **Mermaid C4 extension** | Renders in GitHub/GitLab markdown natively, low friction | Limited C4 support, fewer styling options | Teams prioritizing zero-tooling rendering |
+| **Ilograph** | Interactive, explorable diagrams | Commercial tool, not text-only | Teams wanting interactive exploration |
+
+### Runtime / Infrastructure / Data Flow
+
+| Tool | Pros | Cons | Best For |
+|------|------|------|----------|
+| **D2** | Clean syntax, auto-layout, built-in themes, good for topology | Newer tool, smaller community | Infrastructure topology, data flows |
+| **Mermaid** | Wide rendering support, familiar syntax | Limited layout control, complex diagrams get messy | Sequence diagrams, simple flowcharts |
+| **PlantUML** | Sequence and deployment diagram support, mature | Verbose, requires server for rendering | Detailed sequence diagrams |
+| **Diagrams (Python)** | Programmatic, uses real cloud provider icons | Requires Python, not declarative | Cloud architecture with provider-specific icons |
+
+### Conceptual / Communication
+
+| Tool | Pros | Cons | Best For |
+|------|------|------|----------|
+| **Mermaid** | Renders in markdown, no build step | Limited styling | Quick diagrams in docs and PRs |
+| **Excalidraw** | Hand-drawn aesthetic, collaborative | Not text-based (JSON), harder to diff | Whiteboard-style brainstorming |
+| **ASCII diagrams** | Zero dependencies, works everywhere | Limited expressiveness | Inline code comments, terminal output |
+
+## Docs-as-Code Requirements
+
+Regardless of tool choice, architecture diagrams should follow docs-as-code practices:
+
+1. **Text-based source**: Diagrams defined in text files (`.puml`, `.d2`, `.mmd`, `.dsl`), not binary formats
+2. **Version-controlled**: Stored in git alongside code or in a central docs repo
+3. **Reviewable**: Changes visible in PR diffs (text diffs for source, rendered previews where possible)
+4. **Renderable in CI**: Automated rendering to PNG/SVG on merge (optional but recommended)
+5. **No manual editing of rendered output**: Always regenerate from source
+
+## Quick Syntax Reference
+
+### C4-PlantUML — System Context
+
+```plantuml
+@startuml
+!include <C4/C4_Context>
+
+title System Context - Payments Platform
+
+Person(user, "Customer", "Places orders and makes payments")
+System(payments, "Payments Platform", "Processes payments and manages billing")
+System_Ext(stripe, "Stripe", "Payment gateway")
+System_Ext(bank, "Bank API", "Account verification")
+
+Rel(user, payments, "Submits payment")
+Rel(payments, stripe, "Processes charge", "HTTPS/REST")
+Rel(payments, bank, "Verifies account", "HTTPS/REST")
+@enduml
+```
+
+### Structurizr DSL — Container
+
+```dsl
+workspace {
+    model {
+        customer = person "Customer"
+        payments = softwareSystem "Payments Platform" {
+            api = container "Payments API" "Handles payment requests" "Node.js"
+            db = container "Payments DB" "Stores transactions" "PostgreSQL"
+            worker = container "Payment Worker" "Async payment processing" "Node.js"
+            queue = container "Job Queue" "Payment job queue" "Redis"
+        }
+        stripe = softwareSystem "Stripe" "Payment gateway"
+
+        customer -> api "Submits payment"
+        api -> queue "Enqueues job"
+        worker -> queue "Dequeues job"
+        worker -> stripe "Processes charge"
+        api -> db "Reads/writes"
+        worker -> db "Updates status"
+    }
+    views {
+        container payments {
+            include *
+            autolayout lr
+        }
+    }
+}
+```
+
+### D2 — Runtime Flow
+
+```d2
+direction: right
+
+customer: Customer {shape: person}
+lb: Load Balancer {shape: cloud}
+api: Payments API
+queue: Redis Queue
+worker: Payment Worker
+stripe: Stripe API {style.stroke-dash: 3}
+db: PostgreSQL
+
+customer -> lb: HTTPS
+lb -> api: Route
+api -> queue: Enqueue job
+api -> db: Read/write
+queue -> worker: Dequeue
+worker -> stripe: Process charge
+worker -> db: Update status
+```
+
+### Mermaid — Conceptual Overview
+
+```mermaid
+graph LR
+    Customer -->|HTTPS| API[Payments API]
+    API --> Queue[Redis Queue]
+    API --> DB[(PostgreSQL)]
+    Queue --> Worker[Payment Worker]
+    Worker --> Stripe[Stripe API]
+    Worker --> DB
+```
+
+## Rendering Pipeline
+
+For teams that want automated rendering:
+
+**GitHub Actions example (Mermaid + PlantUML):**
+- Mermaid renders natively in GitHub markdown — no action needed
+- PlantUML: use a GitHub Action with the PlantUML server to render `.puml` to `.svg` on push
+- D2: use the `d2` CLI in CI to render `.d2` to `.svg`
+
+**Structurizr:**
+- Use Structurizr Lite (Docker) locally or in CI to render from the DSL
+- Generates multiple diagram views from a single model file
+
+**Keep rendered outputs in a predictable location** (e.g., `docs/architecture/rendered/`) and add them to `.gitignore` if regenerated in CI, or commit them if the team prefers browsable outputs without running tools.