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.
For complete diagram examples, see examples.md in this skill directory.
Scope
- Architecture diagrams (C4-style, layered, microservice topology)
- Sequence diagrams (API flows, async/await, middleware pipeline)
- Class diagrams (domain models, DI graphs, inheritance)
- Deployment diagrams (containers, Kubernetes, CI/CD flow)
- ER diagrams (EF Core models, database schema)
- Diagram-as-code conventions (naming, grouping, dark mode)
Out of scope
- Documentation platform configuration for Mermaid rendering -- see [skill:dotnet-documentation-strategy]
- GitHub-native doc structure and README patterns -- see [skill:dotnet-github-docs]
- CI/CD pipeline deployment of doc sites -- 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.
Supported Diagram Types
Architecture Diagrams
- C4-Style Context -- system in its environment with external actors (10-12 nodes max)
- C4-Style Container -- high-level technology choices and interactions (15-20 nodes max)
- C4-Style Component -- internal structure of a single service (15-20 nodes max)
- Layered Architecture -- Presentation, Application, Domain, Infrastructure layers
- Microservice Topology -- services, messaging, observability connections
Sequence Diagrams
- API Request Flow -- HTTP request through middleware, auth, controller, service, database
- Async/Await Pattern -- thread pool behavior, cache miss/hit, await points
- Middleware Pipeline -- request/response flow through ASP.NET Core middleware chain
- Authentication Flow -- OAuth 2.0/OIDC with BFF pattern
Class Diagrams
- Domain Model -- entities, value objects, enumerations, relationships
- DI Registration Graph -- singleton/scoped/transient lifetime visualization
- Interface Implementation Hierarchy -- generic repository pattern with inheritance
Deployment Diagrams
- Container Deployment -- Docker host with app, database, cache, reverse proxy
- Kubernetes Pod Layout -- cluster, namespace, deployments, services, config
- CI/CD Pipeline Flow -- build, test, package, deploy stages
ER Diagrams
- EF Core Relationship Visualization -- one-to-many, one-to-one, many-to-many with entity details
- Database Schema with Indexes -- audit logs, soft delete, multi-tenant patterns
State Diagrams
- Order Processing Workflow -- draft through delivery with payment states
- Saga Pattern -- distributed transaction with compensation steps
- State Machine Pattern -- MassTransit-style event-driven state transitions
Flowcharts
- Framework Selection Decision Tree -- web vs desktop, API vs UI, framework choices
- Architecture Decision Flowchart -- monolith vs microservices, communication patterns
Diagram-as-Code Conventions
Naming Conventions
- Use PascalCase for node IDs:
OrderService, CustomerDB
- Use descriptive labels with technology:
API["Order API<br/>(ASP.NET Core)"]
- Use consistent abbreviations: DB (database), API (endpoint), SVC (service), MQ (message queue)
- Prefix subgraphs with the layer or tier name:
subgraph DataTier["Data Tier"]
Grouping Patterns
- Group by architectural layer (Presentation, Application, Domain, Infrastructure)
- Group by deployment boundary (containers, pods, VMs)
- Group by team ownership in microservice diagrams
- Use subgraphs for visual grouping -- limit nesting to 2 levels for readability
GitHub Rendering Tips
- GitHub renders Mermaid in fenced code blocks with the
mermaid language identifier in Markdown files, issues, PRs,
and discussions
- Maximum recommended diagram size: ~50 nodes for readable rendering
- GitHub uses a light theme by default -- avoid light-colored fill that disappears on white backgrounds
- Diagrams auto-size to container width -- keep node labels concise (under 30 characters per line)
- Use
<br/> for line breaks within node labels (not \n)
- Test diagrams in GitHub before merging -- syntax errors render as raw text
Dark Mode Considerations
- Avoid hardcoded colors that fail in dark mode -- use Mermaid theme variables when possible
- Default Mermaid colors work in both light and dark themes on GitHub
- If using custom
style directives, test in both GitHub light and dark modes
- Prefer semantic
classDef styles over inline style for maintainability
- The
neutral theme (%%{init: {'theme': 'neutral'}}%%) provides the best cross-theme compatibility on GitHub
Diagram Size Guidelines
| Diagram Type |
Recommended Max Nodes |
Notes |
| C4 Context |
10-12 |
One system + external actors |
| C4 Container |
15-20 |
Internal containers + data stores |
| C4 Component |
15-20 |
Single service internals |
| Sequence |
8 participants |
More becomes unreadable |
| Class |
10-15 classes |
Split into multiple diagrams |
| ER |
10-12 entities |
Split by bounded context |
| State |
12-15 states |
Split complex workflows |
| Flowchart |
15-20 nodes |
Keep decision trees focused |
Agent Gotchas
Always use .NET-specific content in diagrams -- do not generate generic diagrams. Use real .NET types
(DbContext, IRepository, MediatR), real .NET tools (EF Core, MassTransit, YARP), and real .NET patterns (middleware
pipeline, DI registration).
Keep diagrams under 50 nodes -- larger diagrams render poorly on GitHub and doc sites. Split complex
architectures into multiple focused diagrams (context, container, component) rather than one monolithic diagram.
Use <br/> for line breaks in node labels, not \n -- Mermaid renders \n literally as text. Multi-line labels
require <br/> HTML tags.
Test Mermaid syntax before committing -- syntax errors cause GitHub to render raw text instead of a diagram. Use
the Mermaid Live Editor (https://mermaid.live) or a local preview tool to validate.
ER diagram relationship notation follows Mermaid syntax, not UML -- use ||--o{ for one-to-many, ||--|| for
one-to-one. Do not use UML multiplicity notation.
Use the neutral theme for GitHub compatibility -- %%{init: {'theme': 'neutral'}}%% provides the best
rendering in both light and dark modes.
Sequence diagram participant names cannot contain special characters -- use participant DB as "SQL Server"
alias syntax for names with spaces or special characters.
Nested generics (Task~List~T~~) may not render on all Mermaid versions -- the double ~~ at the end of nested
generic types requires Mermaid v10.3+. Test rendering in your target environment before committing complex generic
type diagrams.
Do not use Font Awesome icon syntax (fa:fa-user) in diagrams intended for GitHub -- GitHub's native Mermaid
renderer does not load Font Awesome CSS. Icons render as literal text. Use plain text labels instead.
Do not configure Mermaid rendering in doc platforms -- platform setup (Starlight remark plugin, Docusaurus theme,
DocFX template) belongs to [skill:dotnet-documentation-strategy]. This skill provides the diagram content only.
Code Navigation (Serena MCP)
Primary approach: Use Serena symbol operations for efficient code navigation:
- Find definitions:
serena_find_symbol instead of text search
- Understand structure:
serena_get_symbols_overview for file organization
- Track references:
serena_find_referencing_symbols for impact analysis
- Precise edits:
serena_replace_symbol_body for clean modifications
When to use Serena vs traditional tools:
- Use Serena: Navigation, refactoring, dependency analysis, precise edits
- Use Read/Grep: Reading full files, pattern matching, simple text operations
- Fallback: If Serena unavailable, traditional tools work fine
Example workflow:
# Instead of:
Read: src/Services/OrderService.cs
Grep: "public void ProcessOrder"
# Use:
serena_find_symbol: "OrderService/ProcessOrder"
serena_get_symbols_overview: "src/Services/OrderService.cs"
1---2name: dotnet-mermaid-diagrams-83description: >-4 Creates Mermaid diagrams for .NET. Architecture, sequence, class, deployment,5 ER, flowcharts.6allowed-tools:7 - Read8 - Grep9 - Glob10 - Bash11 - Write12 - Edit13metadata:14 source: https://skillmd.com/skills/rudironsoni/dotnet-mermaid-diagrams-815---1617# dotnet-mermaid-diagrams1819Mermaid diagram reference for .NET projects: architecture diagrams (C4-style context, container, component views,20layered architecture, microservice topology), sequence diagrams (API request flows, async/await patterns, middleware21pipeline, authentication flows), class diagrams (domain models, DI registration graphs, inheritance hierarchies,22interface implementations), deployment diagrams (container deployment, Kubernetes pod layout, CI/CD pipeline flow), ER23diagrams (EF Core model relationships, database schema visualization), state diagrams (workflow states, order24processing, saga patterns, state machine patterns), and flowcharts (decision trees, framework selection, architecture25choices). Includes diagram-as-code conventions for naming, grouping, GitHub rendering, and dark mode considerations.2627**Version assumptions:** Mermaid v10+ (supported by GitHub, Starlight, Docusaurus natively). GitHub renders Mermaid in28Markdown files, issues, PRs, and discussions. .NET 8.0+ baseline for code examples.2930For complete diagram examples, see `examples.md` in this skill directory.3132## Scope3334- Architecture diagrams (C4-style, layered, microservice topology)35- Sequence diagrams (API flows, async/await, middleware pipeline)36- Class diagrams (domain models, DI graphs, inheritance)37- Deployment diagrams (containers, Kubernetes, CI/CD flow)38- ER diagrams (EF Core models, database schema)39- Diagram-as-code conventions (naming, grouping, dark mode)4041## Out of scope4243- Documentation platform configuration for Mermaid rendering -- see [skill:dotnet-documentation-strategy]44- GitHub-native doc structure and README patterns -- see [skill:dotnet-github-docs]45- CI/CD pipeline deployment of doc sites -- see [skill:dotnet-gha-deploy]4647Cross-references: [skill:dotnet-documentation-strategy] for Mermaid rendering setup across doc platforms,48[skill:dotnet-github-docs] for embedding diagrams in GitHub-native docs, [skill:dotnet-gha-deploy] for doc site49deployment.5051---5253## Supported Diagram Types5455### Architecture Diagrams5657- **C4-Style Context** -- system in its environment with external actors (10-12 nodes max)58- **C4-Style Container** -- high-level technology choices and interactions (15-20 nodes max)59- **C4-Style Component** -- internal structure of a single service (15-20 nodes max)60- **Layered Architecture** -- Presentation, Application, Domain, Infrastructure layers61- **Microservice Topology** -- services, messaging, observability connections6263### Sequence Diagrams6465- **API Request Flow** -- HTTP request through middleware, auth, controller, service, database66- **Async/Await Pattern** -- thread pool behavior, cache miss/hit, await points67- **Middleware Pipeline** -- request/response flow through ASP.NET Core middleware chain68- **Authentication Flow** -- OAuth 2.0/OIDC with BFF pattern6970### Class Diagrams7172- **Domain Model** -- entities, value objects, enumerations, relationships73- **DI Registration Graph** -- singleton/scoped/transient lifetime visualization74- **Interface Implementation Hierarchy** -- generic repository pattern with inheritance7576### Deployment Diagrams7778- **Container Deployment** -- Docker host with app, database, cache, reverse proxy79- **Kubernetes Pod Layout** -- cluster, namespace, deployments, services, config80- **CI/CD Pipeline Flow** -- build, test, package, deploy stages8182### ER Diagrams8384- **EF Core Relationship Visualization** -- one-to-many, one-to-one, many-to-many with entity details85- **Database Schema with Indexes** -- audit logs, soft delete, multi-tenant patterns8687### State Diagrams8889- **Order Processing Workflow** -- draft through delivery with payment states90- **Saga Pattern** -- distributed transaction with compensation steps91- **State Machine Pattern** -- MassTransit-style event-driven state transitions9293### Flowcharts9495- **Framework Selection Decision Tree** -- web vs desktop, API vs UI, framework choices96- **Architecture Decision Flowchart** -- monolith vs microservices, communication patterns9798---99100## Diagram-as-Code Conventions101102### Naming Conventions103104- Use PascalCase for node IDs: `OrderService`, `CustomerDB`105- Use descriptive labels with technology: `API["Order API<br/>(ASP.NET Core)"]`106- Use consistent abbreviations: DB (database), API (endpoint), SVC (service), MQ (message queue)107- Prefix subgraphs with the layer or tier name: `subgraph DataTier["Data Tier"]`108109### Grouping Patterns110111- Group by architectural layer (Presentation, Application, Domain, Infrastructure)112- Group by deployment boundary (containers, pods, VMs)113- Group by team ownership in microservice diagrams114- Use subgraphs for visual grouping -- limit nesting to 2 levels for readability115116### GitHub Rendering Tips117118- GitHub renders Mermaid in fenced code blocks with the `mermaid` language identifier in Markdown files, issues, PRs,119 and discussions120- Maximum recommended diagram size: ~50 nodes for readable rendering121- GitHub uses a light theme by default -- avoid light-colored fill that disappears on white backgrounds122- Diagrams auto-size to container width -- keep node labels concise (under 30 characters per line)123- Use `<br/>` for line breaks within node labels (not `\n`)124- Test diagrams in GitHub before merging -- syntax errors render as raw text125126### Dark Mode Considerations127128- Avoid hardcoded colors that fail in dark mode -- use Mermaid theme variables when possible129- Default Mermaid colors work in both light and dark themes on GitHub130- If using custom `style` directives, test in both GitHub light and dark modes131- Prefer semantic `classDef` styles over inline `style` for maintainability132- The `neutral` theme (`%%{init: {'theme': 'neutral'}}%%`) provides the best cross-theme compatibility on GitHub133134### Diagram Size Guidelines135136| Diagram Type | Recommended Max Nodes | Notes |137| ------------ | --------------------- | --------------------------------- |138| C4 Context | 10-12 | One system + external actors |139| C4 Container | 15-20 | Internal containers + data stores |140| C4 Component | 15-20 | Single service internals |141| Sequence | 8 participants | More becomes unreadable |142| Class | 10-15 classes | Split into multiple diagrams |143| ER | 10-12 entities | Split by bounded context |144| State | 12-15 states | Split complex workflows |145| Flowchart | 15-20 nodes | Keep decision trees focused |146147---148149## Agent Gotchas1501511. **Always use `.NET-specific content` in diagrams** -- do not generate generic diagrams. Use real .NET types152 (DbContext, IRepository, MediatR), real .NET tools (EF Core, MassTransit, YARP), and real .NET patterns (middleware153 pipeline, DI registration).1541551. **Keep diagrams under 50 nodes** -- larger diagrams render poorly on GitHub and doc sites. Split complex156 architectures into multiple focused diagrams (context, container, component) rather than one monolithic diagram.1571581. **Use `<br/>` for line breaks in node labels, not `\n`** -- Mermaid renders `\n` literally as text. Multi-line labels159 require `<br/>` HTML tags.1601611. **Test Mermaid syntax before committing** -- syntax errors cause GitHub to render raw text instead of a diagram. Use162 the Mermaid Live Editor (https://mermaid.live) or a local preview tool to validate.1631641. **ER diagram relationship notation follows Mermaid syntax, not UML** -- use `||--o{` for one-to-many, `||--||` for165 one-to-one. Do not use UML multiplicity notation.1661671. **Use the `neutral` theme for GitHub compatibility** -- `%%{init: {'theme': 'neutral'}}%%` provides the best168 rendering in both light and dark modes.1691701. **Sequence diagram participant names cannot contain special characters** -- use `participant DB as "SQL Server"`171 alias syntax for names with spaces or special characters.1721731. **Nested generics (`Task~List~T~~`) may not render on all Mermaid versions** -- the double `~~` at the end of nested174 generic types requires Mermaid v10.3+. Test rendering in your target environment before committing complex generic175 type diagrams.1761771. **Do not use Font Awesome icon syntax (`fa:fa-user`) in diagrams intended for GitHub** -- GitHub's native Mermaid178 renderer does not load Font Awesome CSS. Icons render as literal text. Use plain text labels instead.1791801. **Do not configure Mermaid rendering in doc platforms** -- platform setup (Starlight remark plugin, Docusaurus theme,181 DocFX template) belongs to [skill:dotnet-documentation-strategy]. This skill provides the diagram content only.182183## Code Navigation (Serena MCP)184185**Primary approach:** Use Serena symbol operations for efficient code navigation:1861871. **Find definitions**: `serena_find_symbol` instead of text search1882. **Understand structure**: `serena_get_symbols_overview` for file organization1893. **Track references**: `serena_find_referencing_symbols` for impact analysis1904. **Precise edits**: `serena_replace_symbol_body` for clean modifications191192**When to use Serena vs traditional tools:**193194- **Use Serena**: Navigation, refactoring, dependency analysis, precise edits195- **Use Read/Grep**: Reading full files, pattern matching, simple text operations196- **Fallback**: If Serena unavailable, traditional tools work fine197198**Example workflow:**199200```text201# Instead of:202Read: src/Services/OrderService.cs203Grep: "public void ProcessOrder"204205# Use:206serena_find_symbol: "OrderService/ProcessOrder"207serena_get_symbols_overview: "src/Services/OrderService.cs"208```