Architecture Patterns Skill

CRITICAL: The description field above controls when Claude auto-loads this skill.

Overview

Provides comprehensive architecture design capabilities including mermaid diagram generation, architecture documentation templates, diagram validation, and pattern libraries for common architectural styles (microservices, RAG systems, full-stack applications).

Instructions

Create Architecture Documentation

Use bash scripts/create-architecture.sh <project-path> <architecture-type> to scaffold architecture docs
Architecture types: nextjs, fastapi, fullstack, microservices, rag, generic
Generates complete architecture overview with mermaid diagrams
Creates directory structure: docs/architecture/ with overview, components, data-flow, deployment
Includes table of contents and cross-references

Validate Mermaid Diagrams

Use bash scripts/validate-mermaid.sh <markdown-file> to check mermaid syntax
Validates diagram types: graph, flowchart, sequenceDiagram, classDiagram, erDiagram, stateDiagram
Checks for syntax errors, invalid node definitions, broken connections
Reports line numbers of errors
Provides suggestions for common fixes

Generate Diagram Placeholders

Use bash scripts/generate-diagrams.sh <output-dir> <diagram-types> to create diagram templates
Diagram types: component, data-flow, deployment, api, security, all
Creates markdown files with properly formatted mermaid code blocks
Includes comments explaining diagram sections
Provides example nodes and relationships

Update Existing Architecture

Use bash scripts/update-architecture.sh <architecture-file> <section> to add new sections
Sections: component, api, security, deployment, data-flow
Inserts section with proper heading hierarchy
Adds mermaid diagram placeholder
Preserves existing content and formatting

Export Diagrams to Files

Use bash scripts/export-diagrams.sh <markdown-file> <output-dir> to extract diagrams
Extracts all mermaid code blocks from documentation
Creates individual .mmd files for each diagram
Names files based on diagram titles or section headings
Generates index.md listing all exported diagrams

Available Scripts

create-architecture.sh: Scaffold complete architecture documentation with diagrams
validate-mermaid.sh: Validate mermaid diagram syntax and structure
generate-diagrams.sh: Create diagram template placeholders
update-architecture.sh: Add new sections to existing architecture docs
export-diagrams.sh: Extract mermaid diagrams to separate files

Templates

architecture-overview.md: Master architecture document template with TOC
component-diagram.md: Component architecture with relationships
data-flow-diagram.md: Data flow and processing pipelines
deployment-diagram.md: Infrastructure and deployment architecture
api-architecture.md: API design, endpoints, and authentication
security-architecture.md: Security patterns, auth flows, data protection

Examples

See examples/ directory for detailed usage examples:

example-nextjs-architecture.md - Next.js 15 App Router architecture
example-fastapi-architecture.md - FastAPI backend with PostgreSQL
example-fullstack-architecture.md - Full stack Next.js + FastAPI
example-ai-rag-architecture.md - RAG system with vector database
example-microservices-architecture.md - Microservices pattern with API gateway

Architecture Patterns

Component Architecture Pattern

Define system components and boundaries
Show component relationships and dependencies
Identify shared services and libraries
Document component responsibilities

Data Flow Pattern

Map data movement through system
Show transformation and processing stages
Identify data sources and destinations
Document data formats and protocols

Deployment Pattern

Define infrastructure components
Show service deployment topology
Identify scaling and redundancy strategies
Document environment configurations

API Architecture Pattern

Design API structure and endpoints
Define authentication and authorization
Show request/response flows
Document rate limiting and caching

Security Architecture Pattern

Define security layers and boundaries
Show authentication and authorization flows
Identify threat vectors and mitigations
Document encryption and data protection

Mermaid Diagram Types

Graph/Flowchart Diagrams

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

Sequence Diagrams

sequenceDiagram
    Client->>API: Request
    API->>Database: Query
    Database-->>API: Result
    API-->>Client: Response

Class Diagrams

classDiagram
    class User {
        +String name
        +login()
    }

Entity Relationship Diagrams

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ITEM : contains

State Diagrams

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing
    Processing --> Complete

Output Standards

Use mermaid for all diagrams (ensures renderability)
Include diagram titles and descriptions
Add comments explaining key components
Follow consistent naming conventions
Use proper markdown heading hierarchy
Include cross-references between documents

Validation Checks

Scripts perform these validations:

Mermaid syntax correctness
Node and edge definitions
Diagram type compatibility
Character escaping in labels
Proper code block formatting
Complete relationship definitions

Integration

This skill is used by:

planning:architecture command - Generate architecture docs
architecture-designer agent - Create system designs
Documentation tools - Include architecture diagrams
Code generation - Architecture-aware scaffolding

Best Practices

Start with high-level overview diagram
Create separate diagrams for each architectural concern
Use consistent component naming across diagrams
Include legends for symbols and colors
Keep diagrams focused and readable (max 15-20 nodes)
Document assumptions and constraints
Version architecture documents
Update diagrams when system changes

Common Diagram Patterns

Layered Architecture

graph TB
    UI[Presentation Layer]
    BL[Business Logic Layer]
    DA[Data Access Layer]
    DB[(Database)]
    UI --> BL
    BL --> DA
    DA --> DB

Event-Driven Architecture

graph LR
    P[Producer] -->|Event| Q[Event Queue]
    Q -->|Event| C1[Consumer 1]
    Q -->|Event| C2[Consumer 2]

Microservices Architecture

graph TB
    AG[API Gateway]
    AG --> MS1[Service 1]
    AG --> MS2[Service 2]
    AG --> MS3[Service 3]
    MS1 --> DB1[(DB 1)]
    MS2 --> DB2[(DB 2)]

Purpose: Comprehensive architecture design and documentation Used by: Architecture designers, system planners, documentation tools

architecture-patterns