common-architecture-diagramming

Standards for creating clear, audience-appropriate C4 and UML architecture diagrams with Mermaid. Use when producing system context diagrams, container views, sequence diagrams, or updating ARCHITECTURE.md files. (triggers: ARCHITECTURE.md, **/*.mermaid, **/*.drawio, diagram, architecture, c4, system design, mermaid)

385 stars

Best use case

common-architecture-diagramming is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Standards for creating clear, audience-appropriate C4 and UML architecture diagrams with Mermaid. Use when producing system context diagrams, container views, sequence diagrams, or updating ARCHITECTURE.md files. (triggers: ARCHITECTURE.md, **/*.mermaid, **/*.drawio, diagram, architecture, c4, system design, mermaid)

Teams using common-architecture-diagramming should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

  • You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

  • You only need a quick one-off answer and do not need a reusable workflow.
  • You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/common-architecture-diagramming/SKILL.md --create-dirs "https://raw.githubusercontent.com/HoangNguyen0403/agent-skills-standard/main/skills/common/common-architecture-diagramming/SKILL.md"

Manual Installation

  1. Download SKILL.md from GitHub
  2. Place it in .claude/skills/common-architecture-diagramming/SKILL.md inside your project
  3. Restart your AI agent — it will auto-discover the skill

How common-architecture-diagramming Compares

Feature / Agentcommon-architecture-diagrammingStandard Approach
Platform SupportNot specifiedLimited / Varies
Context Awareness High Baseline
Installation ComplexityUnknownN/A

Frequently Asked Questions

What does this skill do?

Standards for creating clear, audience-appropriate C4 and UML architecture diagrams with Mermaid. Use when producing system context diagrams, container views, sequence diagrams, or updating ARCHITECTURE.md files. (triggers: ARCHITECTURE.md, **/*.mermaid, **/*.drawio, diagram, architecture, c4, system design, mermaid)

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# Architecture Diagramming Standard

## **Priority: P1 (Standard)**

## Guidelines

- **Use C4 Model**: Context -> Container -> Component -> Code.
- **Audience-Centric**: Tailor abstraction (Execs vs. Devs).
- **Select Type**: Sequence (Protocol), ERD (Data), State (Lifecycle), Cloud (Infra). See [Selection](references/diagram-selection.md).
- **Explicit Labels**: Label every arrow (e.g., "Uses", "HTTPS").
- **Consistent Notation**: Cylinders=DB, Rectangles=Systems, Dashed=Async.
- **Metadata**: Title, Date, Version, Author.
- **Legend Mandatory**: Define all shapes/colors/styles.
- **Direction**: `graph LR` (Flow) or `graph TD` (Hierarchy).
- **Deployment**: Map containers to infrastructure.
- **Governance**: CRITICAL: Review [best-practices.md](references/best-practices.md) before starting.

See [implementation examples](references/implementation.md) for a C4 container diagram in Mermaid.

## Anti-Patterns

- **Mixed Levels**: DB columns in System Context.
- **Unlabeled Arrows**: Ambiguous relations.
- **Mystery Shapes**: Undefined in Legend.
- **Dead Ends**: Unconnected nodes.
- **Clutter**: >20 nodes/diagram.
- **Acronyms**: Undefined abbreviations.

## References

- [Diagram Selection](references/diagram-selection.md)
- [Cloud Architecture](references/cloud-architecture.md)
- [C4 Model Guide](references/c4-model.md)
- [Checklist](references/checklist.md)
- [Best Practices](references/best-practices.md)

Related Skills

spring-boot-architecture

385
from HoangNguyen0403/agent-skills-standard

Structure Spring Boot 3+ projects with feature packaging and clean layering. Use when structuring Spring Boot 3 projects, defining layers, or applying architecture patterns. (triggers: pom.xml, build.gradle, structure, layering, dto, controller, @RestController, @Service, @Repository, @Entity, @Bean, @Configuration)

react-native-architecture

385
from HoangNguyen0403/agent-skills-standard

Structure React Native projects with feature-first organization and separation of concerns. Use when structuring a React Native project or applying clean architecture patterns. (triggers: src/**/*.tsx, src/**/*.ts, app.json, feature, module, directory structure, separation of concerns, Expo, React Navigation, StyleSheet.create, react-native, mobile architecture)

nextjs-architecture

385
from HoangNguyen0403/agent-skills-standard

Structure Next.js projects with Feature-Sliced Design layers, domain-grouped slices, and strict import hierarchy. Use when organizing features into FSD layers, enforcing slice boundaries, or keeping page.tsx thin. (triggers: src/features/**, src/entities/**, src/widgets/**, FSD, Feature Sliced Design, slices, segments)

nestjs-architecture

385
from HoangNguyen0403/agent-skills-standard

Design decoupled, testable NestJS module boundaries with feature, core, and shared modules. Use when structuring module imports, creating feature modules, or enforcing separation of concerns in NestJS. (triggers: **/*.module.ts, main.ts, NestFactory, Module, Controller, Injectable)

laravel-clean-architecture

385
from HoangNguyen0403/agent-skills-standard

Implement Domain-Driven Design with typed DTOs, repository interfaces, and single-responsibility Action classes in Laravel. Use when creating domain folders, binding repository contracts in providers, or passing DTOs between layers. (triggers: app/Domains/**/*.php, app/Providers/*.php, domain, dto, repository, contract, adapter)

laravel-architecture

385
from HoangNguyen0403/agent-skills-standard

Enforce core architectural standards for scalable Laravel applications. Use when structuring controllers, service layers, action classes, Form Requests, or Service Container bindings in Laravel projects. (triggers: app/Http/Controllers/**/*.php, routes/*.php, controller, service, action, request, container)

ios-architecture

385
from HoangNguyen0403/agent-skills-standard

Apply MVVM, Coordinators, and Clean Architecture (VIP/VIPER) in iOS apps. Use when applying MVVM, Coordinators, or VIP/VIPER architecture in iOS apps. (triggers: **/*ViewModel.swift, **/*Coordinator.swift, **/*ViewController.swift, MVVM, Coordinator, ViewState, Output, Input)

golang-architecture

385
from HoangNguyen0403/agent-skills-standard

Structure Go projects with Clean Architecture and standard layout conventions. Use when structuring Go projects or applying Clean Architecture in Go. (triggers: go.mod, internal/**, architecture, structure, folder layout, clean arch, dependency injection)

flutter-layer-based-clean-architecture

385
from HoangNguyen0403/agent-skills-standard

Enforce inward dependency flow, pure domain layers, and DTO-to-entity mapping in Flutter DDD architecture. Use when structuring lib/domain/, lib/infrastructure/, lib/application/, or lib/presentation/ layers, defining repository interfaces, or wiring BLoCs with get_it. (triggers: lib/domain/**, lib/infrastructure/**, lib/application/**, dto, mapper, Either, Failure)

flutter-feature-based-clean-architecture

385
from HoangNguyen0403/agent-skills-standard

Organize Flutter apps with modular feature-based clean architecture. Use when creating or modifying any file under lib/features/ including domain entities, repositories, data sources, or screens. (triggers: lib/features/**, feature, domain, infrastructure, application, presentation)

common-observability

385
from HoangNguyen0403/agent-skills-standard

Enforce structured JSON logging, OpenTelemetry distributed tracing, and RED metrics across backend services. Use when adding request correlation, setting up tracing spans, defining SLO burn-rate alerts, or instrumenting middleware. (triggers: **/*.service.ts, **/*.handler.ts, **/*.middleware.ts, **/*.interceptor.ts, **/*.go, **/*.java, **/*.kt, **/*.py, logging, tracing, metrics, opentelemetry, observability, slo)

common-mobile-ux-core

385
from HoangNguyen0403/agent-skills-standard

Enforce universal mobile UX principles for touch-first interfaces including touch targets, safe areas, and mobile-specific interaction patterns. Use when building mobile screens, handling touch interactions, or validating safe area compliance. (triggers: **/*_page.dart, **/*_screen.dart, **/*_view.dart, **/*.swift, **/*Activity.kt, **/*Screen.tsx, mobile, responsive, SafeArea, touch, gesture, viewport)