Buy Me A CoffeeEvery codebase tells a story, but not every story is best told in code. Whether you are onboarding a new teammate, designing a system, or debugging a production incident, the right diagram can communicate in seconds what paragraphs of prose cannot. Here are five diagram types that belong in every developer's toolkit, along with practical Mermaid syntax you can paste into SimpleMermaid right now.
1. Flowcharts
When to Use
Flowcharts are the Swiss Army knife of diagrams. Reach for one whenever you need to map out decision logic, document a business process, or explain a user flow to non-technical stakeholders. They are ideal for code review discussions, onboarding documentation, and sprint planning sessions where everyone needs to see the same path through a system.
Mermaid Example
flowchart TD
A[User Submits Form] --> B{Valid Input?}
B -- Yes --> C[Process Payment]
B -- No --> D[Show Errors]
C --> E{Payment OK?}
E -- Yes --> F[Send Confirmation]
E -- No --> G[Retry / Alert User]
D --> APro Tip: Use TD (top-down) for processes that flow linearly, and LR (left-right) when you want to emphasize parallel branches. Add subgraphs to group related nodes and keep large flowcharts readable.
2. Sequence Diagrams
When to Use
Sequence diagrams shine when you need to illustrate the order of messages between services, APIs, or components. They are indispensable for documenting REST or GraphQL interactions, OAuth flows, webhook handshakes, and microservice choreography. If you have ever written "then service A calls service B which calls service C" in a design doc, a sequence diagram says it better.
Mermaid Example
sequenceDiagram
participant Client
participant API Gateway
participant Auth Service
participant Database
Client->>API Gateway: POST /login
API Gateway->>Auth Service: Validate credentials
Auth Service->>Database: Query user record
Database-->>Auth Service: User data
Auth Service-->>API Gateway: JWT token
API Gateway-->>Client: 200 OK + tokenPro Tip: Use solid arrows (->>) for synchronous calls and dashed arrows (-->>) for responses. Add activate and deactivate blocks to show when a participant is actively processing, making it obvious where latency lives.
3. Class Diagrams
When to Use
Class diagrams map out the structure of your object-oriented code: classes, interfaces, attributes, methods, and the relationships between them. They are essential during system design when deciding on inheritance hierarchies, planning a refactor to break apart a god class, or documenting a library's public API. Even in non-OOP languages, they help visualize module relationships.
Mermaid Example
classDiagram
class Animal {
+String name
+int age
+makeSound() void
}
class Dog {
+String breed
+fetch() void
}
class Cat {
+bool isIndoor
+purr() void
}
Animal <|-- Dog
Animal <|-- Cat
Dog --> "1..*" Toy : plays withPro Tip: Prefix members with + (public), - (private), or # (protected) to document visibility. Use relationship arrows like <|-- for inheritance, *-- for composition, and o-- for aggregation to precisely describe how classes interact.
4. Entity Relationship Diagrams (ERDs)
When to Use
ERDs are your go-to diagram for database design. Before writing a migration, sketch out your tables, columns, and relationships. They help you spot normalization issues, plan indexes, and communicate your data model to DBAs and backend developers. An ERD created before writing SQL will save hours of refactoring later.
Mermaid Example
erDiagram
USERS ||--o{ ORDERS : places
USERS {
int id PK
string email
string name
datetime created_at
}
ORDERS ||--|{ ORDER_ITEMS : contains
ORDERS {
int id PK
int user_id FK
decimal total
string status
}
PRODUCTS ||--o{ ORDER_ITEMS : "included in"
PRODUCTS {
int id PK
string name
decimal price
}
ORDER_ITEMS {
int id PK
int order_id FK
int product_id FK
int quantity
}Pro Tip: Learn the cardinality notation: ||--o{ means "one to zero-or-many" and ||--|{ means "one to one-or-many." Always label your relationships with a verb phrase so anyone reading the diagram can understand the association instantly. Check out our in-depth ERD guide for more.
5. State Diagrams
When to Use
State diagrams model how an entity transitions between discrete states in response to events. They are perfect for documenting order lifecycles (pending, paid, shipped, delivered), UI component states (idle, loading, error, success), authentication flows, and any finite state machine in your code. If your business logic contains a lot of "if status equals X, then..." conditionals, a state diagram will clarify the design.
Mermaid Example
stateDiagram-v2
[*] --> Draft
Draft --> Review : Submit
Review --> Approved : Approve
Review --> Draft : Request Changes
Approved --> Published : Publish
Published --> Archived : Archive
Archived --> Draft : Restore
Published --> [*]Pro Tip: Use [*] for start and end states. In complex diagrams, nest states with state "Parent" { ... } to show composite states, like a "Review" state that internally has sub-states for "Technical Review" and "Legal Review."
Bringing It All Together
These five diagram types cover the vast majority of scenarios a developer encounters, from whiteboarding a feature to writing production documentation:
- Flowcharts for processes and decision logic
- Sequence diagrams for inter-service communication
- Class diagrams for code structure and relationships
- ERDs for database schema design
- State diagrams for lifecycle and status modeling
The best part? Every example above is valid Mermaid syntax. You do not need to install software or drag shapes around a canvas. Just type your diagram as code, see it render in real time, and share it with a link. That is exactly what SimpleMermaid is built for.
Diagrams-as-code means your visual documentation lives alongside your source code. It can be version-controlled, diff'd in pull requests, and kept in sync with the system it describes. If you have not yet adopted a diagrams-as-code workflow, there has never been a better time to start.
Try These Diagrams Now
Paste any example above into SimpleMermaid and see it render instantly. No signup, no download.
Open the Editor