Diagrams: Meet the 8 Mermaids of Sapience: Turning Ideas into Diagrams
Learn the power of Mermaid under the hood with Sapience.
Diagramming in Sapience
Everything you need to know about the Diagramming Skill
While Sapience doesn’t hallucinate, it does have a few visual superpowers — including what we call the “eight mermaids.” No fish, no scales. Just arrows, connectors, and structured flows that turn ideas into clear diagrams.
Under the hood, Sapience uses Mermaid.js syntax to generate clean, professional diagrams, without requiring you to learn diagramming tools or design software.
That’s Sapience shorthand for this: if you can describe it, Sapience can diagram it.
Sapience supports generating a wide range of diagrams directly inside your conversations. This is especially valuable for teams working on process improvement, operational excellence, system design, and structured thinking.
Supported Diagram Types
1. Flowchart (Most Versatile)
Flowcharts are the most versatile diagram type, used to visualize processes, decisions, and workflows. They show the sequence of steps and the relationships between them using various node shapes and connecting arrows.
Best Used For:
- Process documentation — Map out business processes, SOPs, or operational workflows
- Decision trees — Visualize branching logic and decision points
- System architecture — Show how components connect at a high level
- Troubleshooting guides — Create diagnostic flowcharts for support teams
- Onboarding documentation — Illustrate step-by-step procedures
Key Syntax Elements
Element | Syntax | Purpose |
Direction | TD, LR, BT, RL | Top-down, Left-right, Bottom-top, Right-left |
Rectangle | [text] | Standard process step |
Rounded | (text) | Start/end or soft steps |
Diamond | {text} | Decision point |
Cylinder | [(text)] | Database/storage |
Circle | ((text)) | Connector or event |
Arrow | --> | Flow direction |
Labeled Arrow | -->|label| | Conditional flow |
Example Use Cases
- Customer Support Escalation Flow — Document when and how tickets escalate
- Approval Workflow — Show the path from request to approval/rejection
- Data Pipeline — Visualize ETL processes from source to destination
- User Registration Flow — Map the steps a new user takes to sign up
2. Sequence Diagram
Sequence diagrams show interactions between participants (systems, users, services) over time. They're read top-to-bottom, with each horizontal arrow representing a message or call between participants.
When to Use
- API documentation — Show request/response flows between services
- User journey mapping — Illustrate how users interact with systems
- System integration — Document how multiple systems communicate
- Debugging complex flows — Trace the sequence of events in an issue
- Authentication flows — Document OAuth, SSO, or login sequences
Key Syntax Elements
Element | Syntax | Purpose |
Participant | participant A as Alice | Define an actor with alias |
Solid arrow | ->> | Synchronous call |
Dotted arrow | -->> | Response/async |
Solid with X | -x | Lost message |
Note | Note over A,B: text | Add annotation |
Loop | loop Description ... end | Repeated sequence |
Alt | alt Condition ... else ... end | Conditional paths |
Example Use Cases
- OAuth 2.0 Flow — Document the authorization code grant flow
- Order Processing — Show how an order moves through payment, inventory, and shipping
- Microservice Communication — Map how services call each other for a feature
- Webhook Integration — Document the sequence when a webhook fires
3. Class Diagram
Class diagrams represent the structure of a system by showing classes, their attributes, methods, and the relationships between them. They're fundamental to object-oriented design and software architecture documentation.
When to Use
- Software design — Document object models before or after implementation
- Domain modeling — Map business entities and their relationships
- API schema documentation — Show data structures and their connections
- Database ORM mapping — Visualize how code models map to tables
- Technical specifications — Communicate system structure to developers
Key Syntax Elements
Element | Syntax | Purpose |
Class | class ClassName { } | Define a class |
Attribute | +String name | Public attribute |
Method | +getName() | Public method |
Inheritance | Parent <|-- Child | Child extends Parent |
Composition | Whole *-- Part | Part cannot exist without Whole |
Aggregation | Container o-- Item | Item can exist independently |
Association | A --> B | A uses B |
Example Use Cases
- E-commerce Domain Model — Show Product, Order, Customer, Payment relationships
- CRM Entity Structure — Document Contact, Account, Opportunity, Activity
- API Response Schema — Visualize nested JSON object structures
- Plugin Architecture — Show base classes and extension points
4. State Diagram
State diagrams show the different states an entity can be in and the transitions between those states. They're ideal for documenting lifecycles, status workflows, and finite state machines.
When to Use
- Order/ticket lifecycles — Document status progression
- Approval workflows — Show states from draft to approved/rejected
- User account states — Active, suspended, pending verification, etc.
- Document workflows — Draft, review, published, archived
- System states — Running, paused, error, maintenance
Key Syntax Elements
Element | Syntax | Purpose |
Initial state | [*] | Starting point |
Final state | [*] | Ending point (context-dependent) |
State | StateName | A state |
Transition | State1 --> State2 | Move between states |
Labeled transition | State1 --> State2: trigger | Transition with event |
Composite state | state CompositeState { } | Nested states |
Example Use Cases
- Support Ticket Lifecycle — New → Assigned → In Progress → Resolved → Closed
- Invoice States — Draft → Sent → Viewed → Paid → Overdue
- Employee Onboarding — Offer → Accepted → Background Check → Active
- Feature Flag States — Off → Canary → Percentage Rollout → Full → Deprecated
5. Entity Relationship (ER) Diagram
ER diagrams show database tables (entities) and the relationships between them, including cardinality (one-to-one, one-to-many, many-to-many). Essential for database design and data modeling.
When to Use
- Database schema design — Plan tables before implementation
- Data model documentation — Document existing database structures
- Integration planning — Understand data relationships for migrations
- API design — Map out resource relationships for REST/GraphQL APIs
- Business analysis — Model business entities and their connections
Key Syntax Elements
Element | Syntax | Meaning |
Entity | ENTITY_NAME | A table/entity |
Exactly one | || | One and only one |
Zero or one | o| | Optional (0 or 1) |
One or more | }| | At least one |
Zero or more | }o | Any number (0+) |
Relationship | ENTITY1 ||--o{ ENTITY2 : label | Connection with cardinality |
Example Use Cases
- SaaS Multi-tenant Schema — Organization → Users → Resources hierarchy
- E-commerce Database — Products, Orders, Customers, Inventory
- CMS Data Model — Posts, Authors, Categories, Tags, Comments
- Healthcare Records — Patients, Providers, Appointments, Prescriptions
6. Gantt Chart
Gantt charts visualize project schedules, showing tasks along a timeline with their durations, dependencies, and groupings into phases or sections.
When to Use
- Project planning — Lay out project phases and milestones
- Sprint planning — Visualize work across a sprint or quarter
- Resource allocation — See who's working on what and when
- Dependency tracking — Show which tasks block others
- Executive reporting — Communicate timelines to stakeholders
Key Syntax Elements
Element | Syntax | Purpose |
Title | title Project Name | Chart title |
Date format | dateFormat YYYY-MM-DD | How dates are parsed |
Section | section Phase Name | Group tasks |
Task | Task Name: id, start, duration | Define a task |
Dependency | Task: id, after other_id, duration | Task depends on another |
Milestone | Milestone: milestone, m1, date, 0d | Zero-duration marker |
Example Use Cases
- Product Roadmap — Quarterly feature delivery timeline
- Marketing Campaign — Content creation, review, and publish schedule
- System Migration — Phases from planning to cutover to decommission
- Event Planning — Venue, speakers, marketing, registration timeline
7. Pie Chart
Pie charts show proportional data as slices of a circle. They're best for displaying how parts make up a whole, with a small number of categories.
When to Use
- Budget allocation — Show spending by category
- Market share — Visualize competitive landscape
- Survey results — Display response distributions
- Resource distribution — Team allocation, time spent by activity
- Portfolio composition — Investment or product mix
Key Syntax Elements
Element | Syntax | Purpose |
Title | pie title Chart Title | Name the chart |
Slice | "Label": value | Each category and its value |
Example Use Cases
- Department Budget — Visualize spending across cost centers
- Customer Segments — Show revenue by customer type
- Time Tracking — Display hours by project or activity
- Survey Responses — Satisfaction ratings distribution
8. Mind Map
Mind maps display hierarchical information radiating from a central concept. They use indentation to show parent-child relationships and are excellent for brainstorming and organizing ideas.
When to Use
- Brainstorming sessions — Capture and organize ideas
- Knowledge organization — Structure complex topics
- Meeting notes — Hierarchical capture of discussion points
- Feature planning — Break down a feature into components
- Learning/training — Organize educational content
Key Syntax Elements
Element | Syntax | Purpose |
Root | root((Central Topic)) | Center of the mind map |
Branch | Indented text | First-level topics |
Sub-branch | Further indented | Nested topics |
Shapes | ((circle)), [square], (rounded) | Different node styles |
Example Use Cases
- Strategic Planning — Break down company objectives into initiatives
- Content Strategy — Organize topics, subtopics, and content pieces
- Product Feature Breakdown — Decompose epics into stories
- Onboarding Curriculum — Structure training modules and lessons
Quick Reference: When to Use Each Diagram
Diagram Type | Best For | Key Question It Answers |
Flowchart | Processes, decisions | "What are the steps and decision points?" |
Sequence | Interactions over time | "Who talks to whom, and in what order?" |
Class | Object structures | "What are the components and their relationships?" |
State | Status transitions | "What states can this be in, and how does it change?" |
ER Diagram | Data models | "How is the data structured and related?" |
Gantt | Project timelines | "When does each task happen and how long?" |
Pie Chart | Proportions | "What's the breakdown/distribution?" |
Mind Map | Concept hierarchies | "How do these ideas relate and branch?" |
Best Practices for All Diagrams
- Keep it simple — Aim for 15-20 nodes maximum; split complex diagrams into multiple views
- Use meaningful labels —
UserAuthenticationis better thanA1
- Quote special characters — Any text with apostrophes, parentheses, or colons needs double quotes
- Be consistent — Pick one direction (TD/LR) and stick with it
- Add context — Include a brief explanation before or after the diagram
- Test the flow — Mentally trace through the diagram to verify logic