dotnet-mermaid-diagrams

What this skill does

# dotnet-mermaid-diagrams

Mermaid diagram reference for .NET projects: architecture diagrams (C4-style context, container, component views, layered architecture, microservice topology), sequence diagrams (API request flows, async/await patterns, middleware pipeline, authentication flows), class diagrams (domain models, DI registration graphs, inheritance hierarchies, interface implementations), deployment diagrams (container deployment, Kubernetes pod layout, CI/CD pipeline flow), ER diagrams (EF Core model relationships, database schema visualization), state diagrams (workflow states, order processing, saga patterns, state machine patterns), and flowcharts (decision trees, framework selection, architecture choices). Includes diagram-as-code conventions for naming, grouping, GitHub rendering, and dark mode considerations.

**Version assumptions:** Mermaid v10+ (supported by GitHub, Starlight, Docusaurus natively). GitHub renders Mermaid in Markdown files, issues, PRs, and discussions. .NET 8.0+ baseline for code examples.

**Scope boundary:** This skill owns Mermaid diagram syntax and .NET-specific diagram patterns -- the actual diagram content, conventions, and rendering tips. Documentation platform setup for Mermaid rendering (Starlight plugins, Docusaurus themes, DocFX templates) is owned by [skill:dotnet-documentation-strategy]. GitHub-native documentation structure (README, CONTRIBUTING, templates) is owned by [skill:dotnet-github-docs].

**Out of scope:** Documentation platform configuration for Mermaid rendering -- see [skill:dotnet-documentation-strategy]. GitHub-native doc structure and README patterns where diagrams are embedded -- see [skill:dotnet-github-docs]. CI/CD pipeline deployment of doc sites containing diagrams -- see [skill:dotnet-gha-deploy].

Cross-references: [skill:dotnet-documentation-strategy] for Mermaid rendering setup across doc platforms, [skill:dotnet-github-docs] for embedding diagrams in GitHub-native docs, [skill:dotnet-gha-deploy] for doc site deployment.

---

## Architecture Diagrams

### C4-Style Context Diagram

Shows the system in its environment with external actors and systems.

```mermaid
graph TB
    User["End User<br/>(Browser/Mobile)"]
    Admin["Admin<br/>(Internal)"]

    subgraph System["My .NET Application"]
        API["ASP.NET Core API<br/>(.NET 8)"]
    end

    ExtAuth["Identity Provider<br/>(Azure AD / Auth0)"]
    ExtEmail["Email Service<br/>(SendGrid)"]
    ExtPay["Payment Gateway<br/>(Stripe)"]

    User -->|"HTTPS"| API
    Admin -->|"HTTPS"| API
    API -->|"OAuth 2.0"| ExtAuth
    API -->|"SMTP/API"| ExtEmail
    API -->|"REST API"| ExtPay
```

### C4-Style Container Diagram

Shows the high-level technology choices and their interactions.

```mermaid
graph TB
    subgraph Client["Client Tier"]
        SPA["Blazor WASM<br/>(WebAssembly)"]
        Mobile["MAUI App<br/>(.NET 8)"]
    end

    subgraph API_Tier["API Tier"]
        Gateway["API Gateway<br/>(YARP)"]
        OrderAPI["Order Service<br/>(ASP.NET Core)"]
        CatalogAPI["Catalog Service<br/>(ASP.NET Core)"]
        IdentityAPI["Identity Service<br/>(Duende IdentityServer)"]
    end

    subgraph Data_Tier["Data Tier"]
        OrderDB[("Order DB<br/>(SQL Server)")]
        CatalogDB[("Catalog DB<br/>(PostgreSQL)")]
        Cache[("Redis Cache")]
        Bus["Message Bus<br/>(RabbitMQ)"]
    end

    SPA -->|"HTTPS"| Gateway
    Mobile -->|"HTTPS"| Gateway
    Gateway --> OrderAPI
    Gateway --> CatalogAPI
    Gateway --> IdentityAPI
    OrderAPI --> OrderDB
    OrderAPI --> Cache
    OrderAPI --> Bus
    CatalogAPI --> CatalogDB
    CatalogAPI --> Cache
    Bus --> CatalogAPI
```

### C4-Style Component Diagram

Shows internal structure of a single service.

```mermaid
graph TB
    subgraph OrderService["Order Service"]
        Controllers["Controllers<br/>(API Endpoints)"]
        Validators["FluentValidation<br/>(Request Validators)"]
        Handlers["MediatR Handlers<br/>(Business Logic)"]
        DomainModels["Domain Models<br/>(Entities, Value Objects)"]
        Repos["Repositories<br/>(EF Core)"]
        Events["Domain Events<br/>(MediatR Notifications)"]
        IntEvents["Integration Events<br/>(MassTransit)"]
    end

    Controllers --> Validators
    Controllers --> Handlers
    Handlers --> DomainModels
    Handlers --> Repos
    Handlers --> Events
    Events --> IntEvents
```

### Layered Architecture

```mermaid
graph TB
    subgraph Presentation["Presentation Layer"]
        API["ASP.NET Core Controllers / Minimal APIs"]
        Blazor["Blazor Components"]
    end

    subgraph Application["Application Layer"]
        Services["Application Services"]
        DTOs["DTOs / View Models"]
        Mappings["AutoMapper Profiles"]
        CQRS["MediatR Handlers"]
    end

    subgraph Domain["Domain Layer"]
        Entities["Entities"]
        ValueObjects["Value Objects"]
        DomainEvents["Domain Events"]
        Interfaces["Repository Interfaces"]
    end

    subgraph Infrastructure["Infrastructure Layer"]
        EFCore["EF Core DbContext"]
        Repositories["Repository Implementations"]
        ExternalServices["External Service Clients"]
        Messaging["MassTransit / RabbitMQ"]
    end

    Presentation --> Application
    Application --> Domain
    Infrastructure --> Domain
    Infrastructure -.->|"implements"| Interfaces
```

### Microservice Topology

```mermaid
graph LR
    subgraph Ingress
        LB["Load Balancer"]
        GW["API Gateway<br/>(YARP)"]
    end

    subgraph Services
        S1["Order Service"]
        S2["Catalog Service"]
        S3["Identity Service"]
        S4["Notification Service"]
    end

    subgraph Messaging
        MQ["RabbitMQ"]
    end

    subgraph Observability
        SEQ["Seq / ELK"]
        OTEL["OpenTelemetry Collector"]
    end

    LB --> GW
    GW --> S1
    GW --> S2
    GW --> S3
    S1 -->|"publish"| MQ
    MQ -->|"subscribe"| S2
    MQ -->|"subscribe"| S4
    S1 -.->|"traces"| OTEL
    S2 -.->|"traces"| OTEL
    S1 -.->|"logs"| SEQ
    S2 -.->|"logs"| SEQ
```

---

## Sequence Diagrams

### API Request Flow

```mermaid
sequenceDiagram
    participant Client
    participant Middleware as ASP.NET Middleware
    participant Auth as Authentication
    participant Controller
    participant Service
    participant DB as Database

    Client->>Middleware: POST /api/orders
    Middleware->>Auth: Validate JWT
    Auth-->>Middleware: Claims Principal
    Middleware->>Controller: OrdersController.Create()
    Controller->>Service: CreateOrderAsync(dto)
    Service->>DB: INSERT INTO Orders
    DB-->>Service: Order entity
    Service-->>Controller: OrderResponse
    Controller-->>Client: 201 Created
```

### Async/Await Pattern

```mermaid
sequenceDiagram
    participant Caller
    participant Service as OrderService
    participant Repo as IOrderRepository
    participant DB as SQL Server
    participant Cache as Redis

    Caller->>+Service: GetOrderAsync(id)
    Service->>+Cache: GetAsync(key)
    Cache-->>-Service: null (cache miss)
    Service->>+Repo: FindByIdAsync(id)
    Repo->>+DB: SELECT ... WHERE Id = @id
    Note over Repo,DB: await - thread returned to pool
    DB-->>-Repo: Row data
    Repo-->>-Service: Order entity
    Service->>+Cache: SetAsync(key, order, expiry)
    Note over Service,Cache: Fire-and-forget or await
    Cache-->>-Service: OK
    Service-->>-Caller: Order
```

### Middleware Pipeline

```mermaid
sequenceDiagram
    participant Client
    participant ExHandler as ExceptionHandler
    participant HSTS as HSTS Middleware
    participant Auth as Authentication
    participant Authz as Authorization
    participant CORS as CORS Middleware
    participant Routing as Routing
    participant Endpoint

    Client->>ExHandler: HTTP Request
    ExHandler->>HSTS: next()
    HSTS->>Auth: next()
    Auth->>Authz: next()
    Authz->>CORS: next()
    CORS->>Routing: next()
    Routing->>Endpoint: Matched endpoint
    Endpoint-->>Routing: Respons