5.2 KiB
5.2 KiB
SMOA Diagram Standards
Version: 1.0
Last Updated: 2024
Status: Active
Purpose
This document establishes standards for creating diagrams in SMOA documentation to ensure consistency, clarity, and maintainability.
Diagram Types
Architecture Diagrams
- System architecture
- Component architecture
- Module architecture
- Deployment architecture
Flow Diagrams
- Process flows
- Data flows
- User flows
- Integration flows
Sequence Diagrams
- API interactions
- Authentication flows
- Transaction flows
Entity Relationship Diagrams
- Database schema
- Data models
Tools
Primary Tools
- PlantUML - Text-based diagramming (preferred for version control)
- Mermaid - Markdown-based diagramming
- Draw.io - Visual diagramming (for complex diagrams)
Tool Selection
- Use PlantUML for architecture and sequence diagrams
- Use Mermaid for simple flow diagrams in Markdown
- Use Draw.io for complex visual diagrams
Diagram Standards
Naming Conventions
- Use kebab-case for diagram files
- Include diagram type in name (e.g.,
system-architecture.puml) - Use descriptive names (e.g.,
authentication-flow.puml)
File Organization
- Store diagrams in
docs/architecture/diagrams/ - Organize by category (architecture, flows, sequences)
- Include source files (
.puml,.mmd) and rendered images (.png,.svg)
Diagram Size
- Keep diagrams readable (max 1920x1080 for screens)
- Break complex diagrams into multiple diagrams
- Use zoom/pan for large diagrams
Colors and Styling
- Use consistent color scheme
- Follow accessibility guidelines (color contrast)
- Use standard shapes and symbols
- Include legends for complex diagrams
Architecture Diagrams
System Architecture
- Show high-level system components
- Show external systems
- Show data flows
- Include security boundaries
Component Architecture
- Show component relationships
- Show interfaces
- Show dependencies
- Include technology stack
Module Architecture
- Show module structure
- Show module dependencies
- Show module interfaces
- Include module responsibilities
Flow Diagrams
Process Flows
- Use standard flowchart symbols
- Show decision points clearly
- Include error paths
- Show start and end points
Data Flows
- Show data sources and destinations
- Show data transformations
- Include data formats
- Show security boundaries
User Flows
- Show user actions
- Show system responses
- Include decision points
- Show error handling
Sequence Diagrams
API Interactions
- Show all participants
- Show message flows
- Include timing information
- Show error scenarios
Authentication Flows
- Show authentication steps
- Show security boundaries
- Include token flows
- Show error handling
Entity Relationship Diagrams
Database Schema
- Show all entities
- Show relationships
- Include cardinality
- Show primary/foreign keys
Data Models
- Show data structures
- Show relationships
- Include constraints
- Show inheritance
Diagram Best Practices
Clarity
- Keep diagrams simple and focused
- Avoid clutter
- Use clear labels
- Include legends
Consistency
- Use consistent symbols
- Use consistent colors
- Use consistent layout
- Follow naming conventions
Maintainability
- Use text-based tools when possible
- Version control diagram sources
- Document diagram assumptions
- Update diagrams with code changes
Accessibility
- Use high contrast colors
- Include text descriptions
- Use alt text for images
- Follow WCAG guidelines
Diagram Templates
System Architecture Template (PlantUML)
@startuml system-architecture
!include <tupadr3/common>
!include <tupadr3/font-awesome/users>
title System Architecture
package "External Systems" {
[External System 1]
[External System 2]
}
package "SMOA Application" {
[Module 1]
[Module 2]
[Module 3]
}
[External System 1] --> [Module 1]
[Module 1] --> [Module 2]
[Module 2] --> [Module 3]
[Module 3] --> [External System 2]
@enduml
Sequence Diagram Template (PlantUML)
@startuml sequence-example
title Example Sequence Diagram
actor User
participant "SMOA App" as App
participant "API Server" as API
database "Database" as DB
User -> App: Action
App -> API: Request
API -> DB: Query
DB --> API: Result
API --> App: Response
App --> User: Display
@enduml
Diagram Review Checklist
Before including a diagram in documentation:
- Diagram follows naming conventions
- Diagram is clear and readable
- Diagram uses consistent styling
- Diagram includes necessary details
- Diagram is not overly complex
- Diagram has appropriate size
- Diagram includes caption/description
- Diagram is referenced in text
- Diagram source is version controlled
- Diagram is accessible (color contrast, alt text)
Resources
PlantUML
- Documentation: https://plantuml.com/
- Examples: https://real-world-plantuml.com/
Mermaid
- Documentation: https://mermaid.js.org/
- Live Editor: https://mermaid.live/
Draw.io
- Website: https://app.diagrams.net/
- Templates: https://www.diagrams.net/blog/templates
Document Owner: Documentation Lead
Last Updated: 2024
Next Review: Quarterly